SpunkArt
Data, text and encoding

Formatting JSON: pretty-print, minify, sort keys

The same JSON data can be one dense line or a neatly indented tree. Whitespace between tokens has no meaning, so formatting never changes the data. It changes who can read it, how big it is, and how clean your version-control diffs look.

Format JSON

What a formatter actually does

A formatter parses the text into a value, then writes the value back out with a chosen layout. Because it parses first, it only works on valid JSON; if the input is broken, start with the JSON validator guide. In JavaScript the whole job is one line:

JSON.stringify(JSON.parse(text), null, 2)

The third argument is the indent. A number from 1 to 10 means that many spaces; a string such as "\t" is used as-is; leaving it out produces the compact one-line form. The second argument, null here, can be a function or a list of keys to keep, which is a quick way to strip fields from output.

Size: pretty versus minified

Take the five-field record in the tool above. Measured with JSON.stringify:

LayoutCharactersCompared with minified
Minified73—
Tab indent97+24 (33% larger)
2-space indent107+34 (47% larger)
4-space indent127+54 (74% larger)

Percentages are rounded to the nearest whole number. Small records show the largest relative overhead, because short values sit next to long runs of spaces. On a real API, HTTP compression such as gzip shrinks repeated spaces very well, so the gap on the wire is much smaller than the raw numbers suggest. Minify for storage and transfer; pretty-print for anything a person reads or commits to a repository.

Sorted keys for readable diffs

JSON objects are unordered by definition, but serialisers write keys in whatever order they hold them. If one program writes {"b":1,"a":2} and another writes {"a":2,"b":1}, a line-based diff shows a change even though the data is identical. Sorting keys before you save config files or test fixtures gives every file one canonical order, so a diff shows only real changes. Arrays are never sorted, because array order is meaningful.

Formatting from the command line

  • Python: python3 -m json.tool data.json pretty-prints with 4 spaces. Add --sort-keys to sort, or --compact to minify.
  • jq: jq . data.json pretty-prints; jq -c . data.json minifies; jq -S . sorts keys.
  • Node.js: node -e "console.log(JSON.stringify(require('./data.json'), null, 2))".
  • Editors: most code editors have a “Format Document” command that applies the same rules.

Pitfalls when re-serialising

  • Big integers lose precision. JavaScript numbers are 64-bit floats, safe only up to 253 − 1 (9,007,199,254,740,991). Formatting [9007199254740993] in a browser outputs [9007199254740992]. Large database ids should travel as strings.
  • Number style changes. 1.0 comes back as 1 and 2.50 as 2.5. The value is equal, but a byte-for-byte comparison fails.
  • Out-of-range numbers become null. 1e400 is parsed as Infinity, and JSON.stringify writes Infinity as null.
  • Duplicate keys collapse. Only the last value survives a parse, so formatting silently deletes the others.

Questions

Does formatting change my data?

Whitespace never does. The pitfalls above can, which is why the tool shows the result rather than editing your text in place. Nothing is uploaded.

Which indent should a team use?

Any, as long as everyone uses the same one. Two spaces is common in JavaScript projects and four in Python projects. Put the choice in an editor config file so it is automatic.