Salta ai contenuti

2. Sintassi e tipi

  • 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-Type lo accompagna.
  • Validare un JSON dal terminale con python -m json.tool e jq.

RFC 8259 definisce JSON con una manciata di regole. Un valore è una di queste sette cose:

valore = oggetto | array | stringa | numero | true | false | null

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

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

true, false, null — minuscoli, senza apici. True, NULL, None sono errori.

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

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.

Chiediamo un libro chiedendo a curl di mostrare anche gli header della risposta:

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

GET/api/v1/books/7— il libro 7: tutti i tipi in una risposta

Due strumenti che vale la pena avere sotto le dita.

terminale
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
terminale
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, .attributes entra nella chiave, .awards nella sotto-chiave. Gli apici singoli impediscono alla shell di interpretare i caratteri speciali

Output: ["Strega", "Bancarella"]. Approfondiremo jq nel capitolo 10.

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

Cosa dovresti vedere:

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

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

Provalo online, senza installare nulla:

Apri il notebook in Google Colab Apri il progetto TypeScript in StackBlitz

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

  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.

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

POST/api/v1/echo— echo: cambia il body e osserva json / _raw
Soluzione
  1. Valido.
  2. Non valido: apici singoli.
  3. Non valido: virgola finale.
  4. Valido: \" è l’escape corretto.
  5. Valido: un documento può essere una singola stringa (top-level qualsiasi).
  6. Non valido: chiave senza apici (è sintassi JavaScript, non JSON).
  7. Non valido: dopo il punto serve almeno una cifra.
  • 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-type sbagliato o assente nelle richieste: il server risponde 415 o 422 (Sezione 2, capitolo 7).

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.