JSON Syntax Reference

Every value in a JSON document is exactly one of these.

Notably absent: dates, binary data, integers as distinct from floats, sets, references, and any notion of a comment. Objects and arrays nest to any depth, and the two containers may hold values of mixed types — an array of objects and numbers is legal, if usually unwise.

{
  "key": "value",
  "nested": { "inner": 1 },
  "list": [1, 2, 3]
}

Rules:

• Keys must be double-quoted strings. Unquoted keys are a JavaScript thing, not a JSON thing, and are the most common single cause of a parse failure.
• A key may be any string, including the empty string, a string with spaces, or one containing punctuation. {"": 1} and {"user name": 1} are both valid.
• No trailing comma after the last pair.
• An empty object, {}, is valid.
• Keys should be unique but are not required to be — see the surprises section below.
• Member order carries no meaning, and parsers are not required to preserve it.

[
  { "id": 1 },
  { "id": 2 }
]

Rules:

• Elements are ordered, and that order is guaranteed — unlike object members.
• Mixed types are permitted: [1, "a", null, {}, []] is valid.
• No trailing comma after the last element.
• An empty array, [], is valid.
• There are no holes. [1, , 3] is a syntax error, where JavaScript would give you a sparse array.

Arrays are also the answer whenever order or duplication matters, since objects guarantee neither.

Strings are wrapped in double quotes. Single quotes are never valid, anywhere — not for keys, not for values.

Two characters must be escaped inside a string, plus all control characters below U+0020:

Points worth knowing:

• A literal newline inside a string is invalid. It must be written \n. This is why a multi-line SQL query or a PEM certificate pasted straight into a JSON string fails.
• \uXXXX takes exactly four hex digits. Characters outside the Basic Multilingual Plane — emoji, most historic scripts — need a surrogate pair, two escapes together, so an emoji is \ud83d\ude00 rather than one escape.
• You rarely need \u at all. JSON text is Unicode, conventionally UTF-8, so a string may contain é or 日本語 or 😀 directly.
• The forward-slash escape is the odd one out: permitted but never necessary. It exists so JSON can be embedded in HTML without </script> terminating the surrounding tag early.

The mechanics of applying these in anger — nesting JSON inside JSON, or getting a payload through a shell — are in escaping strings in JSON.

A number is an optional minus sign, an integer part, an optional fraction, and an optional exponent.

The grammar imposes no limit on how many digits a number may have. Implementations do: RFC 8259 notes that good interoperability comes from expecting no more precision than IEEE 754 double precision provides, and that integers are interoperable in the range −(2^53)+1 to (2^53)−1 — roughly ±9.007 × 10^15.

Beyond that, digits are silently lost. A 19-digit identifier sent as a number arrives rounded in any JavaScript consumer, and nothing in the pipeline will warn you. Send large identifiers as strings.

NaN and Infinity deserve their own note because serialisers hit them constantly: JavaScript's JSON.stringify turns both into null rather than failing, so a division by zero somewhere upstream becomes a null in your data.

• Encoding. JSON text exchanged between systems must be encoded in UTF-8.
• A byte-order mark is not allowed. Parsers commonly reject a leading BOM, which is why a file saved by a Windows editor as "UTF-8 with BOM" can fail on a first, invisible character. This is a genuinely nasty one to diagnose by eye.
• Whitespace — space, tab, line feed, carriage return — is permitted between any two tokens and is otherwise meaningless. Indentation is for humans.
• The top level may be any value. RFC 8259 defines a JSON text as "a serialized value", so "hello", 42 and true are each a complete valid document. Older parsers written against the 2006 specification may still require an object or array.
• One document per text. Two objects side by side is not valid JSON. Streaming many records means one object per line — JSON Lines — which is a convention on top of JSON, not part of it.

Since a JSON text is exactly one value, a file containing two objects side by side is not valid JSON — which is a problem for logs and data exports, where you want to append records without rewriting the whole file.

The universal answer is JSON Lines, also written NDJSON: one complete JSON document per line, separated by \n.

{"level":"info","msg":"started","ts":"2026-09-07T09:00:00Z"}
{"level":"warn","msg":"retrying","ts":"2026-09-07T09:00:04Z"}
{"level":"error","msg":"gave up","ts":"2026-09-07T09:00:09Z"}

The rules are a convention on top of JSON rather than part of it:

• Each line is an independent, complete JSON value — usually an object.
• No line may contain a literal newline, so every record must be minified onto one line. Escaped \n inside strings is fine.
• The file as a whole is not valid JSON, and parsing it whole will fail. Parse line by line.
• UTF-8, and by convention a trailing newline at the end of the file.

Why it is worth knowing: it makes a file appendable and streamable. A process can write one more record without touching what came before, and a reader can process a hundred-gigabyte file with a few kilobytes of memory — neither of which a single JSON array permits. This is why structured application logs, database exports and machine-learning datasets are almost always in this shape.

The trade-off is that no JSON parser will read the file as a unit, so tooling has to know what it is looking at. If you need one file that is valid JSON, an array is the only option, and you accept that appending means rewriting.

Five widely-believed rules that the specification does not contain.

"Keys must be unique." RFC 8259 says they SHOULD be unique — a recommendation. Duplicates are legal, and the specification warns only that the receiving software's behaviour "is unpredictable". Most parsers keep the last one.

"JSON must start with { or [." True of the 2006 specification, not of RFC 8259. See above.

"Comments are allowed if the parser is lenient." Some parsers do accept them; that does not make the document JSON. There is no production for a comment in the grammar.

"A trailing comma is a warning." It is a hard syntax error, in both objects and arrays. MDN's documentation for JSON.parse demonstrates exactly this failure.

"Key order is preserved." Not guaranteed. Many parsers do preserve insertion order in practice, and JavaScript's does for string keys, but the specification explicitly notes that libraries differ over whether ordering is even visible.

The general shape of the mistake is assuming JSON is JavaScript with a different extension. It is a strict subset — everything JSON allows, JavaScript allows, but not the reverse:

Every row in that table is a parse failure waiting to happen when object-literal text is pasted somewhere expecting JSON. The error-by-error guide covers what each one looks like when it does.

Reference tables settle arguments; a parser settles them faster. Paste the document into the parse tool and it either produces the parsed structure or the exact error, which is usually quicker than reading a table to work out which of two spellings is legal.

For a document rather than a fragment, the formatter reports the error message together with the line it came from, and will attempt a repair of the common structural mistakes — single quotes, bare keys, trailing commas — without touching the contents of your strings.

One caveat that applies to both, and to every other validator: a parser tells you the document is well-formed. It cannot tell you the data is correct. A payload with every field spelled wrong parses perfectly.