How to Format JSON: A Practical Guide for Developers in 2026

Every developer who works with an HTTP API, a config file, or a log pipeline ends up formatting JSON dozens of times a week. The problem is that the defaults across tools disagree — one serializer emits two-space indentation, another emits four, curl prints it minified, your IDE reformats it on save, and your diff ends up unreadable. This guide is the practical answer to the question "how do I format JSON so it stays clean across every tool I use," plus the small traps that come with it.

#TL;DR

• Use two-space indentation for most JSON. Four is for Python people.
• A JSON formatter worth using also validates as it formats — don't trust a tool that silently "fixes" bad input.
• Minify API responses in transit, pretty-print only for humans.
• UTF-8, no BOM, newline at end of file. Always.
• JSON does not allow comments or trailing commas. If your file has them, it's JSONC or JSON5, not JSON.

#What "formatting" actually means

When most developers say "format this JSON," they mean two things at once: validate that the input is legal JSON, and pretty-print it with whitespace that a human can read. These two jobs can be done independently, but they should be done together. If your JSON formatter accepts malformed input and silently produces output, it's not a formatter — it's a footgun.

The official JSON spec (RFC 8259) is one of the shortest standards you'll ever read. The grammar fits on a napkin. Pretty-printing adds no information; it just inserts newlines, spaces, and indentation between tokens. A round-trip through a compliant formatter should produce byte-for-byte identical output on the second pass.

The simplest possible pretty-printer is built into every JavaScript runtime:

JSON.stringify(obj, null, 2);

The third argument is the indent width. Pass 2 for two-space, 4 for four-space, or a string like "\t" for tabs. If you call JSON.stringify per the MDN spec, you get deterministic output within a single version of V8.

When you need the opposite — a clean single line without whitespace — paste into our JSON minifier. For the full pretty-print-and-validate loop, the JSON formatter is the fastest path and runs entirely in your browser.

#Two-space vs four-space vs tabs

This is the closest thing to a religious war JSON has, so let's cut through it.

• Two spaces is the default for prettier, jq -r ., JSON.stringify(x, null, 2), GitHub's rendered diff, and about 80% of JSON you see in the wild. Pick this unless you have a reason not to.
• Four spaces is Python's json.dumps(x, indent=4) default and tends to spread nested objects across the screen. Use it when your code is mostly Python and you want symmetry with your .py files.
• Tabs show up in handwritten Go configs and some Rust projects. Tabs are fine in theory. In practice, mixing tabs and spaces in a single JSON file causes diff noise, so pick one and enforce it in CI.

#Consistency across a team

The single biggest improvement you can make is not choosing "the right" indent width — it's committing to one and enforcing it. A .editorconfig file plus prettier --check "**/*.json" in CI solves this permanently. If you don't already have that, set it up today:

# .editorconfig
[*.json]
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
charset = utf-8

Everything else — the merge conflicts, the "why did my editor reformat the whole file" complaints — comes back to a missing .editorconfig.

#When to minify the JSON formatter wouldn't touch

Minification and pretty-printing are both valid end states; they just serve different audiences. A useful rule of thumb:

• Minify JSON that machines will read and humans almost never will: API responses, WebSocket payloads, Redis values, JWTs (the payload inside a token is always minified for a reason).
• Pretty-print JSON that humans edit by hand: config files, fixtures, test snapshots, package.json, tsconfig.json.

Don't commit pretty-printed API fixtures that were generated by a server. They'll diverge the moment someone regenerates them, and your diff will flood with whitespace changes. Either format them on write (in a deterministic way) or commit the minified form and let the IDE pretty-print for reading.

#What minification actually saves

Less than you think, especially on the wire. Most production traffic is gzip or Brotli compressed, and compression eats whitespace for breakfast. On a 200 KB JSON payload, pretty-printing might add 15 KB of whitespace uncompressed — but compressed, the difference is often under 1 KB. Don't minify on the server for bandwidth reasons alone. Minify because your logs get smaller and your debugging pipes stay clean.

#How a good JSON formatter validates

A real formatter doesn't just pretty-print; it parses the input into a tree, then re-serializes. If parsing fails, you get a precise error with a line and column — not "invalid JSON". Look for these guarantees when you pick one:

