JSON è un formato rigido che sembra tollerante, ed è per questo che gli si perde dietro così tanto tempo. Un formattatore fa due lavori: rende leggibile un muro di testo minificato e ti dice esattamente dove il parser si è arreso. Il secondo è di solito quello per cui sei arrivato qui.
Le quattro cose che JSON non permette
Quasi tutti gli errori di parsing sono uno degli stessi quattro sbagli, tutti perfettamente legali in JavaScript e illegali in JSON. La virgola dopo l'ultimo elemento. Gli apici singoli invece delle virgolette doppie. Le chiavi senza virgolette: {name: "x"} è un object literal JavaScript, non JSON. E i commenti, che il formato non ha mai supportato in nessun momento della sua vita.
L'ultimo punto frega chi configura strumenti. Se un file di configurazione accetta i commenti, non è JSON: è JSON5 o JSONC, formati identici a vedersi finché un parser rigido non si rifiuta di leggerli. Fuori anche i valori NaN e Infinity, ed è per questo che serializzare il risultato di una divisione può produrre qualcosa che nessun parser riaccetta.
Formattare può riordinarti le chiavi in silenzio
Questa sorprende, e conviene saperla prima di reincollare un file in produzione. Qualsiasi strumento che formatta JSON lo interpreta in memoria e lo riserializza. Per le normali chiavi testuali quel giro preserva l'ordine di inserimento e non si muove niente. Ma le chiavi che sembrano numeri interi non negativi sono speciali: JavaScript le enumera per prime, in ordine numerico crescente, indipendentemente da dove stavano nel tuo file.
Così {"10":"a","2":"b","name":"c"} torna indietro come {"2":"b","10":"a","name":"c"}. I dati sono identici e ogni parser sarà d'accordo, ma un diff riga per riga si accenderà tutto. Se stai formattando un file versionato e indicizzato per ID numerici, mettilo in conto.
I numeri grandi perdono precisione, senza dirtelo
Questa causa bug veri in produzione. JSON non ha un tipo intero: ha i numeri, e JavaScript rappresenta ogni numero come un float a 64 bit. Il che ti dà interi esatti solo fino a 9007199254740991, cioè 2^53−1. Oltre, i valori vengono arrotondati in silenzio al più vicino rappresentabile.
Incolla {"id":9007199254740993} in un qualsiasi strumento JSON basato su browser e ti restituirà 9007199254740992. Nessun errore. Nessun avviso. L'ID è semplicemente sbagliato adesso. È per questo che le API che maneggiano identificatori grandi — Twitter/X, Discord, gli snowflake ID dei database — li mandano come stringhe. Se il tuo JSON contiene ID oltre quella soglia come numeri nudi, non farlo passare da nessuno strumento JavaScript, questo incluso.
Minificare vale meno di quanto sembri
Togliere gli spazi da un JSON taglia tipicamente il 10–20% della dimensione grezza, il che sembra utile finché non ti ricordi che il tuo server quasi certamente lo serve compresso con gzip o brotli. Gli algoritmi di compressione sono bravissimi con gli spazi ripetitivi: per loro sono quasi gratis. Dopo la compressione, la differenza tra JSON formattato e minificato è spesso di un paio di punti percentuali.
Minifica quando stai infilando JSON in un URL, in un attributo data, o dove non verrà compresso. Per una risposta API su HTTP, la leggibilità nel pannello di rete vale di solito più dei byte.
Domande frequenti
Il mio JSON viene inviato a un server?
No. Questo strumento è marcato "client": il parsing e la formattazione girano nella scheda del tuo browser, e il testo non lascia mai la macchina. Detto questo, il JSON incollato da un sistema vero contiene spesso token, anagrafiche clienti o identificatori interni: se è il tuo caso, usa un editor controllato dalla tua organizzazione invece di una qualsiasi pagina web gratuita, questa compresa.
L'errore dice "position 1247" — come la trovo?
Quel numero è uno scostamento in caratteri dall'inizio dell'input, non un numero di riga, il che lo rende scomodo da usare a mano. Formatta prima il documento: una volta indentato, il parser segnala l'errore contro una struttura leggibile e la riga incriminata di solito salta all'occhio. Vale anche la pena sapere che la posizione riportata è dove il parser si è accorto del problema, non sempre dove l'hai commesso: una graffa di chiusura mancante viene spesso segnalata molto sotto la riga davvero sbagliata.
Formattare modifica i miei dati?
Quasi mai, ma quel "quasi" nasconde due casi. Le chiavi che sembrano numeri vengono riordinate, e gli interi oltre 2^53−1 perdono precisione: entrambi spiegati sopra. Tutto il resto torna identico nel significato, anche se gli spazi cambiano.
Posso usare i commenti in un file di configurazione JSON?
Non in JSON vero e proprio. Se il tuo strumento li accetta, sta leggendo JSONC o JSON5, oppure li rimuove prima di interpretare. Molti editor te li lasciano scrivere tranquillamente e poi un parser rigido più a valle rifiuta il file: è un errore confuso da diagnosticare. Se devi annotare un documento JSON e non puoi cambiare formato, il ripiego convenzionale è una chiave sorella tipo "_comment".
Cosa succede con le chiavi duplicate?
La specifica dice che i nomi "dovrebbero" essere unici ma non vieta le ripetizioni, quindi il comportamento dipende dal parser. In pratica JavaScript tiene l'ultima occorrenza e scarta le precedenti senza alcun avviso. Se un documento ha duplicati, formattarlo qui li collasserà in uno solo: è una modifica che potresti non volere, quindi controlla prima di reincollare il risultato.