“Design depends largely on constraints.” — Charles Eames
Thursday, 30 November 2006
One of the perceived deficiencies of JSON is that it doesn’t have a schema language. I say “perceived” because the problems that a schema language brings often outweigh the benefits; after all, look at the mess that XML Schema is in.
Even that said, schemas are useful for documentation and QA. So, I’m finding the work that Robert Cerny has done very interesting; it’s basically schemas for JSON, in JSON (or very nearly so). For example, here’s the schema for the cerny doc format;
CERNY.require("CERNY.js.doc.Schema",
"CERNY.text.DateFormat",
"CERNY.schema");
arrayOf = CERNY.schema.arrayOf;
optional = CERNY.schema.optional;
nonEmptyString = CERNY.schema.nonEmptyString;
isoDate = CERNY.schema.isoDate;
CERNY.js.doc.Parameter = {
name: nonEmptyString,
documentation: nonEmptyString
};
CERNY.js.doc.Function = {
name: nonEmptyString,
documentation: arrayOf(nonEmptyString),
parameters: arrayOf(CERNY.js.doc.Parameter),
returnValue: optional(nonEmptyString)
};
CERNY.js.doc.HistoryEntry = {
date: isoDate,
entry: nonEmptyString
};
CERNY.js.doc.Script = {
name: nonEmptyString,
author: nonEmptyString,
creationDate: isoDate,
modificationDate: optional(isoDate),
documentation: arrayOf(nonEmptyString),
history: arrayOf(CERNY.js.doc.HistoryEntry),
functions: arrayOf(CERNY.js.doc.Function),
uses: arrayOf(nonEmptyString)
};
Pretty easy. The big questions are whether it hits the 80/20 point (at first glance, I think it might, but I haven’t played with it yet), and whether it avoids the versioning nightmare that trapped XML Schema (again, looks good so far, but it’s early days).
Also, CERNY.require’s relationship to URIs is very, very interesting…
Filed under: Web, Web Services, XML
I've been thinking about the need for JSON schemas recently. When you're dealing with JSON that is generated outside your control they could be really useful as a sanity check, so your code doesn't later fall apart due to a missing key that you were expecting.
It sems odd to have a JSON schema language that isn't itself pure JSON though.
Thursday, November 30 2006 at 4:52 PM +10:00
I was looking for a JSON Schema tool a few weeks ago and found this: http://www.kuwata-lab.com/kwalify/
I'd prefer a pure-JSON tool, though.
Thursday, November 30 2006 at 6:06 PM +10:00
I've actually started using kwalify for some JSON schema validation. It's nice, because I happen to use YAML sometimes (and all of the JSON I produce is YAML compatible). Note that it's written in YAML (which can also be JSON).
Thursday, November 30 2006 at 8:27 PM +10:00
Cool! I can't get too excited about strong typing, but at least knowing a given field maybe repeated is very useful metadata. I envisage that one use for the schema patterns is in mapping from XML to JSON .. so an XSD to this could be an interesting project.
Friday, December 1 2006 at 8:29 AM +10:00
Also, it appears that Cerny's implementation is just javascript, whereas kwalify has several implementations (and javascript could easily be added).
Friday, December 1 2006 at 4:37 PM +10:00
Yeah, that seems to be the main limitation. Pure JSON would be really nice, but it looks very difficult to reach that, on the face of it. Human-readability is also really high on my list, because my main use case is documentation, not runtime validation.
Friday, December 1 2006 at 8:43 PM +10:00
If you're just going to use it for documentation, why do you need a computable format, anyway? Why not just a text outline with some prose?
Friday, December 1 2006 at 10:09 PM +10:00
A Cerny schema *is* executable JavaScript code. Some part of me thinks as well, that something pure JSON would be more beneficial. My solution offers on the other hand (almost) unlimited options for expressing constraints on objects. Documents (arrays) seem to be a bit harder to do. Being in the need of a JavaScript interpreter for validation is a disadvantage, but in times of web services, one, that is acceptable. I can picture a solution where one sends a POST request to the URL of a Schema and receives a validation report, this might be good enough for occasional validation during development.
I agree with Douglas Crockford [1] that the code has to ensure it can work on the data, but i don't want my *schema* scattered in my source code. I want it on one place. The resulting code is more readable due to less ifs. And i have the option to turn off validation, if i want to, e.g if i encounter performance problems.
[1] http://tech.groups.yahoo.com/group/json/message/559
Wednesday, December 6 2006 at 10:57 PM +10:00
As documentation this reverses it -- Script is the real thing being described, but it comes last. It also seems like you could describe it easily enough in a non-formal way like:
Doc = ['...', ...]
Script = {
. . name: '...',
. . author: '...',
. . creationDate: 'YYYY-MM-DD',
. . [modificationDate: 'YYYY-MM-DD'],
. . documentation: Doc,
. . history: [{
. . . . date: 'YYYY-MM-DD',
. . . . entry: '...'
. . . . }, ...],
. . functions: [{
. . . . name: '...',
. . . . documentation: Doc,
. . . . parameters: [{name: '...', documentation: Doc}, ...],
. . . . [returnValue: '...']
. . . . }, ...],
. . uses: Doc
. . }Anyway, it's not that hard to create a useful enough schema that way. It's not quite JSON, sadly, because optional elements go outside the syntax. I'm not sure what example-based syntax could look like to express that, without being long-winded and not very example-based anymore. Oh, and the ellipsis. Hrm.
Thursday, December 7 2006 at 7:48 AM +10:00
I put up an introduction to the Cerny schema concept [1]. Any suggestions and feedback is welcome. For developers who are in the need of an interception mechanism, Cerny.js offers a solution for that as well. You will find more about it at [2].
[1] http://www.cerny-online.com/cerny.js/documentation/guides/schema
[2] http://www.cerny-online.com/cerny.js/documentation/guides/interception
Tuesday, February 20 2007 at 7:27 PM +10:00
I am going to start working on proposal for JSON-based JSON Schema (in language-neutral JSON). I would to have collaboration, input and feedback in creating a viable JSON Schema. I will be working on it at JSON.com.
Kris
Friday, September 28 2007 at 3:05 PM +10:00
We have had collaboration from a number of people to put together a JSON Schema proposal, which you can take a look at here: http://www.json.com/json-schema-proposal/
Friday, October 12 2007 at 1:08 PM +10:00