mark nottingham

Schema for JSON

Thursday, 30 November 2006

HTTP APIs

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…


12 Comments

Simon Willison said:

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 AM

Chris Nokleberg said:

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 AM

ryan king said:

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 AM

ryan king said:

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 AM

Paul Downey said:

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

ryan king said:

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 AM

Robert Cerny said:

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 AM

Ian Bicking said:

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

Robert Cerny said:

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 AM

Kris Zyp said:

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 AM

Kris Zyp said:

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 AM