What JSON is
JSON (JavaScript Object Notation) is a text format for structured data. It borrowed its look from JavaScript, but it is a separate, much smaller language defined in RFC 8259 and ECMA-404. Almost every programming language can read and write it, so it is common in web APIs and configuration files. The rules are short and strict: a parser accepts a document or rejects it.
The six value types
Any JSON value is exactly one of these:
- Object: an unordered set of name/value pairs in curly braces,
{"key": value}. Names are always strings. - Array: an ordered list of values in square brackets,
[1, "two", null]. The values need not share a type. - String: Unicode text in double quotes.
- Number: a decimal number, optionally negative, with an optional fraction and exponent.
- Boolean: the bare words
trueorfalse, in lowercase. - Null: the bare word
null, meaning no value.
There is no date type and no binary type. Dates usually travel as ISO 8601 strings and binary data as Base64 text. A bare number or string is also a valid JSON document.
A valid example
{
"id": 42,
"name": "Ada Lovelace",
"active": true,
"score": 98.5,
"tags": ["math", "engines"],
"manager": null,
"address": {"city": "London", "zip": "W1"}
}
Objects and arrays nest to any depth, so the address member holds an object and tags holds an array. Whitespace around tokens is ignored, so the document could sit on one line with the same meaning.
The strict rules
- Strings and object keys use double quotes. Single quotes are not allowed anywhere.
- No trailing commas after the last item of an object or array.
- No comments, neither
//nor/* */. - No
undefined,NaNorInfinity. Usenullor a string instead. - Keys within one object should be unique. The standard does not say which value wins when a key repeats; Python's parser keeps the last one, other parsers may differ.
- Documents sent from one system to another should use UTF-8; see character encoding for what that means.
Escapes inside strings
A backslash starts an escape sequence. The complete list is short: \" for a double quote, \\ for a backslash, \/ for a slash, \b backspace, \f form feed, \n newline, \r carriage return and \t tab. Any other letter after a backslash is an error. Control characters from U+0000 to U+001F, including a real line break, may not appear raw inside a string and must be escaped.
The form \uXXXX writes any character by its four-digit hex code. The string "caf\u00e9 \u20ac" parses to café €. Characters beyond U+FFFF, such as most emoji, need two escapes in a row, called a surrogate pair: "\ud83d\ude00" is one character, U+1F600. Encoders that escape all non-ASCII text produce output such as "\u00e9 \u20ac \ud83d\ude00" for the input "é € 😀"; that is equally valid, only longer.
Numbers
JSON numbers are written in base 10. A minus sign is allowed in front, a plus sign is not. There must be at least one digit on each side of a decimal point, so 0.5 is valid and .5 and 5. are not. A leading zero is only allowed for the number zero itself or before a decimal point. Exponents use e or E, as in 1e3 or -2.5E-4.
The format sets no size limit, but the reader does. JavaScript stores every number as a 64-bit float, which represents integers exactly only up to 9,007,199,254,740,992. Above that, neighbouring integers collapse together: 9,007,199,254,740,993 reads as 9,007,199,254,740,992. Large IDs are therefore often sent as strings.
JSON vs a JavaScript object literal
A JavaScript object literal looks similar but is code, not data. JavaScript allows unquoted keys, single quotes, trailing commas, comments, functions and undefined. None of those is valid JSON. Pasting a JavaScript object into a .json file is a frequent cause of parse errors. In JavaScript, read JSON with JSON.parse, never eval. If you want comments and looser syntax in configuration, a format such as YAML may suit the job.
Invalid examples and what the parser says
Each snippet below was fed to Python's json.loads, which raised a JSONDecodeError. The message column shows the text of each error. Other parsers word their errors differently. In the raw line break row, the string contains an actual newline character.
| Problem | Input | Python message | Fix |
|---|---|---|---|
| Single quotes | {'name': 'Ada'} | Expecting property name enclosed in double quotes | Strings and keys must use double quotes. |
| Unquoted key | {name: "Ada"} | Expecting property name enclosed in double quotes | Every object key must be a quoted string. |
| Trailing comma | {"a": 1, "b": 2,} | Expecting property name enclosed in double quotes | A comma must be followed by another member. |
| Comment | {"a": 1 // note } | Expecting ',' delimiter | JSON has no comment syntax at all. |
| undefined | {"x": undefined} | Expecting value | Only true, false and null are allowed as bare words. |
| Leading zero | {"n": 007} | Expecting ',' delimiter | Numbers other than 0 cannot start with 0. |
| Hex number | {"n": 0x1F} | Expecting ',' delimiter | Only decimal numbers are allowed. |
| Bare decimal point | {"n": .5} | Expecting value | A digit is required before the point. |
| Raw line break | {"s": "line1 line2"} | Invalid control character at | Control characters in strings must be escaped. |
| Unknown escape | {"p": "C:\temp\x"} | Invalid \escape | Only the listed escapes are valid. |
Two details in that output are worth knowing when you debug. First, the message often names the next thing the parser expected, not the mistake itself: a trailing comma is reported as a missing property name, and a comment as a missing comma. Look just before the reported position. Second, Python's json module accepts NaN and Infinity by default as an extension, and parses {"x": NaN} to a float. JavaScript's JSON.parse rejects the same text, so a document that loads in Python can still fail elsewhere. Pass a parse_constant function that raises an error if you need strict behaviour.