1. Strict mode. No comments, no trailing commas, no unquoted keys, no single quotes. If you want the lenient flavor, ask for JSON5 explicitly.
2. Error location. Unexpected token } at line 14, column 3 is a fix in under a minute. SyntaxError: Unexpected end of JSON input is a 20-minute hunt.
3. Large-input performance. Anything above 1 MB should still render in under a second. Our JSON formatter streams input via the browser's native parser, so it handles multi-megabyte payloads without a spinner.
4. Exact round-trips. Numbers should not be coerced, keys should not be re-ordered, strings should not be re-escaped beyond what JSON requires.

The last point is where a lot of online formatters quietly misbehave. They re-order object keys "for readability," lose precision on big integers (JavaScript's number is a 64-bit float), or normalize A to A. All three of those can break downstream tools that hash or sign the JSON.

#JSON, JSONC, and JSON5

Here's a source of endless confusion: the ".json" file in your repo might not be standard JSON at all.

• JSON — the spec. No comments. No trailing commas. Double-quoted keys. This is what the JSON formatter produces.
• JSONC — JSON with comments. Used by VS Code for settings.json and tsconfig.json. It's not a spec, it's a VS Code convention.
• JSON5 — a bigger superset: unquoted keys, single quotes, comments, trailing commas, hex numbers, NaN and Infinity. Configs only; never wire format.

If a formatter strips comments out of your tsconfig.json, it's treating the file as strict JSON. Use a JSONC-aware tool for config, a strict JSON tool for wire data. Don't mix them.

When you pass JSON between services, use strict JSON — never JSON5. The moment a consumer of your API is written in a language without a JSON5 parser (most of them), you've broken compatibility.

#Common mistakes

• Trailing commas. {"a": 1,} is not JSON. It's valid JavaScript, valid JSON5, and valid in many people's muscle memory — but a strict JSON parser will reject it. If you want a linting tool to warn, use prettier or eslint-plugin-jsonc.
• Single quotes. {'a': 1} is never valid JSON. Same story as trailing commas.
• Big integers losing precision. JavaScript represents all numbers as 64-bit floats, so integers above 2^53 - 1 lose precision. If your API returns {"id": 9007199254740993}, that round-trips as 9007199254740992. Serialize IDs as strings.
• Re-ordering keys. If downstream code computes a hash over canonical JSON, re-ordering keys silently breaks the hash. A JSON formatter should preserve insertion order.
• Mixed line endings. Commit .json with LF endings on every platform. CRLF creeps in on Windows and breaks git diff.
• Accidentally committing pretty-printed fixtures. If a fixture file is generated, either commit it minified or normalize it with the same formatter every time.

#FAQ

#What is the best way to format JSON online?

Use a client-side formatter that parses strictly and does not send your input to a server. Paste into the JSON formatter, pick two-space or four-space indentation, and copy the result. Your data never leaves the browser.

#How do I format JSON in VS Code?

Open the file, press Shift+Alt+F (Windows/Linux) or Shift+Option+F (macOS). VS Code uses its built-in JSON formatter, which respects the editor.tabSize setting and treats .jsonc files as JSON with comments.

#Is there a difference between formatting and beautifying JSON?

No. "Format," "beautify," and "pretty-print" all describe the same operation: parsing JSON and re-emitting it with whitespace. "Minify" is the inverse — same parse, no whitespace.

#Why does my JSON formatter say "invalid JSON" on valid input?

Usually one of three things: a trailing comma, a single-quoted string, or a non-JSON comment. All three are valid in JavaScript source but not in the JSON grammar per RFC 8259. Check the last line reported by the error.

#Can I format JSON from the command line?

Yes. python3 -m json.tool < file.json is available everywhere Python is installed. jq . file.json is faster and handles larger files. npx prettier --write file.json respects your project's config.

#Should I minify JSON in production APIs?

Probably not for bandwidth alone — gzip or Brotli on the wire erases most of the gain. Do minify JSON in log files, key-value stores, and anywhere a human will not read it directly.

#Wrapping up

Formatting JSON is one of those tasks that looks trivial until you've had a 400 KB config file expand to three lines because someone's editor decided to "auto-format." Pick two spaces, turn on validation, enforce .editorconfig in CI, and keep JSONC out of your wire format. The rest is muscle memory.