2. Sintassi e tipi
Obiettivi
Sezione intitolata “Obiettivi”- Conoscere tutta la grammatica JSON: è piccola, e conoscerla per intero evita il 90% degli errori.
- Scrivere a mano stringhe con caratteri speciali (
",\, a capo, Unicode) senza sbagliare. - Capire cosa può stare “in cima” a un documento e quale
Content-Typelo accompagna. - Validare un JSON dal terminale con
python -m json.toolejq.
Teoria: la grammatica in una pagina
Sezione intitolata “Teoria: la grammatica in una pagina”RFC 8259 definisce JSON con una manciata di regole. Un valore è una di queste sette cose:
valore = oggetto | array | stringa | numero | true | false | nullOggetto
Sezione intitolata “Oggetto”Graffe, zero o più membri separati da virgola. Ogni membro è stringa : valore. La chiave è sempre una stringa tra doppi apici.
{ "id": 7, "title": "Oltre Trieste", "in_stock": false }{}Quadre, zero o più valori separati da virgola. I valori possono essere di tipi diversi (ma nella pratica un array “misto” è quasi sempre un errore di progettazione).
["Strega", "Bancarella"][1, "due", true, null, {"tre": 3}, [4]][]Stringa
Sezione intitolata “Stringa”Doppi apici, qualsiasi carattere Unicode tranne ", \ e i caratteri di controllo (sotto U+0020), che vanno escapati:
| Sequenza | Significato |
|---|---|
\" |
doppio apice |
\\ |
barra rovesciata |
\/ |
barra (l’escape è facoltativo) |
\n \t \r |
a capo, tabulazione, ritorno carrello |
\b \f |
backspace, form feed |
\uXXXX |
carattere Unicode con 4 cifre esadecimali, es. \u00e8 = è |
I caratteri fuori dal Basic Multilingual Plane (emoji, per esempio) si scrivono come coppia surrogata: 😀 si scrive \ud83d\ude00. Ma dato che JSON è UTF-8, puoi scrivere direttamente "caffè 😀": gli escape servono solo se vuoi restare in ASCII puro.
"Ha detto: \"ciao\"\nSeconda riga — fine"Un intero opzionalmente negativo, con parte frazionaria e/o esponente:
-? (0 | [1-9][0-9]*) (.[0-9]+)? ([eE][+-]?[0-9]+)?Validi: 0, -12, 18.71, 1e3, 6.02E-23. Non validi: 01 (zero iniziale), .5, 5., +3, 0x1F, NaN, Infinity. JSON non distingue interi da decimali: 2002 e 2002.0 sono entrambi “numeri”; è il linguaggio che li interpreta (capitolo 3).
Letterali
Sezione intitolata “Letterali”true, false, null — minuscoli, senza apici. True, NULL, None sono errori.
Spazi bianchi
Sezione intitolata “Spazi bianchi”Spazio, tab, a capo (\n, \r) sono ammessi tra i token, ovunque. Questo è tutto ciò che distingue un JSON “compatto” da uno “indentato”:
{"id":7,"awards":["Strega"]}{ "id": 7, "awards": [ "Strega" ]}MIME type
Sezione intitolata “MIME type”Il tipo ufficiale è application/json. Il charset è implicitamente UTF-8 (RFC 8259 lo rende obbligatorio per lo scambio), quindi application/json; charset=utf-8 è ridondante ma innocuo. Varianti come text/json sono errori storici.
curl, spiegato: guardiamo il Content-Type
Sezione intitolata “curl, spiegato: guardiamo il Content-Type”Chiediamo un libro chiedendo a curl di mostrare anche gli header della risposta:
curl -s -i https://corso-api-json.giuseppebosi.com/api/v1/books/7- -s
- silent: niente barra di avanzamento
- -i
- include: stampa anche la riga di stato e gli header HTTP della risposta, prima del corpo
- /api/v1/books/7
- la risorsa: il libro con id 7
Risposta (header abbreviati):
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 è il contratto: “il corpo è JSON, decodificalo come UTF-8”. Il corpo è compatto (nessuno spazio superfluo): sul filo le indentazioni costano byte. Nota tutti i tipi in una sola risposta: numeri (28.25, 642), stringhe, false, un oggetto annidato (attributes), un array (awards), e null non c’è ma può comparire (avg_rating è null per i libri senza recensioni).
Header della risposta
Validare dal terminale
Sezione intitolata “Validare dal terminale”Due strumenti che vale la pena avere sotto le dita.
curl -s https://corso-api-json.giuseppebosi.com/api/v1/books/7 | python3 -m json.tool- |
- la pipe della shell: l'output di curl diventa l'input del comando a destra
- python3 -m json.tool
- modulo della libreria standard: legge JSON da stdin, lo valida e lo ristampa indentato. Se non è valido esce con errore e posizione
curl -s https://corso-api-json.giuseppebosi.com/api/v1/books/7 | jq '.attributes.awards'- jq
- strumento a riga di comando per JSON (da installare:
apt install jq,brew install jq,winget install jqlang.jq) - '.attributes.awards'
- il filtro:
.è il documento,.attributesentra nella chiave,.awardsnella sotto-chiave. Gli apici singoli impediscono alla shell di interpretare i caratteri speciali
Output: ["Strega", "Bancarella"]. Approfondiremo jq nel capitolo 10.
Python e TypeScript: validare una stringa
Sezione intitolata “Python e TypeScript: validare una stringa”# 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)Cosa dovresti vedere:
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 13Attenzione a un dettaglio: json.loads('{"a": NaN}') in Python non fallisce, perché il modulo accetta NaN, Infinity e -Infinity come estensione. Ne parliamo nel capitolo 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); }}Cosa dovresti vedere:
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)Qui NaN è rifiutato: JSON.parse segue lo standard alla lettera.
Esercizio
Sezione intitolata “Esercizio”Provalo online, senza installare nulla:
La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/books/7
Python su Google Colab (serve un account Google gratuito per eseguire le celle); TypeScript su StackBlitz (si apre e parte da solo nel browser). Se l’API di prova è spenta, accendila da /api-attiva/.
Quali di questi sono JSON validi? Per ognuno, se non lo è, di’ perché.
{"a": 1, "b": [true, null]}{"a": 'uno'}[1, 2, 3,]{"nome": "O\"Brien"}"2024-11-27T00:00:00Z"{a: 1}1.
Poi verifica la tua risposta inviando ciascuno a /api/v1/echo (il server ti dice se lo ha capito come JSON, campo json, o se lo ha ricevuto come testo grezzo, campo _raw):
Header della risposta
Soluzione
- Valido.
- Non valido: apici singoli.
- Non valido: virgola finale.
- Valido:
\"è l’escape corretto. - Valido: un documento può essere una singola stringa (top-level qualsiasi).
- Non valido: chiave senza apici (è sintassi JavaScript, non JSON).
- Non valido: dopo il punto serve almeno una cifra.
Errori comuni
Sezione intitolata “Errori comuni”- Chiavi senza apici o con apici singoli (
{a: 1},{'a': 1}): vale in JavaScript, non in JSON. - Virgola dopo l’ultimo elemento:
[1,2,],{"a":1,}. - A capo “vero” dentro una stringa invece di
\n. - Zero iniziale (
007),+,.5: numeri non conformi. content-typesbagliato o assente nelle richieste: il server risponde 415 o 422 (Sezione 2, capitolo 7).
In sintesi
Sezione intitolata “In sintesi”Sette tipi di valore, due contenitori, doppi apici sempre, escape per i caratteri speciali, spazi liberi tra i token, application/json come etichetta. Nel prossimo capitolo: quello che JSON non sa fare (date, precisione, commenti) e come conviverci.