How to Format JSON Properly

JSON looks simple until you open a 4,000-line minified file with a single trailing comma somewhere inside it and spend an hour finding the error. Formatting JSON properly is half aesthetics and half survival: consistent indentation, valid syntax, and sane key ordering make the difference between a file you can debug in minutes and one that kills your afternoon.

This guide covers the rules of valid JSON, the conventions that keep files maintainable, and the tools that will format, validate, and diff it for you so you never have to hand-align braces again.

The rules that are non-negotiable

JSON is strict. Keys must be double-quoted strings. Strings must use double quotes, never single. No trailing commas — after the last item in an array or object, the comma is illegal. No comments (despite what JSON5 or JSONC might let you write). No unquoted keys. No undefined. These aren’t style rules; breaking any of them makes the file unparseable.

Pick two or four spaces and stick with it

JSON doesn’t have an official indentation rule. Two spaces is compact and good for configs; four spaces is more readable for deeply nested data. Tabs work but render inconsistently across editors. The golden rule: whatever you pick, apply it everywhere in the file. Mixed indentation is how you end up reviewing pull requests where half the diff is whitespace.

Format once, automate forever

Hand-formatting JSON is a waste of time. Paste it into our JSON formatter to get pretty-printed output with your chosen indent. In editors, Prettier or VS Code’s built-in JSON formatter does the same on save. For API responses in the browser, a JSON viewer extension formats them automatically.

Validate before you ship

Invalid JSON breaks silently. An API endpoint returning malformed JSON to a client throws a parse error with no useful line number. Validate anything you don’t control: config files loaded at startup, data from third-party APIs, fixtures in tests. The JSON formatter above flags the first invalid token and tells you which line to fix.

Sort keys when diffing

If you check JSON into git, sorted keys make diffs readable. Two identical objects with keys in different order look completely different to git diff. Most formatters have a “sort keys alphabetically” option; turn it on for config files and schema definitions. For our site, run the file through our JSON diff checker to see only the real changes regardless of key order.

Minify for production, pretty-print for humans

Pretty-printed JSON has lots of whitespace — great for reading, wasteful for network transfer. API responses and bundled configs should be minified in production, and pretty-printed only when you open them in an editor. Build tools handle this automatically, but if you’re shipping JSON by hand, minify the one that goes to the wire.

Watch data types carefully

42 is a number; "42" is a string — they are not interchangeable. true, false, and null are lowercase only. Dates are always strings (JSON has no date type) — the convention is ISO 8601 (“2026-04-22T10:30:00Z”). Large integers can lose precision in JavaScript — above 2^53, send them as strings.

Prefer arrays over numbered keys

An anti-pattern: { "item1": ..., "item2": ... }. Use an array: { "items": [...] }. Arrays preserve order, iterate cleanly, and don’t require parsing integers out of keys. Only use object keys when the key has real meaning (user ID, region code, etc.).

Handle nested data without pain

Deeply nested JSON — three or four levels — becomes unreadable fast. If you’re designing your own schema, flatten where possible. For third-party data you can’t control, use the JSON formatter’s collapse controls to fold branches you don’t care about.

JSON vs YAML vs TOML

JSON is the default for APIs and programmatic data. YAML is easier for humans to write but has its own pitfalls (significant whitespace, the Norway problem). TOML is simple for configs. If you need to move between formats, our YAML / JSON converter handles the common case.

Common mistakes and how to avoid them

Copy-pasting JSON from documentation that uses smart quotes — they look like quotes but aren’t. Forgetting to escape backslashes in Windows paths ("C:\\Users\\me", not "C:\Users\me"). Including BOMs (byte-order marks) in UTF-8 JSON files — some parsers choke on them. Editing JSON in a word processor that auto-converts quotes. Solution: use a code editor, and validate before you ship.

Related: what is schema markup, how to use regex effectively, and what is an API for the full picture of where JSON shows up in modern development.