How to describe JSON data in a spec?

Question

What is the best way to describe JSON data in a spec?

In the past I've used examples with 'wordy' descriptions, but it feels imprecise.

There seems to be a nascent JSON schema standard, but it doesn't look like a hugely active project. Any other ways?

---

(Update) After thinking about this for several days I like bmargulies suggestion around using a conversion convention. Since the JSON documents in this case our coming out of .NET web services I am going to simply document the schema with C# class syntax. This may not be totally rigourous, but everyone involved will understand it and coupled with the examples will get the message across as quickly as possible.

Answer 1

How about using some kind of extended BNF?

PERSON <- { "firstname": FIRSTNAMES, "lastname": LASTNAME, "age": AGE, "version": VERSION, "parents" <- PARENTS }

FIRSTNAMES <- [ FIRSTNAME+ ]

FIRSTNAME <- STRING

LASTNAME <- STRING

PARENTS <- [ PERSON{0,2} ]

AGE <- INTEGER

VERSION <- 1 | 2

You'd have to define the meaning of atomic type descriptions like INTEGER and STRING somewhere. If you wanted to add non-hardcoded keys for dictionaries, you would define that as follows:

BREADLOOKUP <- { (TYPE : HOWMANY)+ }

TYPE <- "white" | "dark" | "french" | "croissant"

HOWMANY <- POSITIVE-INTEGER

This would allow stuff like { "white": 5, "french": 2 }

Since both regular expressions and BNF are pretty well known, this might be an easy way to go. ?, +, *, {n}, {min,max} would be easy ways to specify a number of elements (taken from regexes) and the rest is pretty much pure BNF.

If you did that rigorously enough, it might even be parsable for a validator.

Answer 2

You could combine a W3C XML Schema, or some less ugly schema like RelaxNG, with conversion conventions.