title: Syntax for documenting JSON structure
body: <p>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. </p>
  
  <p>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.</p>
  
  <p>This the not totally thought out scheme  I'm currently using:</p>
  
  <pre><code>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.
  </code></pre>
  
  <p>example: </p>
  
  <pre><code>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
  }
  </code></pre>