JSON is everywhere in modern development. APIs return it. Configuration files use it. Databases store it. But raw JSON is often hard to read. This guide covers why formatting matters and how to do it right.
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.
Indentation styles
There are three common indentation styles:
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.
There's no "right" choice — pick what your team uses and be consistent.
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)
Not all projects need sorted keys, but it's a nice option to have.
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 in your browser, 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.