Formattatore JSON

Cosa fa questo formattatore JSON

JSON (JavaScript Object Notation) è il formato più comune per spostare dati strutturati tra programmi: risposte API, file di configurazione, righe di log e altro. È progettato per essere compatto, il che lo rende anche difficile da leggere quando gli oggetti si annidano su qualche livello o arrivano su una sola riga. Questo strumento prende qualsiasi JSON che incolli e lo riscrive in due modi: abbellito, con un’indentazione coerente perché la struttura sia evidente a colpo d’occhio, o minimizzato, privo di ogni spazio facoltativo per essere il più piccolo possibile all’invio.

Convalida anche mentre formatta. Poiché analizza il testo prima di riserializzarlo, un JSON non valido non produce mai un output fuorviante: ottieni invece la riga e la colonna in cui l’analisi è fallita, ogni volta che riesce a ricavarle, per andare subito al problema.

Abbellire vs. minimizzare: quando usare ciascuno

I due modi hanno obiettivi opposti, e la maggior parte dei flussi di lavoro li usa entrambi in fasi diverse:

• Abbellisci quando leggi o esegui il debug: ispezionare una risposta API, confrontare due payload o rivedere un file di configurazione in una pull request. L’indentazione trasforma un muro di testo in un albero navigabile.
• Minimizza quando spedisci: incorporare JSON nell’HTML, salvarlo in un cookie o in una cache, o inviarlo nel corpo di una richiesta dove ogni byte conta. Il JSON minimizzato è esattamente lo stesso dato, solo senza gli spazi.

Il selettore di indentazione (2 spazi, 4 spazi o tabulazione) influisce solo sull’output abbellito. Due spazi è la convenzione più diffusa in JavaScript e negli strumenti web; quattro spazi o tabulazioni vanno bene per i team che le preferiscono. Qualunque cosa scegli, il risultato resta JSON valido: l’indentazione è puramente estetica.

Leggere gli errori di convalida

Quando il JSON non è valido, lo strumento riporta la riga e la colonna del primo problema invece di un semplice "non valido", tranne nell’unico caso descritto dalla sezione su dove puntano la riga e la colonna. I messaggi di errore dei motori differiscono tra i browser e spesso omettono una posizione, quindi il luogo è calcolato in modo indipendente e indica un punto ragionevole da cui iniziare. Correggi il primo errore e ricontrolla: un singolo carattere fuori posto si trasforma spesso in diversi problemi apparenti.

Errori JSON comuni

JSON è più severo degli oggetti letterali di JavaScript a cui somiglia. Questi sono gli errori che traggono più spesso in inganno:

• Virgole finali: una virgola dopo l’ultimo elemento di un oggetto o array è valida in JavaScript ma non in JSON.
• Apici singoli: le stringhe e le chiavi JSON devono usare le virgolette doppie. 'valore' non è valido; "valore" è corretto.
• Chiavi senza virgolette: ogni chiave di oggetto deve essere una stringa tra virgolette, quindi { name: "x" } deve diventare { "name": "x" }.
• Commenti: JSON non ha una sintassi per i commenti. // e /* */ causeranno un errore di analisi.
• Numeri speciali: NaN, Infinity e -Infinity non sono numeri JSON validi.
• Virgolette sbagliate: le "virgolette tipografiche" incollate da un elaboratore di testi sembrano virgolette ma sono caratteri diversi e non verranno analizzate.

Dove puntano la riga e la colonna segnalate

La posizione non è dove hai omesso qualcosa: è dove l’analizzatore ha incontrato per la prima volta qualcosa che non può legittimamente stare lì, e di solito sono due punti diversi. Nell’oggetto qui sotto alla riga 3 manca la virgola che dovrebbe chiuderla, e lo strumento segnala la riga 4, colonna 3: le virgolette di apertura della chiave successiva. Nulla era sbagliato fino all’arrivo di quelle virgolette, perché il documento avrebbe potuto legittimamente finire dopo la riga 3; l’analizzatore viene quindi a sapere dell’omissione solo quando incontra qualcosa che non è né una virgola né una parentesi graffa di chiusura.

{
  "id": 42,
  "name": "widget"
  "price": 9.99
}

• Una virgola mancante è segnalata al primo carattere di ciò che viene dopo, che in JSON indentato come quello sopra è la riga successiva: leggi la riga indicata insieme a quella sopra.
• Una virgola in eccesso è segnalata alla parentesi di chiusura: riga 3, colonna 1 per un oggetto la cui ultima coppia sta alla riga 2. La virgola promette un’altra coppia e la parentesi è ciò che rompe la promessa.
• Una stringa non chiusa è di solito segnalata alla fine della riga in cui si è aperta anziché alle virgolette di apertura, perché le virgolette successive su una riga più avanti possono chiuderla altrove. Un ritorno a capo non può comparire dentro una stringa JSON, quindi il ritorno a capo è il primo carattere che non può stare lì.
• Riga 1, colonna 1 su un documento che sembra perfetto significa quasi sempre un contrassegno di ordine dei byte. Alcuni editor ne scrivono uno salvando in UTF-8; è invisibile, sta prima della parentesi di apertura, e JSON non ha posto per esso.

