JSON (JavaScript Object Notation) is the most common format for exchanging data between programs. It is defined by RFC 8259 and ECMA-404, and its whole grammar fits on one page, which is part of why it became so popular.

The six kinds of value

A JSON document is exactly one value, and every value is one of these:

TypeExampleNotes
Object{"name": "Ana", "age": 31}Keys must be strings in double quotes
Array[1, 2, 3]Items can be any values, mixed
String"café \"quoted\""Double quotes only; escapes start with \
Number-12.5e3Decimal only; no leading zeros, no NaN or Infinity
Booleantrue, falseLowercase
NullnullLowercase

Whitespace (spaces, tabs and line breaks) is allowed between tokens and has no meaning. That is why the same data can be shown formatted over many lines or minified onto one.

Strings and escapes

Inside a string, only these escapes are allowed: \" \\ \/ \b \f \n \r \t and \u followed by four hexadecimal digits, such as é for é. Line breaks and tabs cannot appear literally inside a string; they must be written as \n and \t. Characters outside the first 65,536 code points, including most emoji, can be written directly or as a pair of \u escapes.

The mistakes that break JSON

Most invalid JSON comes from writing it like JavaScript:

  • Trailing commas: [1, 2, 3,] and {"a": 1,} are invalid.
  • Single quotes: {'a': 'b'} is invalid; use double quotes.
  • Unquoted keys: {a: 1} is invalid; write {"a": 1}.
  • Comments: // and /* */ are not part of JSON.
  • JavaScript values: undefined, NaN, Infinity and functions do not exist in JSON.
  • Number formats: 007, +1, .5, 1. and hexadecimal 0x1F are all invalid.
  • Two values in one document: {"a":1}{"b":2} is two documents. Formats that store one JSON value per line, such as JSON Lines, must be read line by line.

The JSON Formatter & Validator reports the line and column of the first of these errors.

Large numbers and duplicate keys

The JSON grammar puts no limit on numbers, but programs do. JavaScript stores every number as a 64-bit floating-point value, which represents whole numbers exactly only up to 9,007,199,254,740,991 (2⁵³ − 1). Parse {"id": 12345678901234567890} with JSON.parse and the id becomes 12345678901234567000. APIs that use large IDs often send them as strings for this reason.

Duplicate keys, as in {"a": 1, "a": 2}, are allowed by the grammar, but RFC 8259 notes that programs handle them differently; many keep only the last value. Avoid them in JSON you produce.

JSON versus similar formats

  • JSON5 and JSONC add comments, trailing commas and other conveniences. They are used for configuration files, but standard JSON parsers reject them.
  • JSON Lines (also called NDJSON) stores one JSON value per line, which suits logs and streaming.
  • YAML can represent the same data with indentation instead of brackets; YAML 1.2 is designed so that JSON documents are also valid YAML.