How to Format and Validate JSON (And Fix the Errors You Will Hit)

2026-07-15 · 7 min read

A practical guide to reading, formatting and debugging JSON — including the handful of syntax rules that cause almost every parse error developers run into.

JSON is deliberately minimal. That is its strength, and also why a single misplaced character can break an entire API response with an error message that points at the wrong place.

The rules that cause almost every error

JSON has a small grammar, and violations cluster around a handful of mistakes.

• Trailing commas are invalid. JavaScript allows them, JSON does not. This is the most common error by a wide margin.
• Keys must be double-quoted strings. Not single quotes, not bare words.
• Strings use double quotes only. Single quotes are never valid, anywhere.
• Comments do not exist in JSON. No double-slash and no slash-star. If you need annotation, add a field for it.
• No undefined, no NaN, no Infinity. Use null.
• Numbers cannot have leading zeros or a trailing decimal point. 007 and 1. are both invalid.

Why error messages mislead

A parser reports the position where parsing became impossible, which is often well past where you actually made the mistake. Forget a closing brace on line 12 and the error may surface on line 340, where the parser finally runs out of input.

This is why formatting is a debugging technique rather than a cosmetic one. Re-indenting the document makes structural imbalance visible — a block that does not close where you expect it to becomes obvious at a glance.

Formatting versus validating versus minifying

Formatting adds whitespace and indentation to make structure readable. It changes nothing about the data.

Validating confirms the document parses and reports where it fails. Any formatter implicitly validates, because it cannot format what it cannot parse.

Minifying strips all non-essential whitespace to reduce transmission size. For a large API payload this meaningfully reduces bandwidth. For anything a human will read, it is counterproductive.

Schema validation is a separate concern — checking not that the JSON parses, but that it has the fields your application expects with the types it expects. JSON Schema handles this, and no formatter will do it for you.

A word about pasting sensitive JSON online

API responses routinely contain access tokens, session identifiers, email addresses, internal hostnames and customer records. Pasting one into a formatter that transmits to a server means handing that data to a third party — and if the payload contained a live token, you should now treat it as compromised.

This is not hypothetical. Credential leakage through developer utilities is a recognised and recurring problem.

Our JSON formatter parses entirely in your browser. Nothing is transmitted, so there is no server-side log to worry about. The same applies to our JWT decoder, which matters more — a JWT you are debugging is very often a valid credential.

Debugging a payload you did not write

• Format it first. Structure you can see is structure you can reason about.
• Collapse nested objects to understand the shape before reading the values.
• When the error position looks wrong, work backwards from it looking for an unclosed bracket or brace.
• For very large payloads, extract the failing section and validate it in isolation.
• If the source is an API, check whether it returned an HTML error page rather than JSON — a surprisingly common cause of "invalid JSON" when the real problem is a 500 response.

JSON versus the alternatives

JSON won for APIs because it maps cleanly onto the data structures every language already has, and because it is unambiguous. It is a poor fit for configuration files, though, precisely because of the strictness above — no comments and no trailing commas make hand-edited config painful.

YAML is friendlier to write and allows comments, at the cost of significant whitespace sensitivity and a much larger specification with genuine surprises in it. TOML sits between the two and is well suited to configuration. JSON5 relaxes JSON's rules for human authoring while remaining recognisable.

For data interchange between systems, JSON remains the right default. For files humans edit by hand, it usually is not.

← Back to all articles