Understanding JSON
Six types, one syntax.
The smallest data format that's good enough — and the rules people quietly get wrong.
The six value types.
Every JSON value is one of six things: a string in double quotes, a number (no quotes, no leading plus, no trailing dot), a boolean (true or false), null, an array in square brackets, or an object in curly braces. Arrays and objects can nest indefinitely; everything else is a leaf. Six types, no surprises.
string · number · bool · null · array · object
The strict rules.
JSON is fussier than most people remember. Object keys must be double-quoted strings — single quotes don't count. There are no trailing commas after the last item in an array or object; adding one is invalid JSON, even though every modern language permits it. There are no comments — JSON has no syntax for them at all. If you need comments, you need JSON5 or YAML, not JSON.
The number trap.
JSON's numbers are double-precision floats — IEEE 754, fifteen significant digits. That means an integer larger than about 9 × 10¹⁵ (Number.MAX_SAFE_INTEGER in JavaScript) can't be represented exactly. Twitter learnt this the painful way: their snowflake IDs overflowed double precision and the API had to start returning them as strings. If you're encoding a large user id or a transaction reference, send it as a string, not a number.
safe range: ±2⁵³ ≈ 9.007 × 10¹⁵
String escapes.
Strings in JSON are double-quoted UTF-8 text. The backslash escapes \", \\, \n, \r, \t work as you expect. Unicode escapes use \u followed by four hex digits — though characters outside the basic multilingual plane need a surrogate pair (two \u sequences). Most of the time, just paste the actual character.
Whitespace doesn't matter (until it does).
JSON parsers accept any amount of whitespace between tokens. Pretty-printing is purely a courtesy to humans — both forms parse to the same data structure. The choice between two-space, four-space, or no indentation is style; both minified and indented JSON ship reliably across every language that speaks JSON. The indented form is for reading; the minified form is for the wire.
What JSON deliberately leaves out.
JSON has no date type, no binary type, no NaN, no Infinity, no schema, no comments, no references. Every JSON document is a finite tree of the six types above. When you need dates, encode them as ISO 8601 strings; for binary data, Base64; for schema, JSON Schema (a separate specification). The minimalism is the whole point — it's why JSON beat XML.
JSON5 and the relaxed cousins.
JSON5 adds back what JSON deliberately left out: trailing commas, single-quoted strings, unquoted keys, comments, NaN and Infinity. It's a humans- editing-config-files format, not a wire format. Use it for configuration; use plain JSON for data interchange. The two look almost identical until they don't.
Read next