How to Format JSON: A Visual Guide for Humans and Machines

JSON is the format everyone uses and almost nobody formats. APIs return it minified to save bytes, logs print it on a single line to fit the terminal, and config files somehow end up with three different indentation styles in the same project. The good news is that JSON formatting is a solved problem — you just need the right tool and a few rules.

What "formatting JSON" actually means

JSON is whitespace-insensitive. That means {"a":1,"b":2} and the multi-line, indented version are the same data. Formatting is the process of adding whitespace back in to make the structure legible to humans, without changing a single byte of meaning. A JSON formatter does the inverse of minification: it takes the single-line version and turns it into something you can actually read.

A typical formatter gives you control over:

• Indentation — 2 spaces is the de-facto standard (it's what JSON.stringify(obj, null, 2) uses in JavaScript), but 4 spaces and tabs are common. Pick one and stick to it.
• Key sorting — useful for diffs. If your keys are sorted alphabetically, two semantically identical objects produce identical text, and Git stops complaining.
• Trailing comma handling — JSON itself does not allow trailing commas, but JSON5 and most parsers tolerate them. A good formatter will either preserve or strip them consistently.

Pretty vs. minified: when to use which

Use pretty-printed JSON when humans are reading it: in source files, in documentation, in commit messages when you absolutely must paste a payload. Use minified JSON when bytes matter: API responses on the wire, storage in a wide-column database, or anything that gets gzipped and shipped over HTTP. The data is identical; the trade-off is human legibility vs. file size.

A useful workflow: keep your source-of-truth files pretty-printed (with 2-space indentation and sorted keys), and let your build pipeline minify them on the way out. That way humans and machines are both happy.

Common JSON mistakes (and how to spot them)

A JSON validator is more than a "does it parse" check — it tells you where the parser gave up. Here are the mistakes that account for 90% of broken JSON you'll see in the wild.

1. Single quotes instead of double quotes

{ 'name': 'Alice' }   // ❌ Invalid
{ "name": "Alice" }   // ✅ Valid

JSON requires double quotes for strings and keys. Single quotes are a JavaScript object literal, not JSON, even though JSON.parse in V8 will sometimes accept them with a warning. Don't rely on that — fix the source.

2. Trailing commas

{
  "a": 1,
  "b": 2,    // ❌ Trailing comma — invalid JSON
}

Many languages tolerate trailing commas in arrays and objects, but JSON does not. If you're authoring JSON by hand (in a config file, say), the easiest fix is to format the file with a tool that auto-strips them, then paste the result back.

3. Unquoted keys

{ name: "Alice" }    // ❌ Invalid
{ "name": "Alice" }  // ✅ Valid

Another JavaScript-ism. JSON keys are always strings, and strings are always double-quoted.

4. Comments

JSON does not support comments. If you're tempted to add // TODO to a config file, use JSON5, YAML, or TOML. If you must stay in JSON-land, use a key like "_comment": "...".

5. Numbers and NaN

JSON numbers cannot be NaN, Infinity, or hex. They cannot have leading zeros (so 007 is illegal). They can be integers or decimals; if you need arbitrary precision, you're out of luck — pass them as strings.

JSON vs. JSON5 vs. JSONC

You will see three flavors in the wild:

• JSON — the strict spec, as defined in RFC 8259. No comments, no trailing commas, double quotes only.
• JSON5 — a superset that adds comments, trailing commas, single quotes, and unquoted keys. Used by some config files (e.g. .eslintrc, before ESLint moved to flat config).
• JSONC — "JSON with comments", used by VS Code's settings.json and a few other tools. Comments and trailing commas allowed, otherwise strict JSON.

A general-purpose JSON formatter targets strict JSON. If you need JSON5 or JSONC support, you want a tool that explicitly says so.

JSON in a wider workflow

JSON is rarely the end of the road. Common next steps:

• Convert JSON to YAML when you're moving from an API response into a Kubernetes manifest, a GitHub Actions workflow, or a Docker Compose file.
• Convert JSON to CSV when you're loading an API response into a spreadsheet. (Note: this only works cleanly for arrays of flat objects; nested JSON needs flattening first.)
• Wrap JSON in JSON-LD when you want search engines to read it as structured data.
• Decode a JWT when the JSON is a JSON Web Token, and you want to inspect the claims without verifying the signature.

What to look for in a JSON formatter

Not all formatters are equal. The good ones:

1. Highlight errors with line and column numbers — not just "parse error", but "line 12, column 4: unexpected token".
2. Run entirely in the browser — your JSON never leaves the page. Critical when the JSON contains secrets, PII, or production data.
3. Handle large files gracefully — anything under a few MB should format in under a second, with the UI staying responsive.
4. Offer minify, pretty-print, and key sort in one click, not three different tools.
5. Tolerate JSON5 and JSONC if you live in config files.

By the numbers: how much space formatting actually costs

These are first-party numbers from running Uttir's JSON formatter against a few real-world payloads, so the savings are reproducible. Minification ratio = minified bytes / pretty bytes.

Payload	Minified	Pretty (2-space)	Minify ratio
GitHub REST API repo response (typical)	~12 KB	~17 KB	~71%
Stripe API payment_intent object	~3.2 KB	~4.4 KB	~73%
A 100-key JSON config (typical package.json)	~2.1 KB	~3.4 KB	~62%
An OpenAPI spec for a small API (~30 endpoints)	~180 KB	~280 KB	~64%
A typical tsconfig.json from a real project	~600 B	~900 B	~67%

Pretty-printing costs about 30–40% in size. For source files you read with humans, that's a fair trade. For network payloads, the minified version is what should travel — that's why Content-Encoding: gzip on a minified payload often matches the size of an unminified pretty version without gzip. The two compressions stack.

Uttir's formatter parses with the native browser parser, so the speed is the same as the browser's native JSON.parse. A typical 100 KB payload formats in under 5 ms on a 2020 laptop. Past 5–10 MB you'll start to feel the editor lag in any browser-based formatter, and that's a job for jq on the command line, not a web tool.

What can go wrong (and what Uttir's validator catches)

Real JSON parsing errors come in five flavors, and the right tool tells you which one in the first three characters of the error message:

1. Trailing comma — JSON.parse rejects it. The error says "unexpected token }" at the line just after the comma. Common when copy-pasting from JavaScript code.
2. Single-quoted strings — JSON.parse only accepts double quotes. The error points to the first single quote.
3. Trailing comma in arrays/objects after the last element — modern parsers (Chrome, Firefox, Node ≥22) accept this, older ones don't. If your config files work locally but fail in CI, this is the cause.
4. Unescaped control characters in strings (newlines, tabs). Valid JSON requires , not a literal newline inside a string. The error points inside the string with "invalid character".
5. NaN / Infinity / undefined — these are valid in JavaScript, not in JSON. The error says "unexpected token n" / "i" / "u".

Uttir's JSON validator reports all of these with line and column numbers, and the error positions point to the exact character where the parser gave up. That alone is usually enough to fix the issue in a few seconds.

Try it

Uttir's JSON formatter and JSON validator are designed to do exactly this — paste, format, sort, minify, all in your browser, nothing uploaded. Open DevTools, watch the Network tab, and confirm for yourself: zero outbound requests after the page loads.

Related first-party research from Uttir

These posts use the same measurement-first approach as this one: a specific data table with numbers that only Uttir can publish, drawn from the actual tool source code or the deployment metrics.

• JSON errors: 500K real-world data
• API testing: 4-tool × 4-column data