JSON Formatting Rules & the Errors That Break Parsers

JSON lesson · 8-minute read

Most "invalid JSON" messages come from the same handful of mistakes. Here is the practical rule set — what JSON allows, what it forbids, and the exact error you will see when you slip. Paste any example into the JSON Formatter to watch it pass or fail in real time.

1. Strings and keys: double quotes only

Every string value and every object key must be wrapped in double quotes. Single quotes and unquoted keys are both invalid.

{ "ok": "yes" }      ✓
{ 'ok': 'yes' }      ✗  →  "Unexpected token ' in JSON"
{ ok: "yes" }        ✗  →  "Unexpected token o in JSON"

Fix: replace every ' with " and quote every key.

2. No trailing commas

Commas go between items, never after the last one — in both arrays and objects.

[1, 2, 3]            ✓
[1, 2, 3,]           ✗  →  "Unexpected token ] in JSON"
{ "a": 1, "b": 2, }  ✗  →  "Unexpected token } in JSON"

Fix: delete the comma before the closing ] or }. This is the number-one JSON error.

3. Matching brackets and braces

Every { needs a } and every [ needs a ], correctly nested. A missing closer usually shows up as an error at the very end of the document.

{ "items": [1, 2, 3 }   ✗  →  "Unexpected token } ... expected ]"

Fix: format the document — proper indentation makes an unbalanced bracket obvious at a glance.

4. No comments

JSON has no comment syntax. Both // and /* */ are rejected.

{
  // the user's name
  "name": "Ada"
}                       ✗  →  "Unexpected token / in JSON"

Fix: remove the comment, or store the note as a real field such as "_note": "the user's name".

5. Numbers follow one grammar

Numbers are written in plain decimal: an optional minus, digits, an optional fraction, an optional exponent. No leading zeros, no + sign, no hex, and crucially no NaN or Infinity.

{ "a": 42, "b": -0.75, "c": 1e3 }   ✓
{ "a": 007 }                        ✗  leading zero
{ "a": NaN }                        ✗  →  "Unexpected token N in JSON"

Fix: drop leading zeros; represent "not a number" as null or a string.

6. Escape special characters in strings

Inside a string, a literal double quote, backslash, or newline must be escaped with a backslash. Raw control characters are not allowed.

{ "path": "C:\\Users\\ada" }        ✓  escaped backslashes
{ "quote": "she said \"hi\"" }      ✓  escaped quotes
{ "path": "C:\Users" }              ✗  →  "Bad escaped character"

Fix: double every backslash and escape inner quotes. Need to embed binary or odd bytes in a string safely? That is what Base64 is for.

7. One top-level value, UTF-8, no BOM

A JSON document is a single value — usually one object or array. Two values side by side is invalid, and a stray byte-order mark at the start of the file will trip some parsers.

{"a":1}{"b":2}        ✗  →  "Unexpected non-whitespace after JSON"

Fix: wrap multiple records in an array: [{"a":1},{"b":2}].

Why these rules, not others?

None of this is arbitrary — each rule removes an ambiguity so that every parser, in every language, reads your data the same way. For the reasoning behind the strictness, see why JSON needs a strict format. New to the format entirely? Start with what JSON is.

Next: Base64 Lessons →