Syntax for documenting JSON structure

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.

How to generate a HTML Documentation from JSON:

You will need to generate a Json Schema, there is this service that you can paste the orginal JSON and auto generate the Schema:

http://www.jsonschema.net/

With the schema in hands you can auto generate the HTML Documentation using Matic.

https://github.com/mattyod/matic

Generating HTML

To Install Matic you will need install Node.js: http://nodejs.org/

On Windows, run CMD

Install Jade running this command: npm install -g jade

Open the Downloaded Matic folder from Github: cd PATH_TO_FOLDER/matic

Run the install command: npm install -g

Download a documentation example project: https://github.com/mattyod/matic-simple-example

Put your schema in the folder "schemas"

Open the project folder: cd PATH_TO_PROJECT_FOLDER

Run command: matic

You should see a success message: Documentation built to ./web/

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