Che cos’è un file JSON?

JSON è un formato di testo semplice che si apre in qualsiasi editor. Si usa per spostare dati fra programmi e il web.

L’estensione è .json e il nome per esteso è JavaScript Object Notation. Contano entrambi meno di ciò che il file può contenere, ed è di questo che parla il resto della pagina.

Risale al 2001. La specifica è RFC 8259.

L’età serve saperla per un motivo pratico: più un formato è vecchio, più programmi hanno avuto tempo di impararlo.

È pubblicata per intero, quindi la si può implementare partendo dal documento invece che per osservazione: è per questo che il formato compare in così tanti programmi, ed è per questo che file scritti vent’anni fa si aprono ancora. Una specifica pubblicata però non è la stessa cosa di una esente da royalty: dove un formato incapsula un codec, le licenze sui brevetti restano una questione a parte che lo standard non risolve.

JSON conserva il suo contenuto esattamente. Risalvarlo non cambia nulla, quindi puoi aprirlo, modificarlo e risalvarlo quante volte vuoi senza accumulare danni: è questo che ne fa un formato di lavoro e non di consegna.

JSON non ha una sintassi per i commenti. Tutto ciò che spiega deve vivere fuori dal file, ed è bene saperlo prima di sceglierlo per qualcosa che una persona modificherà a mano.

Visual Studio Code, jq e Postman lo leggono, e così fanno quasi tutti i programmi dello stesso tipo.

Quando un file non si apre, il formato è raramente il problema: più spesso è il programma a essere più vecchio di lui. Convertire in qualcosa di più vecchio è la via d’uscita affidabile, ed è a questo che serve il resto di questo sito.

Qualsiasi browser attuale lo legge.

Puoi quindi metterlo su una pagina o allegarlo a un messaggio senza chiederti che cosa abbia installato chi lo riceve.

JSON è pensato per essere aperto e modificato. Tieni il file in questo formato per tutto il tempo in cui il lavoro va avanti, ed esporta da lì ogni volta che serve una copia finita.

Un documento JSON è costruito da oggetti, array, stringhe, numeri, booleani e null. È l’intero vocabolario, e la brevità dell’elenco è la ragione per cui il formato ha preso il sopravvento: ogni linguaggio di programmazione ha già tutti e sei, quindi leggere un documento significa chiamare una funzione e ricevere indietro valori nativi senza nulla da mappare.

La specifica sta in poche pagine. È stata descritta più che progettata — Douglas Crockford ha preso la sintassi degli oggetti letterali che JavaScript aveva già e ha scritto ciò che già funzionava — motivo per cui sembra ovvia invece che ingegnosa.

Il JSON non ha commenti, deliberatamente, ed è la proprietà più lamentata del formato. Il ragionamento era che i commenti invitano direttive di parsing, e il risultato è che il JSON è un povero linguaggio di configurazione per quanto sia buono come formato di trasporto.

Tre ripieghi sono in circolazione. Una chiave chiamata qualcosa come underscore-comment, che qualunque parser accetterà e qualunque validatore di schema rifiuterà. JSON5 e JSONC, che aggiungono commenti e virgole finali e non sono JSON — il file di impostazioni di Visual Studio Code è JSONC, motivo per cui modificarlo in uno strumento rigoroso fallisce. E la risposta onesta, che è usare TOML o YAML per qualunque cosa mantenuta da una persona.

Il JSON non distingue interi da virgola mobile. La maggior parte dei parser legge ogni numero come un double, e un double conserva gli interi esattamente solo fino a circa nove quadrilioni.

Oltre quel limite, i valori cambiano silenziosamente. Un identificativo di database a 64 bit, un ID snowflake in stile Twitter, un grande importo finanziario nell’unità più piccola — tutti possono tornare come un numero diverso da quello inviato, senza alcun errore da nessuna parte. Il rimedio è inviare tali valori come stringhe, cosa che fa ogni API seria, e vale la pena controllarlo piuttosto che presumerlo quando si integra con una che potrebbe non farlo.

Le chiavi duplicate non sono vietate. I parser differiscono in cosa fanno — la maggior parte tiene l’ultima, alcuni tengono la prima, pochi danno errore — e un documento che si affida a un comportamento o all’altro si affida a un’implementazione, non al JSON.

Allo stesso modo l’ordine delle chiavi non è garantito conservato, quindi trattare un oggetto come una struttura ordinata è un errore; usate un array se l’ordine conta. E non ci sono date: la convenzione universale sono le stringhe ISO 8601, e ogni parser vi consegna una stringa che qualcos’altro deve interpretare.

Il JSON è UTF-8. La specifica lo dice per qualunque cosa scambiata fra sistemi, e il corollario pratico è che un byte order mark non è permesso — quei tre byte invisibili all’inizio di un file causano un fallimento di parsing il cui messaggio di solito incolpa il primo carattere invece di nominare la causa.

Se un file JSON fallisce a fare il parsing e sembra perfetto in un editor, è la prima cosa da controllare. «UTF-8 senza BOM» è l’impostazione, ed è lo stesso consiglio di ogni altro formato di testo su questo sito, con la differenza che qui è genuinamente fatale invece che semplicemente fastidioso.

Un documento JSON deve essere completo prima di poter essere analizzato — la parentesi di chiusura è ciò che lo rende valido — quindi un array di record da dieci gigabyte deve essere letto interamente in memoria prima che il primo sia disponibile. Per grandi esportazioni e pipeline di log è fatale.

NDJSON, chiamato anche JSON Lines, lo risolve mettendo un oggetto JSON completo su ogni riga senza array che lo racchiuda. Ogni riga si analizza indipendentemente, quindi un file di qualunque dimensione scorre riga per riga, e un processo può iniziare a lavorare sul primo record immediatamente. Esportazioni di dati, spedizione di log e dataset per l’apprendimento automatico lo usano quasi tutti, ed è il formato a cui ricorrere ogni volta che un file JSON si misura in gigabyte.

JSON Schema è il modo standard per descrivere come appare un documento valido, e vale la pena usarlo per qualunque interfaccia fra due sistemi — trasforma «l’API ha restituito qualcosa di strano» in un errore specifico che nomina il campo. Il supporto è buono e meno uniforme dell’equivalente XML.

Per il lavoro quotidiano, un editor con supporto JSON dà gratis la metà importante: una virgola mancante o finale viene segnalata sul posto, e JSON generato da macchina arrivato come un’unica lunga riga può essere formattato in qualcosa di leggibile. Entrambe sono operazioni da due secondi che risparmiano una quantità sorprendente di tempo.