E dove lo strumento non riesce a ricavare alcuna posizione, segnala il fallimento senza di essa invece di indicare una coordinata indovinata. Una riga e una colonna date con sicurezza ma che puntano a una sintassi perfettamente corretta ti farebbero cercare nel posto sbagliato, e questo è peggio che sapere soltanto che il documento non si analizza.

Cosa cambia la formattazione e cosa conserva

Per quasi ogni documento la risposta è lo spazio bianco e nient’altro. Ma lo strumento non modifica il tuo testo: lo analizza trasformandolo in valori veri e riscrive quei valori, e cinque cose non sopravvivono a quel viaggio di andata e ritorno. Nessuna è un difetto dello strumento — ciascuna è ciò che la specifica JSON dice che siano un numero o un oggetto — e ciascuna vale la pena di essere conosciuta prima di incollare l’output sopra il tuo originale.

• La stessa chiave scritta due volte: sopravvive solo l’ultima delle due, perché un oggetto non può portare una chiave due volte. La RFC 8259 dice che un programma che riceve un oggetto con nomi duplicati si comporta in modo imprevedibile, e un altro analizzatore può tenere il primo, quindi nemmeno quale delle due ti resta è una cosa su cui contare.
• Un intero di più di quindici cifre: i numeri JSON sono letti come virgola mobile a doppia precisione, che contiene esattamente ogni numero intero fino a due alla cinquantatreesima — una cifra di sedici caratteri — quindi un intero di quindici cifre sopravvive sempre e uno più lungo può non farlo. Incolla 12345678901234567890 ed esce 12345678901234567000. I lunghi identificatori di database sono la vittima abituale: tienili come stringhe se puoi.
• Le forme con esponente e con zeri finali sono normalizzate: 1e3 torna come 1000, e 1.50 come 1.5. È lo stesso numero scritto nel modo standard.
• Una grandezza fuori da ciò che quel formato può portare torna come qualcos’altro: 1e400 non ha valore in doppia precisione e torna come null, e 1e-400 torna come 0. Una lunga frazione decimale è arrotondata alla precisione che il formato ha, esattamente come un intero lungo.
• Una sequenza di escape diventa il carattere che denota: \u00e9 torna come é, e una coppia surrogata con escape come l’emoji che compone. Per qualunque analizzatore sono la stessa stringa; una delle due scritture è semplicemente più corta.

L’ordine delle chiavi è conservato come l’hai scritto, con un’eccezione che vale la pena conoscere: una chiave fatta di sole cifre, che si legge come un semplice intero non negativo sotto i quattro miliardi circa, è trattata come indice di un array e torna all’inizio del suo oggetto in ordine numerico, dovunque tu l’avessi messa. Nient’altro si muove: nessun’altra chiave viene riordinata, e nessuna viene aggiunta o rinominata. Se qualcosa di tutto questo ti importa, minimizza invece di abbellire e confronta il risultato con il tuo originale carattere per carattere. È la via più corta per vedere cosa ha fatto il viaggio di andata e ritorno.

Quando il JSON che cerchi è dentro una stringa

I registri dei webhook, le code di messaggi e le colonne di database portano molto spesso un intero documento JSON come un unico valore stringa, con ogni virgoletta interna in escape. Il documento esterno è perfettamente valido, quindi lo strumento lo abbellisce e lo segnala valido — e la parte che eri venuto a leggere resta una lunga riga di barre rovesciate. Non è andato storto nulla: sono due documenti, uno avvolto dentro una stringa dell’altro.

{
  "event": "order.created",
  "payload": "{\"id\":42,\"total\":19.99}"
}

Leggerlo richiede dunque due passaggi. Formatta qui il documento esterno, copia ciò che sta fra le virgolette della stringa che ti interessa, disfa l’escape e incolla di nuovo il risultato. Lo strumento Escape / unescape di stringhe JSON compie quel passaggio intermedio: la sua direzione di unescape riporta \" a " e la riga a un documento che questa pagina può formattare. Se controlli ciò che ha prodotto il file, la soluzione migliore sta più a monte: invia il payload come oggetto annidato invece che come stringa, e non serve alcun passaggio.

Un oggetto per riga non è un documento

I file di log, le esportazioni da API e gli endpoint in streaming contengono comunemente un oggetto JSON completo per riga; il formato si chiama JSON Lines, o NDJSON. Ogni riga è JSON valido da sola, ma il file non è un documento JSON, perché un documento JSON contiene esattamente un valore di primo livello e questo ne contiene diversi, uno dopo l’altro e senza nulla che li unisca.

{"level":"info","msg":"started"}
{"level":"warn","msg":"retrying"}
{"level":"error","msg":"gave up"}

Incolla quello qui e lo strumento segnala la riga 2, colonna 1: il primo oggetto è finito in modo pulito, e poi un secondo è cominciato dove il documento avrebbe dovuto terminare. Da lì ci sono due strade. Formatta una riga alla volta, che è ciò che vuoi quando leggi una singola voce di log. Oppure fai del file un solo documento — avvolgi le righe fra parentesi quadre e metti una virgola alla fine di ogni riga tranne l’ultima — che è ciò che vuoi quando stai per caricare il tutto in qualcosa che si aspetta un array.