JSON

This article is a stub. You can help the IndieWeb wiki by expanding it.

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

• 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

See Also

• microformats2
• JavaScript
• http://seriot.ch/parsing_json.php
• RFC7493 The I-JSON Message Format: Internet JSON for interoperability between JSON parsers
• https://twobithistory.org/2017/09/21/the-rise-and-rise-of-json.html
• https://twitter.com/dauwhe/status/927955449126838278
  • "It is a truth universally acknowledged, that a working group in possession of a problem, must be in want of a new JSON format." @dauwhe November 7, 2017
• JSONx an “IBM® standard format to represent JSON as XML.”
• JSON Canonicalization Scheme (JCS) (RFC 8785) for a canonical JSON format, which of course also links to more specs trying to do the same thing (Appendix H).
• JavaScript Object Notation (JSON) Text Sequences (RFC 7464) can be used to combine multiple JSON documents into a single file/stream of JSON documents, a sequence. Though again many alternatives exist, JSON Lines probably being the most prevalent. Wikipedia has a short overview.
• JavaScript’s (and thus node’s) JSON parser has enabled Prototype Poisoning (https://medium.com/intrinsic/javascript-prototype-poisoning-vulnerabilities-in-the-wild-7bc15347c96) in multiple tools, see https://hueniverse.com/a-tale-of-prototype-poisoning-2610fa170061?gi=5984ffcbc7a9 for one such story and open-source solution
• Microsoft has a format they call JSON with Comments and refer to as jsonc. This is used in tools like VSCode and and has an open-source parser. But should not be confused with jsonc another alternative JSON format, JSONC the JSON compressor, or json-c the C JSON implementation.
• The original license includes the line "The Software shall be used for Good, not Evil." This has lead to discussions about it not being OSS.
• XSL Transformations (XSLT) Version 3.0 (W3C Recommendation) specifies JSON to XML transformation, giving another way to express JSON as XML.
• From UBJSON, a binary format for JSON: “Attempts to make using JSON faster through binary specifications like BSON, BJSON or Smile exist”. Another wide split in different specifications having come from original JSON.
• JSONH, a “way to pack and unpack generic homogenous collections” (e.i. lists of objects to just flat arrays). For when you want to store JSON objects in JSON but in less bytes.
  • 2011-06-18 Andrea Giammarchi: Last Version Of JSON Hpack (archived)
  • 2021-12-28 Andrea Giammarchi: Beyond JSON Performance (archived), from the 2021 edition of the yearly Web Performance Calendar
• lulz: Acronym of Javascript’s Son, per Web Development Acronyms: A Convenient Reference List.
• PipeWire and its policy manager WirePlumber implement a dialect called SPA JSON:
  • 2022-10-27 Ashok Sidipotu: From Lua to JSON: refactoring WirePlumber's configuration system (archived) gives some examples of what would have the same parser outcomes.
  • PipeWire calls it “Relaxed JSON variant parsing.” The SPA stands for Simple Plugin API and has nothing to do with the JSON itself.
  • It looks like the implementations for WirePlumber (docs, merge request) came later and is different from the one for PipeWire (docs, original commit). Neither docs will actually tell you what is relaxed, thus why the first mentioned blogpost by Ashok is valuable. One way to find out how the parser works is to read all the commit messages, like commit 49b17bca explaining what relaxing was done to the parser (archived).
• JSON5 dubs itself “JSON for Humans” and has the goal to be used for JSON that is written by hand rather than as a data communication format between computers.
  • It has a formal spec that describes it as a superset of RFC 7159 and a subset of ECMA-262, 5.1 Edition.
• newline-delimited JSON http://ndjson.org/
• JC (JSON Convert) (archived) - an open-source tool to turn the output of cli applications into JSON
  • 2021-12-03 Kelly Brazil: Tips on Adding JSON Output to Your CLI App (archived) - things to think about if your application is outputting JSON, with comments on streaming output and making sure filters are easy to apply