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:
| Layout | Characters | Compared with minified |
|---|---|---|
| Minified | 73 | — |
| Tab indent | 97 | +24 (33% larger) |
| 2-space indent | 107 | +34 (47% larger) |
| 4-space indent | 127 | +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.jsonpretty-prints with 4 spaces. Add--sort-keysto sort, or--compactto minify. - jq:
jq . data.jsonpretty-prints;jq -c . data.jsonminifies;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.0comes back as1and2.50as2.5. The value is equal, but a byte-for-byte comparison fails. - Out-of-range numbers become null.
1e400is parsed as Infinity, andJSON.stringifywrites Infinity asnull. - 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.