JSON

From IndieWeb


JSON (abbreviation for JavaScript Object Notation) is a data serialization format often used by HTTP APIs, growing in popularity instead of XML, and also the canonical output of microformats2 parsers.

Specs

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 “ex­plic­it­ly rules out some legal-but-dumbass things”. (2017-12-14 Tim Bray: 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.

Issues

Accepting JSON POST requests

Main article: JSON form encoded

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

Indieweb Examples

Barnaby Walters

Previously, Barnaby Walters using Taproot on waterpigs.co.uk would return a JSON version of a document by appending ".json" to the URL. However, in 2014-?? Barnaby dropped support for this.

"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"[1]

Aaron Parecki

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."[2]

Also see: p3k

Resources

See Also