So, I saw the PDF John posted discussing JSON format ideas. Ian and
Jon, you rock. It is a great document and excellent ideas. Most of it
makes good sense to me and, I'm sure that, as I reread and understand
better, I will love even more.
That said, there is one fundamental detail I do not love:
authors: {
'#contains': 'author',
'#items': [{ '#value': 'John Smith' }, { '#value': 'Dave Jones' }]
}
First
reason is that the label 'authors' is plural but contains only one
thing. In my opinion, things named plural should always be arrays.
Second is that I envision a line of code like:
const firstAuthor = inData.authors["#item"][0]["#value"];
Looks a lot like C# to me, low signal to noise ratio.
In
my other Javascript life, we would be inclined to use inflection, i.e.,
the assumption that 'authors' has elements with an implied name of
'author' and vice versa. I can understand that our XML roots make this
difficult to accept.
Consequently, I am inclined toward the everything is an object (if it's not a list) approach. EG,
authors: [
{ author: 'John Smith', '@type': 'bigshot' },
{ author: 'Dave Jones', '@type': 'contributor' }
]
This
provides a data structure that mentions the word 'author' the same
number of times as does the XML. That it also provides room for
attributes is good. This seems nicer to me:
const firstAuthor = inData.authors[0].author;
I
don't know if this can be expressed properly with openAPI or if it
violates some other rule of interaction with XML. I do know that, as a
Javascript programmer, I would rather use the form I suggest.