Formattare JSON

Il documento viene letto per intero, trasformato in strutture dati e riscritto da capo. Non è una questione di eleganza implementativa: vuol dire che un documento rotto non esce formattato a metà, e che quello che esce è per costruzione JSON valido.

La differenza si vede quando qualcosa non torna. Un formattatore che inserisce a capo con un’espressione regolare accetta virgolette sbilanciate, una virgola di troppo e un commento, e ti restituisce un documento più ordinato che nessuna API accetterà. Qui in quel caso non esce niente, ed è la risposta giusta.

La scelta non ha un vincitore tecnico: `JSON.stringify` accetta tutti e tre e nessun parser guarda il rientro. Due spazi è quello che producono la maggior parte degli strumenti e quello che troverai nei file di configurazione di un progetto JavaScript; quattro è la convenzione di parecchi ambienti Python e Java.

La tabulazione ha un argomento suo che non è di gusto: chi legge con un lettore di schermo o con una larghezza personalizzata decide da sé quanto vale. Se il file finisce in un repository, l’unica regola che conta è quella già in uso lì — un file riformattato con un rientro diverso produce un diff che tocca ogni riga e nasconde la modifica vera.

Le chiavi di un oggetto JSON non hanno un ordine significativo: la specifica dice che è un insieme non ordinato di coppie, quindi riordinarle non cambia il documento. Ordinarle serve a una cosa precisa, confrontare due risposte che contengono gli stessi dati scritti in ordine diverso.

Gli array invece non vengono toccati mai, e non è una scelta prudenziale: un array è una sequenza, e il suo ordine è dato. Riordinarlo cambierebbe il significato del documento — un elenco di passaggi, una cronologia, una classifica diventerebbero un altro contenuto pur restando validi.

JSON non distingue interi e decimali: ha un unico tipo numerico, e in JavaScript diventa un numero in virgola mobile a doppia precisione. Gli interi restano esatti fino a 9.007.199.254.740.991; oltre quella soglia due valori diversi possono finire sullo stesso numero.

In pratica capita con gli identificatori: un ID Twitter, uno Snowflake, una chiave primaria a 64 bit. Il documento resta valido, il valore cambia, e nessuno se ne accorge finché una ricerca non trova più niente. Chi progetta l’API lo evita in un modo solo, mandando quegli identificatori come stringhe. Se qui compare l’avviso sulla precisione, il documento contiene un numero in quella zona.

Non ci sono commenti, non è ammessa una virgola dopo l’ultimo elemento, le chiavi vanno fra virgolette doppie e le stringhe pure — l’apostrofo non delimita niente. Non esistono `NaN`, `Infinity` né un tipo data: una data in JSON è una stringa, quasi sempre in formato ISO 8601, e il significato glielo dà chi legge.

Le eccezioni che si incontrano sono formati diversi con lo stesso nome. JSON5 e JSONC ammettono commenti e virgole finali, e li usano `tsconfig.json` e le impostazioni di parecchi editor; NDJSON è un documento per riga e non un documento solo. Nessuno dei tre passa da un parser JSON, qui come altrove.

Il JSON è UTF-8 e i caratteri accentati non richiedono nessun trattamento: `città` resta `città`, senza diventare `citt\u00e0`. Le sequenze di escape con `\u` sono ammesse e vengono lette, ma non vengono prodotte, perché renderebbero illeggibile un documento che si sta formattando proprio per leggerlo.

Dentro una stringa restano intatti anche gli spazi, gli a capo e le virgolette protette. È la conseguenza diretta del fatto che il documento venga analizzato: la formattazione tocca lo spazio fra i valori, mai quello dentro. Un cerca-e-sostituisci sul testo grezzo, invece, taglia gli spazi anche là dentro e cambia i dati.

Serve a leggere: una risposta di API arrivata su una riga sola, un campo di log che contiene un documento intero, una configurazione ereditata da qualcun altro. Il rientro rende visibile la struttura, e la struttura è la cosa che si sta cercando in tutti e tre i casi.

Non serve a verificare che il documento sia quello giusto. La formattazione non controlla nessuno schema, non sa quali campi siano obbligatori e non ha opinioni sui tipi. Per la domanda «perché la mia API lo rifiuta» la pagina utile è quella di validazione, che dice riga e colonna del punto in cui il parser si ferma.

La regola pratica è semplice: quello che leggono le persone va formattato, quello che attraversa la rete va ridotto. Un file di configurazione versionato formattato produce diff piccoli e comprensibili; lo stesso file su una riga sola produce un diff che dice «riga 1 modificata» a ogni cambiamento.

Per una risposta di API vale l’opposto, ma con meno enfasi di quanta se ne senta: se la compressione è attiva, il guadagno del rientro tolto è molto minore di quanto suggerisca la differenza in byte, perché gli spazi ripetuti sono esattamente ciò che un compressore elimina meglio. Resta un guadagno; non è quello che salva un’applicazione lenta.

Il JSON che si incolla in un formattatore è, molto spesso, la risposta di un’API con dentro nomi, email e indirizzi. Su un servizio remoto quello sarebbe un trasferimento di dati personali a un terzo, con tutto ciò che ne consegue in termini di base giuridica e di accordo; qui non avviene, perché il documento non lascia il dispositivo.

È anche la ragione per cui questa pagina non ha una funzione di condivisione né una cronologia dei documenti recenti. Sarebbero comode e vorrebbero dire conservare da qualche parte quello che hai incollato, il che riporterebbe esattamente il problema che il calcolo locale toglie di mezzo.