What is JSON and why does formatting matter?
JSON (JavaScript Object Notation) is the de facto interchange format for data on the web. REST APIs return it, configuration files use it, and databases store it. When it arrives minified — as a single dense line — reading it requires a formatter.
A formatter does three things: it validates the syntax, re-serialises the data with consistent indentation, and optionally minifies it back for storage or transmission.
The JSON syntax rules developers most often break
JSON is strict in ways XML and most config formats are not:
- Keys must be double-quoted strings.
{name: "Alice"}is invalid;{"name": "Alice"}is correct. - Trailing commas are illegal.
[1, 2, 3,]fails. Most linters catch this, but it slips through when hand-editing. - Single quotes are not allowed.
{'name': 'Alice'}is JavaScript object literal syntax, not JSON. - Comments are not part of the spec. If your toolchain uses JSON-with-comments (JSONC), a standard JSON parser will reject the file.
- Numbers must not have leading zeros.
010is an error;10is fine.
Indentation: 2 spaces, 4 spaces, or tabs?
The choice is stylistic, but conventions vary by ecosystem:
| Format | Common in | |---|---| | 2 spaces | JavaScript/TypeScript projects (npm default) | | 4 spaces | Python (PEP 8 inspired), Java | | Tabs | Go (gofmt), Makefile enthusiasts |
For configuration files committed to a repository, pick whichever matches your .editorconfig or prettier config and never change it — diffs over whitespace-only changes pollute git history.
When to minify
Minified JSON removes all non-essential whitespace. A 100 KB pretty-printed file might become 60 KB minified. The difference matters when:
- Serving JSON over a slow mobile connection (though gzip compression reduces the gap significantly)
- Storing JSON in a column-level database field where byte counts are metered
- Embedding JSON in a
<script>tag where file size directly affects page load
For API responses, let your server gzip the response rather than manually minifying — you get the size benefit without losing human-readability in development.
Reading validation errors
A good formatter reports the exact position where parsing failed. Typical messages:
- "Unexpected token , in JSON" — trailing comma before a closing bracket
- "Unexpected end of JSON input" — missing closing brace or bracket
- "Expected property name or '}'" — an extra comma at the end of an object
- "Unexpected token ' in JSON" — single quotes used instead of double
When you see a line/column number, count from the top-left. Most errors are within 2–3 characters of the reported position.
Understanding the stats: keys, depth, and byte counts
Keys is the total count of named properties across all objects in the document. A deeply nested API response with 50 objects each having 5 keys reports 250.
Depth is the maximum nesting level. {"a": {"b": {"c": 1}}} has a depth of 3. Very deep nesting (10+) is usually a sign of data modelling problems.
Byte counts tell you the cost of formatting. The original bytes count what you pasted. Pretty bytes count the formatted version. Minified bytes show the floor. The gap between pretty and minified is your indentation overhead — for deeply nested structures it can be 30–50%.