Glossario

JSON (JavaScript Object Notation)

Il JSON (JavaScript Object Notation) è un formato di testo leggero per rappresentare e scambiare dati strutturati tra programmi. Usa coppie nome-valore ed elenchi, è facile da leggere per le persone e da elaborare per le macchine. È il formato più usato dalle API web per inviare e ricevere informazioni.

Cos’è il JSON e com’è fatto

Un file JSON è un testo che descrive dati con una sintassi minima. Un oggetto è racchiuso tra parentesi graffe e contiene coppie composte da un nome tra virgolette doppie e da un valore. Un elenco, detto array, sta tra parentesi quadre. I valori possono essere testi, numeri, valori vero o falso, il valore nullo, altri oggetti o altri array.

Il formato non ammette commenti e ha regole precise: le virgolette doppie sono obbligatorie e dopo l’ultimo elemento non va messa la virgola. Un errore di sintassi rende l’intero file illeggibile per chi lo elabora.

A cosa serve il JSON

  • Scambio di dati tra client e server attraverso le API, in particolare quelle REST.
  • File di configurazione di applicazioni e strumenti di sviluppo.
  • Archiviazione in database a documenti, come MongoDB, e nelle colonne JSON dei database relazionali.
  • Scambio di dati strutturati con i modelli di intelligenza artificiale, che spesso restituiscono risposte in questo formato.

Differenza tra JSON, XML e YAML

L’XML è più verboso e più ricco: supporta attributi, spazi dei nomi e schemi di validazione molto rigorosi. Il JSON è più compatto e si converte direttamente in strutture dati di quasi ogni linguaggio. Lo YAML è più leggibile da una persona perché usa il rientro invece delle parentesi, e per questo si preferisce nei file di configurazione.

Origine e standard del JSON

Il formato nasce dalla sintassi con cui JavaScript descrive gli oggetti, ma è indipendente dal linguaggio e ha librerie in tutti i linguaggi principali. Douglas Crockford lo ha diffuso all’inizio degli anni Duemila. Oggi è definito da due standard equivalenti: la RFC 8259 dell’IETF e la specifica ECMA-404.

Come controllare un file JSON

Un validatore verifica la sintassi e segnala la riga in cui si trova l’errore. Per i dati scambiati tra sistemi si usa JSON Schema, che descrive i campi attesi, i loro tipi e quali sono obbligatori. Così chi riceve i dati può rifiutare subito le richieste malformate.

Errori comuni nei file JSON

I problemi più frequenti sono la virgola dopo l’ultimo elemento, gli apici singoli al posto delle virgolette doppie, i commenti inseriti nel file e i nomi dei campi senza virgolette. Le date non hanno un tipo proprio e si scrivono come testo, di solito nel formato ISO 8601. Per lo scambio tra sistemi lo standard richiede la codifica UTF-8, che evita problemi con le lettere accentate.

Tipi di dati e strutture annidate

Il JSON conosce sei tipi di valore: testo, numero, valore vero o falso, nullo, oggetto e array. Un oggetto può contenere altri oggetti e altri array, e così si descrivono strutture complesse, come un ordine con i dati del cliente e un elenco di righe. La struttura è ad albero, e per leggere un campo in profondità si segue il percorso dei nomi. L’ordine dei campi in un oggetto non ha significato, mentre quello degli elementi di un array sì.

Come si usa il JSON nei programmi

Quasi tutti i linguaggi hanno funzioni integrate per due operazioni. La lettura, detta parsing, trasforma il testo JSON in oggetti del linguaggio, come i dizionari in Python. La scrittura, detta serializzazione, fa il percorso inverso. Se il testo non rispetta la sintassi, il parsing fallisce con un errore, quindi i programmi che ricevono dati dall’esterno gestiscono questo caso e non si fidano dei campi che trovano senza averli controllati.

JSON Lines, JSON-LD e GeoJSON

Dal formato di base derivano alcune varianti con uno scopo preciso. JSON Lines scrive un oggetto per riga ed è comodo per i registri e per i file molto grandi, che si possono leggere riga per riga. JSON-LD aggiunge ai dati un contesto semantico e si usa per i dati strutturati delle pagine web. GeoJSON descrive punti, linee e aree geografiche e viene letto dalle applicazioni di mappe.

Limiti del JSON

Il formato non prevede commenti e non ha un tipo per le date, quindi ogni sistema deve accordarsi su come scriverle. I numeri molto grandi possono perdere precisione in alcuni linguaggi, come JavaScript, che li tratta come numeri a virgola mobile. Per i volumi elevati, il testo del JSON occupa più spazio e richiede più tempo di formati binari come Protocol Buffers e MessagePack, che rinunciano alla leggibilità per guadagnare velocità.

Convenzioni per un JSON ben progettato

Un’API è più semplice da usare se i suoi JSON seguono regole coerenti. I nomi dei campi hanno una convenzione unica, come camelCase o snake_case, e non si mescolano. Le date e gli orari si scrivono nel formato ISO 8601, con il fuso orario. Un campo assente e un campo nullo hanno significati diversi, e la documentazione dice quale dei due si usa. Gli errori hanno una forma prevedibile, con un codice e un messaggio leggibile.

Fonti e approfondimenti