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

I would recommend my js-schema JavaScript library. The primary motivation behind it was the same what you describe in the question. It is a simple and easy to understand notation to describe JSON schemas (or specification, if you want).

An example schema described in JSON Schema:

{   "type":"object",   "properties":{     "id":{       "type":"number",       "required":true     },     "name":{       "type":"string",       "required":true     },     "price":{       "type": "number",       "minimum":0,       "required":true     },     "tags":{       "type":"array",       "items":{         "type":"string"       }     }   } } 

and the same schema description with js-schema:

{   "id"    : Number,   "name"  : String,   "price" : Number.min(0),   "?tags" : Array.of(String) } 

The library is able to validate object against schemas, generate random objects conforming to a given schema, and serialize/deserialize to/from JSON Schema.

Answer 2

I know this is an older question, but it might be useful to someone else: When looking for methods to describe JSON-data I stumbled upon Orderly. Here's the abstract right of the front page:

Orderly is a textual format for describing JSON. Orderly can be compiled into JSONSchema. It is designed to be easy to read and write.

I can agree with that, but I have only tried it with relatively simple structures so far.