JSON (JavaScript Object Notation) is a lightweight data-interchange format defined by RFC 8259 and standardized as ECMA-404. JSON formatting — also called pretty-printing — takes compact, minified JSON and adds indentation and line breaks so humans can read it. A formatter inserts two or four spaces (or tabs) before nested keys, aligns brackets, and usually validates the syntax at the same time. Formatting never changes the data: a pretty-printed document holds exactly the same values as its minified original, only with whitespace added, which is why it is safe to format any JSON before reading, debugging, or committing it. JSON was created by Douglas Crockford in the early 2000s, and the current specification, RFC 8259, was published by the IETF in December 2017 and later designated Internet Standard STD 90. Every mainstream language ships a JSON parser — JavaScript's JSON.parse, Python's json module, Go's encoding/json — which is why JSON became the de facto format for APIs and configuration files.
Why format JSON?
Minified JSON (all on one line) is compact and efficient for transmission. But it's nearly impossible to read by hand. When you need to debug an API response, audit a config file, or understand a data structure, formatted JSON with proper indentation is essential.
Formatting also makes it easier to spot errors. Missing commas, unclosed brackets, and type mismatches jump out when the JSON is properly indented.
What indentation should you use?
There are three common indentation styles, and no single "right" answer — pick what your team uses and be consistent. Here's how they compare:
| Style | Best for | Tradeoff |
|---|---|---|
| 2-space | JavaScript and Node.js projects; files under version control | Compact, less diff noise |
| 4-space | Python and Java projects | Easier to scan visually, takes more space |
| Tab | Accessibility; respects editor preferences | Renders at different widths across editors |
2-space indentation
Compact and readable. Popular in JavaScript and Node.js projects. Good for files that will be version-controlled (less diff noise).
4-space indentation
More visual separation between levels. Common in Python and Java projects. Easier to scan visually but takes more space.
Tab indentation
Respects user preferences (tabs render at different widths in different editors). Good for accessibility. Less common in JSON but supported by most tools.
When to format
During development: Always format JSON when you're reading or debugging it. Use a formatter in your editor or a tool like TOOlover.
Before committing: If you're checking JSON into version control, format it consistently. This reduces diff noise and makes code reviews easier.
In APIs: Most APIs return minified JSON for efficiency. That's fine — clients can format it locally if needed.
In config files: Format configuration JSON for readability. Developers will read these files more often than machines will parse them.
Bonus: sorting keys
Some formatters can sort object keys alphabetically. This is useful for:
- Making diffs cleaner (keys don't move around)
- Finding keys faster (they're in order)
- Comparing two JSON objects (same key order makes comparison easier)
Tools
Most editors have built-in JSON formatting (VS Code: Shift+Alt+F). For quick formatting without opening an editor, use TOOlover's JSON Formatter — it's free, runs entirely in your browser (your data never leaves your device), and supports 2-space, 4-space, and tab indentation.
The key takeaway: format JSON when you're reading it, keep it consistent, and choose an indentation style that works for your team. The RFC 8259 specification is the reference if you need the formal grammar.