There have been many descriptions of the JSON format. ECMA-404 includes some of this history, quoted here with links added:
JSON was first presented to the world at the JSON.org website in 2001. A definition of the JSON syntax was subsequently published as IETF RFC 4627 in July 2006. ECMA-262, Fifth Edition (2009) included a normative specification of the JSON grammar. This specification, ECMA-404, replaces those earlier definitions of the JSON syntax. Concurrently, the IETF published RFC 7158/7159 and in 2017 RFC 8259 as updates to RFC 4627. The JSON syntax specified by this specification and by RFC 8259 are intended to be identical.
It must be noted that Tim Bray, editor of RFC 8259, actually recommends using I-JSON (RFC 7493) and none of the above mentioned specifications. Because it “explicitly rules out some legal-but-dumbass things”. (2017-12-14 : The Last JSON Spec (archived).)
HTML first gives you automatic JSON
You should always support a human readable HTML page of any data you publish, and mark it up with microformats2. At that point you don't need a separate JSON representation, because microformats2 parsers give you back canonical JSON which you can then serve if you wish, e.g. see Aaron Parecki's example below.
Accepting JSON POST requests
JSON does not have as wide support for POST requests compared to form-encoded requests.
In most web frameworks you have to jump through hoops to read the raw POST data if it's JSON format.
A Google search can confirm that lots of people are confused about how to handle JSON POST requests: how to receive JSON post in php, ruby, python, node
"I ditched content negotiation because it turned out to be a huge maintentance chore of very little actual value. ...the .json view was essentially the same as the parsed microformat view, and I never used it so it kept breaking"
Previously, Aaron Parecki returned JSON representations of URLs by appending ".json". However, in 2016-01 when Aaron launched the new version of his website, the new site did not support this feature.
"My .json view is *literally* the parsed microformat view. As in, I render the HTML as normal, then pass it through mf2-php before responding. It's like getting content negotiation for free."
Also see: p3k
- JSON Formatter
- JSONView - Chrome plugin which pretty-prints JSON
- JSON Formatter - A Safari extension which makes valid JSON documents human-readable.
- JSON Generator - define a schema and generate sample JSON data for testing