A colleague and I are hashing through the architecture of a website we're going to be building. One of the main requirements is that site developers/maintainers will be able to create these re-usable templates/widgets that they want to be able to re-use and display with different data on different pages.
For example, there could be a carousel widget with a title and an array
of slides which each have a text blurb and image URL. This would require
a developer defining a schema describing all the fields and their
datatypes, which must all belong to a list of known valid datatypes,
such as string, text, image, etc.
The requirements of our app call for such a schema to be written in
JSON. We also provide a mechanism by which a template can be previewed
by supplying it a sample_data.json which will render the mustache HTML
with the provided JSON dictionary of sample_data.
We will be providing the developers a sample template that they can use
and modify to create their own templates. There will be an
index.html.mustache, a schema.json, and a sample_data.json. Our
disagreement is how we ought to signify single fields (e.g. the title
field for the whole template/widget) vs. repeatable fields (e.g. the
slides to be used in a carousel).
One of us thinks the following would be most intuitive:
{
"title": "string",
"slides": {
"name": "string",
"body": "text",
"image": "image"
}
}The idea is that a key is the name of the field, and the value is the one of the predefined known datatypes, or it is an Object, which signifies a repeatable set of fields.
The other finds it confusing that we would be signifying a repeatable
field set via an Object (such as the object value of the slides key)
and would prefer we supply the value as a single-element array:
{
"title": "string",
"slides": [{
"name": "string",
"body": "text",
"image": "image"
}]
}That way, the developers creating templates could easily look at a
schema and think "Ah, this will be an array of a variable number of
elements." As an added bonus, the schema object could itself be used as
a valid dictionary object to pass to the mustache when it's being
rendered; title would evaluate to "string", and even the slides
array could be properly iterated over in the mustache template without
any modification to the schema JSON to make it conform to a dictionary
data object.
The first developer thinks that this is ultimately misleading, and particularly jarring that the to signify that a fieldset is repeatable, you must supply an Array that is always, exactly one element. This developer thinks that the other is improperly taking advantage of a coincidence that the JSON schema happens to be a valid data object that conforms to itself, while the developer in favor of this idea thinks that this is to be expected and that it'd be highly confusing to the people maintaining/creating the templates/widgets that in one JSON file (the schema) an object would be used to represent repeatable data, and in the other (the context object that should conform to the schema), an array is supplied for the repeatable data.
Who is crazy here? Is there an obvious third way that'd be superior?
Heya, I'm part 2 of this discussion, arguing for example 2:
Example 1: Objects in the schema are converted into arrays of themselves when returned to the template:
Example 2: Objects in schema match the structure of the data returned
For me, it boils down to this:
Example 1 involves a special case rule that has to be communicated. Look at the two examples without reading the text: Example 2 you're looking at the actual structure of the data to be returned. Example 1, you might think you are - but you don't know that objects will actually be replaced with arrays.