What is JSON?

The short definition

JSON — JavaScript Object Notation — is a way of writing structured data as plain text. It was derived from JavaScript’s object syntax in the early 2000s and is now defined independently by ECMA-404 and RFC 8259, which is why every language has a parser for it and none of them need JavaScript.

A JSON document is exactly one value. That value is usually an object or an array, but a bare string, number, boolean or null is a complete, valid JSON document on its own.

The six types

• object — an unordered set of key/value pairs in braces. Keys must be strings in double quotes.
• array — an ordered list in square brackets. Elements do not have to share a type.
• string — double-quoted text. Single quotes are never valid.
• number — an optionally signed decimal, with an optional fraction and exponent. No leading +, no leading zero, no hex, no NaN, no Infinity.
• true / false — the two booleans, lowercase.
• null — the empty value, lowercase.

{
  "id": 4821,
  "name": "Ada Lovelace",
  "active": true,
  "retiredOn": null,
  "roles": ["admin", "author"],
  "profile": { "city": "London", "since": 1843 }
}

What is not allowed

Most invalid JSON is invalid for one of the same few reasons, and all of them are things JavaScript itself permits. That mismatch is why "it works in my editor" is not evidence that a document is valid JSON.

• Comments. There are no // or /* */ comments in JSON, at all.
• Trailing commas. A comma before } or ] is a syntax error.
• Unquoted keys. {name: "x"} is a JavaScript object literal, not JSON.
• Single-quoted strings. 'x' is not a JSON string.
• undefined, NaN and Infinity. None of these exist in JSON.
• Leading zeros and a leading plus on numbers. 007 and +5 are both invalid.
• Literal control characters inside strings — a raw newline must be written \n.

Things the specification leaves open

Two documents can both be valid JSON and still be handled differently by two parsers, because the grammar deliberately does not decide everything.

Duplicate keys are the clearest case: {"a":1,"a":2} is valid, and the specification does not say which value wins. Almost every parser keeps the last, but nothing requires it. Object key order is likewise not meaningful — some parsers preserve it, and none are obliged to.

Number precision is the other one. JSON numbers have no defined range, but a parser built on IEEE-754 doubles — which includes every JavaScript parser — cannot hold an integer above 9,007,199,254,740,991 exactly. Large ids silently change value.

JSON is not a JavaScript object

The names look alike and the confusion is constant, but they are different things. JSON is text; a JavaScript object is a runtime value. JSON.parse turns the first into the second, and JSON.stringify goes back.

JSON is also a strict subset of what JavaScript object literal syntax allows. Everything valid in JSON is valid JavaScript; the reverse is emphatically not true.