They're using JSON to describe sets of possible JSON instances, using conventions of "..." to represent other items in a list; and italics to represent variables (though not always: example text such as "My Task" is used for some variables).
Perhaps a shell-style convention, like $taskListID and ${My Task} would be clearer? It's going outside the JSON syntax, but so is "..." - and obviously extra-linguistic constructs help alert the reader
that it isn't part of the instance syntax (like italics).
I've looked at some "JSON schema" proposals, but they take the same meta-approach as XML Schema, which somehow seems even worse applied to JSON.
Regarding the actual format, they the kind attribute (kind="tasks#taskList") like a class. Since it defines the type of the message, maybe it would be clearer if it were distinguished in some way (like XML tags: <tasks#taskList> - invalid, I know).
disclaimer: I don't mean to rag on these guys - their focus is Google Tasks, not a schema for JSON. It's just that it's very well documented, and so it's a clear example of using JSON as a schema. This issue will become more important over time.
They're using JSON to describe sets of possible JSON instances, using conventions of "..." to represent other items in a list; and italics to represent variables (though not always: example text such as "My Task" is used for some variables).
Perhaps a shell-style convention, like $taskListID and ${My Task} would be clearer? It's going outside the JSON syntax, but so is "..." - and obviously extra-linguistic constructs help alert the reader that it isn't part of the instance syntax (like italics).
I've looked at some "JSON schema" proposals, but they take the same meta-approach as XML Schema, which somehow seems even worse applied to JSON.
Regarding the actual format, they the kind attribute (kind="tasks#taskList") like a class. Since it defines the type of the message, maybe it would be clearer if it were distinguished in some way (like XML tags: <tasks#taskList> - invalid, I know).
disclaimer: I don't mean to rag on these guys - their focus is Google Tasks, not a schema for JSON. It's just that it's very well documented, and so it's a clear example of using JSON as a schema. This issue will become more important over time.