What do you think of JSON for documenting data structures in this project? http://code.google.com/apis/tasks/v1/using.html http://code.google.com/apis/tasks/v1/

What do you think of JSON for documenting data structures in this project? http://code.google.com/apis/tasks/v1/using.html http://code.google.com/apis/tasks/v1/using.html (scroll down for the "Protocol" sections; there are about 10) 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.