2. Syntax and types
- Know the whole JSON grammar: it is small, and knowing all of it avoids 90% of mistakes.
- Write strings with special characters (
",\, newlines, Unicode) by hand without errors. - Understand what can sit “at the top” of a document and which
Content-Typegoes with it. - Validate JSON from the terminal with
python -m json.toolandjq.
Theory: the grammar on one page
Section titled “Theory: the grammar on one page”RFC 8259 defines JSON with a handful of rules. A value is one of these seven things:
valore = oggetto | array | stringa | numero | true | false | null(oggetto = object, stringa = string, numero = number.)
Object
Section titled “Object”Braces, zero or more members separated by commas. Each member is string : value. The key is always a string in double quotes.
{ "id": 7, "title": "Oltre Trieste", "in_stock": false }{}Square brackets, zero or more values separated by commas. The values can be of different types (but in practice a “mixed” array is almost always a design mistake).
["Strega", "Bancarella"][1, "due", true, null, {"tre": 3}, [4]][]String
Section titled “String”Double quotes, any Unicode character except ", \ and the control characters (below U+0020), which must be escaped:
| Sequence | Meaning |
|---|---|
\" |
double quote |
\\ |
backslash |
\/ |
slash (escaping is optional) |
\n \t \r |
newline, tab, carriage return |
\b \f |
backspace, form feed |
\uXXXX |
Unicode character with 4 hex digits, e.g. è = è |
Characters outside the Basic Multilingual Plane (emoji, for example) are written as a surrogate pair: 😀 is written 😀. But since JSON is UTF-8, you can write "caffè 😀" directly: escapes are only needed if you want to stay in pure ASCII.
"Ha detto: \"ciao\"\nSeconda riga — fine"Number
Section titled “Number”An optionally negative integer, with a fractional part and/or an exponent:
-? (0 | [1-9][0-9]*) (.[0-9]+)? ([eE][+-]?[0-9]+)?Valid: 0, -12, 18.71, 1e3, 6.02E-23. Not valid: 01 (leading zero), .5, 5., +3, 0x1F, NaN, Infinity. JSON does not distinguish integers from decimals: 2002 and 2002.0 are both “numbers”; it is the language that interprets them (chapter 3).
Literals
Section titled “Literals”true, false, null — lowercase, no quotes. True, NULL, None are errors.
Whitespace
Section titled “Whitespace”Space, tab and newline (\n, \r) are allowed between tokens, anywhere. That is all that separates a “compact” JSON from an “indented” one:
{"id":7,"awards":["Strega"]}{ "id": 7, "awards": [ "Strega" ]}MIME type
Section titled “MIME type”The official type is application/json. The charset is implicitly UTF-8 (RFC 8259 makes it mandatory for interchange), so application/json; charset=utf-8 is redundant but harmless. Variants like text/json are historical mistakes.
curl, explained: looking at the Content-Type
Section titled “curl, explained: looking at the Content-Type”Let’s request a book and ask curl to also show the response headers:
curl -s -i https://corso-api-json.giuseppebosi.com/api/v1/books/7- -s
- silent: no progress bar
- -i
- include: also prints the status line and the HTTP response headers, before the body
- /api/v1/books/7
- the resource: the book with id 7
Response (headers shortened):
HTTP/1.1 200 OKcontent-type: application/jsonetag: "…"cache-control: public, max-age=60
{"id":7,"title":"Oltre Trieste","isbn":"978-88-36071-007-2","author_id":12,"category_id":3,"price":28.25,"pages":642,"published_year":2001,"language":"es","in_stock":false,"attributes":{"format":"tascabile","cover":"morbida","awards":["Strega","Bancarella"],"dimensions_cm":{"w":14,"h":23},"ebook":true},"created_at":"2024-11-27T00:00:00Z","reviews_count":4,"avg_rating":3.5}content-type: application/json is the contract: “the body is JSON, decode it as UTF-8”. The body is compact (no extra whitespace): over the wire, indentation costs bytes. Notice all the types in a single response: numbers (28.25, 642), strings, false, a nested object (attributes), an array (awards); null is not here but can appear (avg_rating is null for books with no reviews).
Response headers
Validating from the terminal
Section titled “Validating from the terminal”Two tools worth having at your fingertips.
curl -s https://corso-api-json.giuseppebosi.com/api/v1/books/7 | python3 -m json.tool- |
- the shell pipe: the output of curl becomes the input of the command on the right
- python3 -m json.tool
- a standard library module: reads JSON from stdin, validates it and prints it indented. If it is not valid it exits with an error and the position
curl -s https://corso-api-json.giuseppebosi.com/api/v1/books/7 | jq '.attributes.awards'- jq
- a command-line tool for JSON (to install:
apt install jq,brew install jq,winget install jqlang.jq) - '.attributes.awards'
- the filter:
.is the document,.attributesgoes into the key,.awardsinto the sub-key. The single quotes stop the shell from interpreting special characters
Output: ["Strega", "Bancarella"]. We will go deeper into jq in chapter 10.
Python and TypeScript: validating a string
Section titled “Python and TypeScript: validating a string”# python3 sintassi.pyimport json
validi = ['{"id": 7}', '[1, 2, 3]', '"solo una stringa"', '42', 'null', '{"s": "caff\\u00e8 \\"ok\\""}']non_validi = ["{'id': 7}", '{"id": 7,}', '[01]', 'True', '{"a": NaN}', '{"s": "a capo\nreale"}']
for testo in validi + non_validi: try: valore = json.loads(testo) print("VALIDO ", repr(testo), "->", repr(valore)) except json.JSONDecodeError as e: print("NON VALIDO", repr(testo), "->", e.msg, "alla posizione", e.pos)What you should see:
VALIDO '{"id": 7}' -> {'id': 7}VALIDO '[1, 2, 3]' -> [1, 2, 3]VALIDO '"solo una stringa"' -> 'solo una stringa'VALIDO '42' -> 42VALIDO 'null' -> NoneVALIDO '{"s": "caff\\u00e8 \\"ok\\""}' -> {'s': 'caffè "ok"'}NON VALIDO "{'id': 7}" -> Expecting property name enclosed in double quotes alla posizione 1NON VALIDO '{"id": 7,}' -> Illegal trailing comma before end of object alla posizione 8NON VALIDO '[01]' -> Expecting ',' delimiter alla posizione 2NON VALIDO 'True' -> Expecting value alla posizione 0VALIDO '{"a": NaN}' -> {'a': nan}NON VALIDO '{"s": "a capo\nreale"}' -> Invalid control character at alla posizione 13Watch out for one detail: json.loads('{"a": NaN}') in Python does not fail, because the module accepts NaN, Infinity and -Infinity as an extension. We discuss it in chapter 3.
// node --experimental-strip-types sintassi.tsconst validi = ['{"id": 7}', '[1, 2, 3]', '"solo una stringa"', '42', 'null', '{"s": "caff\\u00e8 \\"ok\\""}'];const nonValidi = ["{'id': 7}", '{"id": 7,}', '[01]', 'True', '{"a": NaN}', '{"s": "a capo\nreale"}'];
for (const testo of [...validi, ...nonValidi]) { try { const valore: unknown = JSON.parse(testo); console.log("VALIDO ", JSON.stringify(testo), "->", valore); } catch (e) { console.log("NON VALIDO", JSON.stringify(testo), "->", (e as SyntaxError).message); }}What you should see:
VALIDO "{\"id\": 7}" -> { id: 7 }VALIDO "[1, 2, 3]" -> [ 1, 2, 3 ]VALIDO "\"solo una stringa\"" -> solo una stringaVALIDO "42" -> 42VALIDO "null" -> nullVALIDO "{\"s\": \"caff\\u00e8 \\\"ok\\\"\"}" -> { s: 'caffè "ok"' }NON VALIDO "{'id': 7}" -> Expected property name or '}' in JSON at position 1 (line 1 column 2)NON VALIDO "{\"id\": 7,}" -> Expected double-quoted property name in JSON at position 9 (line 1 column 10)NON VALIDO "[01]" -> Unexpected number in JSON at position 2 (line 1 column 3)NON VALIDO "True" -> Unexpected token 'T', "True" is not valid JSONNON VALIDO "{\"a\": NaN}" -> Unexpected token 'N', "{"a": NaN}" is not valid JSONNON VALIDO "{\"s\": \"a capo\nreale\"}" -> Bad control character in string literal in JSON at position 13 (line 1 column 14)Here NaN is rejected: JSON.parse follows the standard to the letter.
Exercise
Section titled “Exercise”Try it online, nothing to install:
The GET request straight in your browser: https://corso-api-json.giuseppebosi.com/api/v1/books/7
Python on Google Colab (a free Google account is needed to run the cells); TypeScript on StackBlitz (it opens and starts by itself in the browser). If the practice API is switched off, turn it on from /en/api-attiva/.
Which of these are valid JSON? For each one that is not, say why.
{"a": 1, "b": [true, null]}{"a": 'uno'}[1, 2, 3,]{"nome": "O\"Brien"}"2024-11-27T00:00:00Z"{a: 1}1.
Then check your answer by sending each one to /api/v1/echo (the server tells you whether it understood it as JSON, field json, or received it as raw text, field _raw):
Response headers
Solution
- Valid.
- Not valid: single quotes.
- Not valid: trailing comma.
- Valid:
\"is the correct escape. - Valid: a document can be a single string (any top-level value).
- Not valid: unquoted key (that is JavaScript syntax, not JSON).
- Not valid: at least one digit is required after the dot.
Common mistakes
Section titled “Common mistakes”- Unquoted or single-quoted keys (
{a: 1},{'a': 1}): fine in JavaScript, not in JSON. - Comma after the last element:
[1,2,],{"a":1,}. - A “real” newline inside a string instead of
\n. - Leading zero (
007),+,.5: non-conforming numbers. - Wrong or missing
content-typein requests: the server responds 415 or 422 (Section 2, chapter 7).
Summary
Section titled “Summary”Seven value types, two containers, always double quotes, escapes for special characters, free whitespace between tokens, application/json as the label. Next chapter: what JSON cannot do (dates, precision, comments) and how to live with it.