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 structure.

Note I'm not trying to to test or validate anything, I'm just using this for documentation. Also some ways to add comments to non-constants(items always returned w/ the same value) would be nice.

This the not totally thought out scheme I'm currently using:

Plain names refer to identifiers or types.
Some types have type-comment
Strings that appear to be constant(always returned for that type of request) strings are "str"
Constant Numbers would be just the number
Constant null is null
Booleans are true/false for constant booleans or Boolean otherwise
[a,b,c] are lists with 3 items a,b,c
[...  ...] is a list of repeating elements of some types/constants/patterns
{a:A,b:B,c:c} and {... ...}  is the same for a dictionary.

example:

story          := [header,footer]
header         := {"data":realHeader,"kind":"Listing"}
realHeader     := {"after": null, "before": null, "children": [{"data": realRealHeader, "kind": "t3"}], "modhash": ""}
footer         := {"data":AlmostComments,"kind":"Listing"}
AlmostComments := {"data": {"after": null, "before": null, "children": comments, "modhash": ""}, "kind": "t1"}
comments       := [...{"data":comment, "kind":"t1"}...]

realRealHeader :=
{"author": string,
"clicked": boolean,
"created": int,
"created_utc": int,
"domain": "code.reddit.com",
"downs": int,
"hidden": boolean,
"id": string-id,
"is_self": boolean,
"levenshtein": null,
"likes": null,
"media": null,
"media_embed": { },
"name": string-id,
"num_comments": int,
"over_18": false,
"permalink": string-urlLinkToStoryStartingFrom/r,
"saved": false,
"score": int,
"selftext": string,
"selftext_html": string-html,
"subreddit": string-subredditname,
"subreddit_id": string-id,
"thumbnail": "",
"title": string,
"ups": int,
"url": "http://code.reddit.com/"
}


comments := {
"author": string,
"body": string-body_html-wout-html,
"body_html": string-html-formated,
"created": int,
"created_utc": int,
"downs": int,
"id": string-id,
"levenshtein": null,
"likes": null,
"link_id": string-id,
"name": string-id",
"parent_id": string-id,
"replies": AlmostComments or null,
"subreddit": string-subredditname,
"subreddit_id": string-id,
"ups": int
}

I think your scheme is actually a pretty good starting point. I was going to suggest for fields that have limited values to use syntax like `"mode": "fast" | "medium" | "slow",`, where each possible value is explicitly given as a literal string or int or boolean. The vertical bar `|` is not legal in JSON (outside of a string), so its meaning as a meta character is understood. — Mark Lakata, Jul 08 '15 at 22:50
till the world find a "one size fit all" , one can try this https://jsondoc.online — Bhuvan, Jun 14 '19 at 04:38

score 43 · Accepted Answer · answered Jan 06 '11 at 22:20

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.

Old question but - the "hyper-schema" part of the JSON Schema standard can document links/forms quite comprehensively. — cloudfeet, Jan 18 '13 at 15:59

score 15 · Answer 2 · answered Apr 11 '13 at 18:09

15

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/

answered Apr 11 '13 at 18:09

Carlos Oliveira

846
10
23

1

Thanks for mentioning Matic. Just one point, you can also install it by running: npm install -g matic – Mattyod Apr 22 '13 at 16:07
I'd like to be able to validate JSON using a Json Schema, is that possible, or is it only useful for generating documentation? – Daryl Jan 03 '17 at 16:45
jsonschema.net does not respond anymore maybe https://app.quicktype.io/#l=schema can be usefull – lrkwz Feb 17 '18 at 19:03
Maybe I'm wrong, but matic cannot handle arrays of objects? – Peter Sep 25 '18 at 14:12
There have been some changes since this answer was posted. Now requires Pug rather than Jade. Also see new Matic example here: https://github.com/mattyod/matic-draft4-example – Yogi Jul 15 '19 at 15:22

score 9 · Answer 3 · edited Oct 20 '11 at 01:24

9

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

edited Oct 20 '11 at 01:24

Iterator

20,250
12
75
111

answered Jan 10 '11 at 22:51

SnatchFrigate

352
2
7

14

To document an api for developers. – Roman A. Taycher Jan 11 '11 at 08:52
1

The shape of the jsdoc output is exactly what I'd do and I'd put it directly in the source of the service that produces the output, at the top of the file. I'd then put brief sample output below that. The convention being that developers who need to use a service just go look at the source. – jaydel Jan 13 '11 at 13:18
4

Note that comments are forbidden in JSON They will make APIs, like JavaScript JSON.parse(), fail You can still include comments but they'll have to be removed from the JSON before delivering it to its destination (configuration reader, Web client, ...) – Alexandre Morgaut Sep 29 '16 at 11:54
Note that the linked jsdoc project is deprecated and no longer developed. The latest incarnation is on github: https://github.com/jsdoc/jsdoc – Dathan Feb 16 '22 at 22:59

score 5 · Answer 4 · answered Oct 10 '11 at 20:39

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)!

score 3 · Answer 5 · answered Apr 24 '13 at 10:56

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/

score 3 · Answer 6 · answered Jan 11 '11 at 22:33

3

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

answered Jan 11 '11 at 22:33

Josh Schumacher

198
1
9

1

One challenge in decoupling it from the source that consumes and produces the JSON is that you add a new risk of keeping the two things in synch. This is of course a common challenge with all documentation, but since the audience here is developers, leaving the example in the code probably helps to reduce this risk a bit. – jaydel Jan 13 '11 at 15:46

score 2 · Answer 7 · answered May 28 '20 at 08:37

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:

pypi json-schema-for-humans page
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.

Syntax for documenting JSON structure

7 Answers7

Linked