Formattare JSON

Come formattare JSON in quattro passaggi

1. Incollare il proprio JSON nel riquadro JSON in ingresso.
2. Fare clic su Formatta / Abbellisci per ottenere un rientro pulito (2 spazi, 4 spazi o tabulazione), su Minifica per togliere tutti gli spazi, oppure su Valida per limitarsi a controllarlo.
3. Se il JSON non è valido, il messaggio indica la riga e la colonna esatte dell'errore.
4. Il risultato si può copiare oppure scaricare come file.

Formattare, validare, minificare: le differenze

Validare controlla soltanto se il testo è JSON ben formato. Formattare (abbellire) reindenta il JSON valido perché una persona possa leggere le strutture annidate. Minificare rimuove ogni spazio e ogni interruzione di riga superflui, in modo che i dati risultino il più compatti possibile — comodo prima di inviare il JSON in rete o di inserirlo da qualche parte. Nessuna di queste operazioni modifica i dati: chiavi, valori, tipi e ordine delle chiavi restano esattamente come sono stati scritti; cambiano solo gli spazi.

Motivi frequenti per cui il JSON non è valido

• Virgola finale — {"a":1,} non è valido; dopo l'ultimo elemento non può esserci una virgola.
• Apici singoli — stringhe e chiavi richiedono le "virgolette doppie", mai '.
• Chiavi senza virgolette — {name:"x"} deve diventare {"name":"x"}.
• Commenti — in JSON non esistono né // né /* */.
• Parole chiave scritte male — i valori booleani e null vanno in minuscolo (true, false, null); le parole chiave che appartengono solo a JavaScript non sono JSON valido.
• Parentesi non corrispondenti — ogni { e ogni [ richiede la propria parentesi di chiusura.

I dati restano privati?

Sì. Lo strumento usa JSON.parse e JSON.stringify direttamente nel browser: niente viene inviato a un server. Si possono quindi incollare senza rischi risposte di API interne, token di accesso o file di configurazione. Una volta caricata la pagina, tutto continua a funzionare anche senza connessione.

Che cos'è JSON e da dove viene?

JSON (JavaScript Object Notation) è un formato leggero, basato su testo, per lo scambio di dati strutturati. Gli ha dato il nome e lo ha reso popolare Douglas Crockford, che nel 2002 registrò il dominio json.org e vi pubblicò la grammatica. La sintassi deriva dai valori letterali di oggetto e array del linguaggio JavaScript, in particolare dallo standard ECMAScript 3 del 1999, ma JSON in sé è indipendente dal linguaggio: esistono parser e serializzatori per praticamente ogni linguaggio di programmazione. È proprio per questo che è diventato il modo abituale con cui un browser, un'app per telefono e un server dialogano fra loro, anche quando sono scritti in tre linguaggi diversi.

JSON è stato messo per iscritto per la prima volta come specifica IETF con la RFC 4627 (2006). Nell'ottobre 2013 ha ricevuto una grammatica formale da un ente di normazione con ECMA-404, e la specifica autorevole di oggi è la RFC 8259 (2017), pubblicata anche come standard di Internet STD 90. La RFC 8259 ha chiarito una regola che i documenti precedenti lasciavano vaga: il testo JSON scambiato fra sistemi deve essere codificato in UTF-8. Le due specifiche vive, ECMA-404 e RFC 8259, sono tenute volutamente identiche, e i rispettivi curatori si sono impegnati ad aggiornarle sempre insieme.

I sei tipi di dato di JSON

Ogni valore di un documento JSON appartiene a uno solo di sei tipi — non c'è altro:

• Object — un insieme non ordinato di coppie "key": value racchiuse fra parentesi graffe. Le chiavi devono essere stringhe fra virgolette doppie.
• Array — un elenco ordinato di valori racchiuso fra parentesi quadre. I valori possono essere di tipi diversi.
• String — testo fra virgolette doppie, con sequenze di escape come \n, \t, \" e \uXXXX.
• Number — un numero decimale come 42, -3.14 o 6.022e23. Non esiste un tipo intero separato e non sono ammessi NaN, Infinity né gli zeri iniziali.
• Boolean — i valori in minuscolo true oppure false.
• Null — il valore in minuscolo null, cioè «nessun valore».

Un documento JSON è semplicemente un valore di uno di questi tipi — quasi sempre un oggetto o un array al livello più esterno, anche se la RFC 8259 ammette come testo JSON completo qualunque valore, perfino un singolo true o un solo numero.

Perché JSON deve essere così rigido

JSON è volutamente un sottoinsieme rigoroso della sintassi di JavaScript, più rigoroso persino degli oggetti che si scrivono nel codice. Questa rigidità è un pregio: una grammatica inflessibile fa sì che ogni parser conforme legga un documento allo stesso modo, senza margini di interpretazione. Le regole su cui più spesso ci si inciampa discendono direttamente da questa scelta. Non esistono commenti: Crockford li eliminò di proposito, perché nessuno potesse nascondere istruzioni per il parser dentro un file di dati. Non è ammessa la virgola dopo l'ultimo elemento, perché la virgola è un separatore e non può comparire alla fine. Per le chiavi e per le stringhe sono ammesse solo le virgolette doppie: gli apici singoli e le chiavi senza virgolette che JavaScript consente non sono JSON valido. E le parole chiave true, false e null distinguono maiuscole e minuscole, quindi True o NULL danno errore.

La trappola dei numeri grandi

JSON non pone alcun limite alla dimensione o alla precisione di un numero, ma quasi tutti i parser — compreso il JSON.parse del browser — leggono i numeri come valori in virgola mobile a 64 bit secondo lo standard IEEE 754. In questo modo gli interi sono rappresentati in modo sicuro solo fino a 2⁵³ − 1 (9007199254740991, disponibile in JavaScript come Number.MAX_SAFE_INTEGER). Un ID di database a 64 bit più grande di così, o un token numerico molto lungo, viene arrotondato in silenzio durante la lettura. La soluzione consueta è trasmettere quei valori come stringhe e convertirli soltanto dove è disponibile un tipo per interi grandi. È un errore sottile di cui nessun formattatore può avvisare, perché l'arrotondamento avviene dentro il parser, prima che il valore arrivi alla pagina.

JSON, XML e YAML a confronto

Prima di JSON il formato di scambio dominante era XML. XML è potente — supporta attributi, spazi dei nomi, schemi (XSD) e validazione — ma è prolisso: ogni elemento richiede un tag di apertura e uno di chiusura, il che aumenta la mole dei dati e il costo della lettura. JSON esprime gli stessi dati con molto meno testo e corrisponde direttamente alle strutture native della maggior parte dei linguaggi (oggetti, array, mappe, liste): è per questo che le API REST vi sono passate quasi per intero.

YAML è quasi un soprainsieme di JSON e vi aggiunge commenti, àncore e un impaginato basato sui rientri, il che lo rende diffuso per le configurazioni curate a mano, come le pipeline di CI e i manifest di Kubernetes. Il prezzo da pagare è che la sensibilità di YAML ai rientri lo rende facile da rompere durante la modifica, mentre le parentesi esplicite di JSON non lasciano dubbi. Una regola pratica utile: JSON per le macchine, YAML per le persone, XML per i documenti con marcatura ricca e contenuti misti.

I parenti più permissivi: JSON5, JSONC e NDJSON

Diverse estensioni allentano le regole di JSON per scopi specifici. JSONC («JSON with Comments») si limita ad ammettere i commenti // e /* */ ed è ciò che Visual Studio Code usa per i file delle impostazioni. JSON5 va oltre e consente apici singoli, chiavi senza virgolette, la virgola dopo l'ultimo elemento e i numeri esadecimali, così che i file curati a mano risultino più tolleranti. NDJSON (detto anche JSON Lines) memorizza un oggetto JSON indipendente per ogni riga: è la scelta ideale per i registri in tempo reale e per i grandi insiemi di dati, perché un programma può elaborare un record alla volta senza caricare l'intero file. Nessuna di queste varianti è intercambiabile con il JSON rigoroso: se un server si aspetta JSON conforme alla RFC 8259, i commenti e la virgola finale vengono rifiutati. È di gran lunga il motivo più comune per cui dati che «sembrano giusti» non si lasciano leggere.

Dove si incontra JSON

Una volta che ci si fa caso, JSON è ovunque. È il formato del corpo della stragrande maggioranza delle API REST e GraphQL; il linguaggio di configurazione di innumerevoli strumenti (package.json, tsconfig.json, composer.json); il formato nativo dei documenti dei database NoSQL come MongoDB; e il contenuto di ogni JSON Web Token. Alcuni dialetti specializzati lo estendono ad altri campi: GeoJSON descrive mappe e forme geografiche, JSON-LD alimenta i dati strutturati che i motori di ricerca leggono e JSON Schema descrive e valida la forma di altri documenti JSON. Conoscere bene JSON è una delle competenze che rendono di più nello sviluppo software, perché lo stesso formato ricompare in moltissimi posti.

Abbellire o minificare? Dipende da chi legge

Il JSON abbellito, con rientri e interruzioni di riga, è pensato per un lettore: la persona. Il JSON minificato, privato di ogni spazio superfluo, è pensato per un altro: la rete. I dati che stanno per essere spediti sul filo conviene minificarli — tenendo però presente che le risposte HTTP sono quasi sempre compresse con gzip o Brotli e che la compressione riduce già in modo molto efficace gli spazi ripetuti, per cui a compressione avvenuta la differenza di dimensione è di solito modesta. Il vantaggio vero della minificazione sono semplicemente meno byte da leggere. Tutto ciò che invece si legge, si analizza in cerca di errori, si registra nel controllo di versione o si incolla in una segnalazione conviene abbellirlo prima: una struttura pulita e rientrata rende evidente a colpo d'occhio una parentesi mancante o un valore fuori posto.

Una nota su JSON e sicurezza

Leggere JSON è sicuro; eseguirlo no. Agli inizi qualche sviluppatore elaborava il JSON passandolo a eval() di JavaScript: così veniva eseguito qualunque codice nascosto nel testo, una vulnerabilità grave. Conviene usare sempre un vero parser come JSON.parse, che è quello impiegato da questo strumento, e mai eval. Una finezza da conoscere: una chiave di nome __proto__ presente in JSON di provenienza non fidata è stata sfruttata, in alcune librerie, per attacchi di «prototype pollution». I parser ben mantenuti oggi se ne difendono, ma resta un buon motivo per non passare mai JSON non fidato direttamente a codice che unisce oggetti.

JSON non ha un tipo per le date

Sorprende spesso scoprire che JSON non ha alcuna rappresentazione propria per date, orari o dati binari: esistono solo i sei tipi visti sopra. Per una convenzione ormai universale le date viaggiano come stringhe ISO 8601, per esempio "2026-06-30T14:00:00Z", e i dati binari come stringhe codificate in Base64. Serializzando un Date di JavaScript con JSON.stringify si ottiene automaticamente una stringa ISO 8601, ma rileggendola si riceve una stringa e non un Date: la conversione va fatta a mano. Considerare ogni marca temporale come UTC — la si riconosce dalla Z finale — e convertirla in ora locale solo per la visualizzazione è il modo più affidabile per evitare errori di fuso orario.

Chiavi duplicate e ordine delle chiavi

Altri due dettagli traggono spesso in inganno. Primo: la RFC 8259 dice che i nomi all'interno di un oggetto dovrebbero essere unici, ma non vieta i duplicati e lascia indefinito il comportamento di un parser che incontra due volte la stessa chiave. Nella pratica quasi tutti i parser, compreso quello del browser, conservano l'ultima occorrenza: non conviene però farvi affidamento, perché le chiavi duplicate sono una classica fonte di errori fra sistemi diversi. Secondo: sebbene un oggetto JSON sia formalmente una raccolta non ordinata, ogni parser diffuso conserva l'ordine in cui le chiavi sono state inserite, e anche questo formattatore lascia le chiavi esattamente nell'ordine in cui sono state scritte, sia abbellendo sia minificando. Se un'applicazione dipende davvero da un ordine preciso, conviene codificarlo in modo esplicito — per esempio come array di coppie — invece di affidarsi all'ordine delle chiavi dell'oggetto.

Muoversi dentro JSON: JSONPath e JSON Pointer

Man mano che i documenti crescono serve un modo per indicare un valore in profondità. A questo servono due piccoli standard. JSON Pointer (RFC 6901) usa un percorso separato da barre come /users/0/email e punta a un'unica posizione precisa: è così che JSON Patch e JSON Schema fanno riferimento internamente a un nodo. JSONPath è una notazione più espressiva, simile a un'interrogazione (ispirata a XPath per XML), capace di selezionare più nodi in una volta, filtrare per condizione e usare caratteri jolly — per esempio $.users[*].email per estrarre l'indirizzo di posta di tutti gli utenti. Il Pointer risponde «questo punto preciso», JSONPath «tutto ciò che corrisponde». Sapere che esistono risparmia molte ricerche a mano dentro un documento grande e abbellito.

Consigli per i file JSON di grandi dimensioni

Gli strumenti che lavorano nel browser, compreso questo, gestiscono senza fatica file di diversi megabyte, perché l'elaborazione avviene in locale sul computer. Quando i documenti diventano davvero grandi, qualche abitudine aiuta. Abbellire prima di leggere, così la struttura si vede, conservando una copia minificata per il trasporto. Per i file che non entrano più per intero in memoria conviene NDJSON (un oggetto per riga), da elaborare riga per riga, oppure un parser a flusso che restituisce i valori man mano che legge, invece di costruire prima l'intero albero. E quando un'API restituisce una raccolta ampia, meglio cercare la paginazione — un cursore next o un parametro di pagina — invece di chiedere tutto insieme: le API progettate bene non si aspettano mai il download di un milione di record in una sola risposta.

Domande frequenti

Il mio JSON viene caricato su un server?

No. La formattazione, la validazione e la minificazione avvengono interamente nel browser con JavaScript. I dati non lasciano mai il dispositivo: per questo lo strumento è veloce e si possono incollare senza timore anche contenuti riservati, come risposte di API interne o file di configurazione.

Perché il mio JSON non è valido?

Le cause più comuni sono una virgola dopo l'ultimo elemento, apici singoli al posto delle virgolette doppie, chiavi senza virgolette, commenti (in JSON non esistono) oppure una parentesi mancante. Questo strumento indica esattamente la riga e la colonna in cui la lettura è fallita.

Che differenza c'è fra formattare, validare e minificare?

Validare verifica soltanto se il testo è JSON ben formato. Formattare (abbellire) reindenta il JSON valido perché sia leggibile. Minificare elimina tutti gli spazi e le interruzioni di riga, così i dati risultano il più compatti possibile per il trasporto. Questo strumento esegue tutte e tre le operazioni da un unico riquadro.

La formattazione modifica i miei dati?

No. Abbellire e minificare cambiano soltanto gli spazi: chiavi, valori, tipi e struttura restano identici, e l'ordine delle chiavi rimane esattamente quello in cui sono state scritte.

Quanto può essere grande il file?

Poiché tutto avviene nel browser, lo strumento gestisce senza difficoltà le normali risposte di API e i file di configurazione di diversi megabyte. Per i file molto grandi il limite è soltanto la memoria del dispositivo, non un limite di caricamento.

Strumenti per sviluppatori correlati

• Da JSON a CSV
• Da JSON a XML
• Da JSON a tabella HTML
• Da CSV a JSON
• Codificatore / decodificatore Base64

Vedere tutte le conversioni per sviluppatori e dati →