Skip to content

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-Type goes with it.
  • Validate JSON from the terminal with python -m json.tool and jq.

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.)

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]]
[]

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"

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).

true, false, null — lowercase, no quotes. True, NULL, None are errors.

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"
]
}

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:

terminal
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 OK
content-type: application/json
etag: "…"
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).

GET/api/v1/books/7— book 7: every type in one response

Two tools worth having at your fingertips.

terminal
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
terminal
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, .attributes goes into the key, .awards into 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.py
import 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' -> 42
VALIDO 'null' -> None
VALIDO '{"s": "caff\\u00e8 \\"ok\\""}' -> {'s': 'caffè "ok"'}
NON VALIDO "{'id': 7}" -> Expecting property name enclosed in double quotes alla posizione 1
NON VALIDO '{"id": 7,}' -> Illegal trailing comma before end of object alla posizione 8
NON VALIDO '[01]' -> Expecting ',' delimiter alla posizione 2
NON VALIDO 'True' -> Expecting value alla posizione 0
VALIDO '{"a": NaN}' -> {'a': nan}
NON VALIDO '{"s": "a capo\nreale"}' -> Invalid control character at alla posizione 13

Watch 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.

Try it online, nothing to install:

Open the notebook in Google Colab Open the TypeScript project in StackBlitz

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.

  1. {"a": 1, "b": [true, null]}
  2. {"a": 'uno'}
  3. [1, 2, 3,]
  4. {"nome": "O\"Brien"}
  5. "2024-11-27T00:00:00Z"
  6. {a: 1}
  7. 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):

POST/api/v1/echo— echo: change the body and watch json / _raw
Solution
  1. Valid.
  2. Not valid: single quotes.
  3. Not valid: trailing comma.
  4. Valid: \" is the correct escape.
  5. Valid: a document can be a single string (any top-level value).
  6. Not valid: unquoted key (that is JavaScript syntax, not JSON).
  7. Not valid: at least one digit is required after the dot.
  • 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-type in requests: the server responds 415 or 422 (Section 2, chapter 7).

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.