Developers · 6 min read

JSON Formatting and the Syntax Errors That Break It

JSON is deliberately small and strict, which makes it easy for machines and surprisingly easy for humans to get wrong. One missing quote or stray comma and an entire payload is rejected with an unhelpful message. This guide covers the rules JSON actually enforces, the errors people hit most often, and how formatting helps you find them.

The rules JSON enforces

JSON allows six kinds of value: objects, arrays, strings, numbers, true or false, and null. Objects are wrapped in curly braces and hold key-value pairs separated by commas. Arrays are wrapped in square brackets. Every key must be a string in double quotes, and strings must also use double quotes.

The format is defined independently of JavaScript, and it is stricter than JavaScript object literals. Code that works as a JS object can fail as JSON, which is the source of most confusion.

The errors you will see most

Almost every parse failure comes from a short list of mistakes:

  • Trailing commas: a comma after the last item in an object or array is invalid in JSON, even though JavaScript allows it.
  • Single quotes: {'name': 'Ada'} is not JSON. Keys and strings need double quotes.
  • Unquoted keys: {name: "Ada"} is a JavaScript object, not JSON.
  • Comments: JSON has no comment syntax. // and /* */ will cause an error.
  • Special values: NaN, Infinity and undefined are not valid. Use null or a string instead.
  • Unescaped characters: a literal newline or tab inside a string must be written as \n or \t, and a double quote as \".

Reading an error message

Parsers usually report a position, such as "Unexpected token } in JSON at position 42". The character reported is where the parser gave up, not necessarily where the mistake is. A missing comma between two properties is reported at the start of the second property, and an unclosed string is often reported far later, at the end of the document.

When the reported position looks fine, look at the characters just before it: the previous line is usually where a comma, quote or bracket is missing.

Why pretty-printing finds bugs

Minified JSON is a single line, which hides structure. Formatting it with consistent indentation makes mismatched braces visible immediately: a closing bracket that sits at the wrong indentation level shows exactly where nesting went wrong.

Formatting also makes diffs readable. Two payloads that differ in one nested field are impossible to compare on one line, but obvious when each key has its own line. For this reason many teams commit JSON configuration files pretty-printed with two-space indentation and minify only for transport.

Numbers, dates and big integers

JSON numbers have no integer type, and JavaScript parses all of them as 64-bit floating-point values. Integers above 9,007,199,254,740,991 (2 to the 53rd power, minus 1) lose precision, which is why identifiers such as large database IDs are best sent as strings.

JSON also has no date type. The widely used convention is an ISO 8601 string such as 2026-11-12T09:30:00Z, or a Unix timestamp in seconds or milliseconds. Whichever you choose, document it, because the parser will not tell you which one it received.

Keeping sensitive data safe while debugging

Pasting production payloads into online tools can leak tokens and personal data. Prefer a formatter that works entirely in your browser so nothing is transmitted. Before sharing a payload in a bug report, replace secrets, email addresses and access tokens with placeholders.

Frequently asked questions

Can JSON contain comments?
No. Standard JSON has no comment syntax. If you need comments, use a superset such as JSON5 for configuration, and convert to plain JSON before sending it to a strict parser.
What is the difference between JSON and a JavaScript object?
JSON is a text format with stricter rules: double-quoted keys and strings, no trailing commas, no comments, and no functions or undefined values.
Does formatting change the data?
No. Pretty-printing and minifying only change whitespace between tokens. The parsed value is identical.

More guides