Why formatting JSON matters
In production, JSON usually travels minified: one line, no spaces, no breaks. That saves bytes but makes it unreadable. When you're debugging an API response, scanning a long config, or auditing a database export, the first move is to format. A good formatter turns a soup of characters into a clear hierarchical structure in under a second.
Strict JSON rules
- Double quotes only. JSON doesn't accept single quotes.
'name'breaks the parser;"name"works. - No trailing commas.
{"a":1,}is valid JavaScript but invalid JSON. - No comments. No
//and no/* */. If you need comments, use JSON5 or JSONC (VS Code's variant). - Keys always quoted.
{name: "Genfy"}breaks;{"name": "Genfy"}works. - Booleans lowercase.
trueandfalse, notTrue.
Valid data types
JSON supports six types: string, number, boolean, null, object and array. No dates (represented as ISO strings), no undefined (the key gets dropped), no functions, no symbols. When a library serializes a JavaScript object to JSON, anything outside those six types disappears silently.
Indentation: 2 spaces, 4 spaces or tab
No universal standard. The most common convention in JavaScript projects is 2 spaces (npm package.json, Prettier default). Python leans toward 4. Some teams use tabs for accessibility reasons. What matters is consistency inside a project: if your repo uses 2 spaces, don't introduce files with 4.
Common syntax errors
- Trailing comma at the end of an array or object. Often comes from deleting the last line without updating the previous comma.
- Smart quotes. When you copy from Word or Google Docs, regular quotes get auto-replaced with curly quotes (" ") that JSON doesn't understand.
- Control characters in strings. Literal tabs and newlines inside strings break the parser; they must be escaped as
\tand\n. - Mismatched braces or brackets.
Tips for working with large JSON
If your file is over 10 MB, avoid web editors — they may freeze the browser. Use a CLI tool like jq to filter and reformat. To inspect part of the structure, try jq 'keys' to list top-level keys before going deeper.
JSON vs modern alternatives
- JSON5: allows comments, trailing commas, unquoted keys. Useful for configs.
- YAML: more readable but ambiguous (an unquoted value can be parsed as string or number).
- TOML: popular in Rust and some config files (Cargo, pyproject.toml).
- Protocol Buffers: binary, much more efficient than JSON for internal service-to-service traffic.