JSON flaws

November 11, 2024 ยท View on GitHub

This document presents flaws with the JSON format, which are problematic given how ubiquitous the notation is.

Also see Gallia data modeling.md

  • Was probably never meant to become the standard it has become
  • Has no official notions of schema: JSON Schemas are an afterthought and unaffiliated(?)
  • Ambiguity over the semantics of: {"foo": "hello", "bar": null} vs {"foo": "hello", "bar": []} vs {"foo": "hello"}; this means people choose one arbitrarily and sometimes imparts alternative semantics to each (and often do not comment on that fact); empty strings and zero values are also possibly problematic from that angle (TBD).
  • JSON arrays at the top-level are painful to process when big, which is probably why "JSON Lines" (https://jsonlines.org/) prospered. I recommend avoiding them as much as possible.
  • JSON aims to be part human friendly, part machine friendly; it is less human friendly than YAML or HOCON, and much less machine friendly than say alternatives like Avro, protobuf, etc; This isn't a problem in and of itself, only insofar as people use it for just about everything irrespective of who/what will consume it (human or machine)
  • Data types:
    • It's dearly missing the Integer type (possibly my biggest pet peeve with it) - I refer to this as the "JSON number tax"
    • It's missing a "flag" type, which could be achieved with an optional "Unit" value; people resort to using a boolean which is wasteful if only one boolean value is ever used; flags are especially useful when extremely rare.
    • Some could argue a character type would have been useful too
  • Keys:
    • Duplicate keys being allowed: echo '{"foo":"hello", "foo":3}' | jq -c # returns {"foo":3}
    • Key-quoting is mandatory, which seems wasteful most of the time
    • Keys are limited to strings, although this can be argued to be a good thing
    • Keys order is not guaranteed to be preserved
  • File extensions:
    • Other than .json, and to an extent .jsonl, there is no common convention for what a file may actually contain: a single object? in compact form? pretty-printed? Multiple objects one-per-line? multiple objects in a JSON 'array', multiple objects pretty printed? It would certainly be useful to know that just from the filename. In my libraries (Gallia and Aptus), I assume: .json or .jsono for single object, .jsonl or .jsons for one-per-line, and .jsona for array
  • other misc oddness:

Note that I am writing the specification for a JSON-like format that would address some of these concerns. I will post it soon for feedback (bearing this in mind)