Syntax for documenting JSON structure

Question

So I\'m trying to document the format of the json returned by an api I am writing against and I\'d like to know if there is any popular format for the documentation of json stru

Answer 1

It may not be useful in your case since it seems you are not building an API.

But if it was the case and you were using Java or JVM (JAX-RS), you could have used Swagger.

It permits to describes your API in a JSON representation (like WSDL/WADL). And they provide an IHM layer that reads that JSON representation of your API. Here is what you will get: http://petstore.swagger.wordnik.com/

https://developers.helloreverb.com/swagger/

Answer 2

I'm unsure to why you're trying to document JSON, I can guess your trying to find a consistent way to tell an IDE or a developer the data types on your notation.

jsdoc (http://jsdoc.sourceforge.net/#usage) might be what your are looking for.

for example:

{
   /**
     * Name of author
     * @type String
     */
   "author": null, 
   /**
     * has the author been clicked
     * @type Boolean
     */
   "clicked": null, 
   /**
     * Unix Timestamp of the creation date
     * @type Int
     */
   "created": null
}

Alternatively if your trying to demonstrate the structure of your data. You could look at YAML (http://www.yaml.org/), it's designed to be a human readable serialisation format which maybe be better suited for documenting your data structure.

A quick example:

Author:
  name: String
  clicked: Boolean
  created: Integer

Answer 3

In theory JSON Schema could serve this purpose, but in practice I am not sure it does. Worth mentioning I hope.

Other than this, my personal opinion is that since JSON is predominantly used for transferring objects, documenting equivalent objects in language client uses (Java, C#, various scripting languages) may make most sense -- after all, such objects usually are mapped/bound to JSON and back. And then you can use whatever documentation tools are available, like Javadoc for Java (perldoc for Perl, Oxygen for c++ etc etc).

For specifying interfaces there is also WADL (Web App Description Language), which might help.

Answer 4

You could write a sample JSON response and then document it using Markdown and Docco. Docco outputs easy to follow HTML based documentation.

Answer 5

A simple but effective way is to create a JSON schema with a JSON schema generator and then use JSON Schema for Humans, a Python utility to create html interactive documentation:

pip install json-schema-for-humans
generate-schema-doc [OPTIONS] SCHEMA_FILE [RESULT_FILE]

Useful references:

1. pypi json-schema-for-humans page
2. json-schema-for-humans documentation that includes some visual examples of the output

Keep in mind the JSON Schema is still in Draft state as of now, with the aim of becoming a IETF standard in the future.

Answer 6

For simple APIs where each JSON chunk is only one or two levels deep, then documenting by showing examples seems to be the common practice.

However for more complex data models such as yours, I have not seen any good solution. There are some JSON schema proposals, but that seems to go against the spirit of JSON, and seems too heavyweight for your purpose of just documenting.

Personally, I think your scheme is very good. With a few small extensions to handle optional and alternative sections I think it could be just as expressive as Backus-Naur Form, be very easy to read and understand, and be in keeping with the spirit of JSON. Maybe we can get some momentum behind others to use this "Taycher JSON Grammar Form" (TJGF)!