Formattatore JSON

Formattare il JSON significa aggiungere lo spazio bianco che serve a una persona e non serve a una macchina: un membro per riga, indentazione coerente, uno spazio dopo ogni due punti. I dati non cambiano. Cambia solo la loro presentazione.

La parte facile da sbagliare è proprio quest’ultima frase. Un formattatore che analizza il documento trasformandolo in valori JavaScript e poi li riserializza ha già riscritto i tuoi numeri prima di stampare qualsiasi cosa, e la maggior parte fa esattamente questo.

Che cosa la formattazione non cambia

Questo formattatore riemette i token che ha letto invece di riserializzare valori analizzati. Il testo di ogni numero, stringa e literal torna quindi byte per byte, e viene riscritto solo lo spazio bianco che li separa.

Conta più di quanto sembri. Fai passare un documento con un ID di 19 cifre attraverso un formattatore costruito su JSON.parse e JSON.stringify e l’ID torna diverso, in silenzio, senza alcun avviso nell’interfaccia.

I numeri mantengono il testo esatto

1.50 resta 1.50, 1e3 resta 1e3, -0 resta -0, e 12345678901234567890 resta se stesso invece di diventare 12345678901234567000.

Le stringhe vengono copiate alla lettera

Un \u00e9 con escape resta con escape e una é letterale resta letterale. La formattazione non è il momento di decidere come codificare una stringa, quindi non lo decide.

L’ordine delle chiavi viene preservato

A meno che tu non attivi esplicitamente l’ordinamento. Gli oggetti JSON non sono ordinati secondo la specifica, ma in pratica ogni parser conserva l’ordine di inserimento e i diff ci contano.

Le chiavi duplicate vengono mantenute e segnalate

Rimuoverne una cambierebbe ciò che vede chi consuma il documento. Ricevi invece un avviso che indica entrambe le posizioni.

Quale indentazione scegliere

Due spazi è il valore predefinito qui perché è ciò che emettono npm, Prettier e quasi tutto il tooling JavaScript, e perché in JSON l’annidamento diventa profondo in fretta. Quattro spazi si leggono meglio su file di configurazione poco annidati. Le tabulazioni lasciano a ogni lettore la scelta della larghezza, che è l’argomento di accessibilità a loro favore, e si comprimono leggermente meglio.

Per tutto ciò che viene trasmesso invece che letto, conviene minificare. Lo spazio bianco in una risposta JSON è puro sovraccarico, e su un payload di API tipico vale tra il 10 e il 20 per cento dei byte.

Fine riga e ritorno a capo finale

L’output usa LF per impostazione predefinita. Esiste un’opzione CRLF perché il tooling Windows e alcuni sistemi di CI ci tengono, e perché un file che mescola i due produce un diff in cui ogni riga sembra modificata.

Lo spazio bianco fuori dalle stringhe non significa nulla per un parser, quindi niente di tutto questo tocca la validità. Tocca i tuoi diff, che in pratica è ciò che noti.

How to do this in code

La stessa operazione nel codice. Tutte queste varianti producono un’indentazione di due spazi; tutte riscriveranno anche i tuoi numeri, che è il compromesso che accetti quando il payload non contiene interi grandi.

const pretty = JSON.stringify(JSON.parse(text), null, 2);

// Tabs
const tabbed = JSON.stringify(JSON.parse(text), null, '\t');

import json

pretty = json.dumps(json.loads(text), indent=2)

# Keep non-ASCII readable rather than escaping it
pretty = json.dumps(json.loads(text), indent=2, ensure_ascii=False)

# From the command line
# python -m json.tool --indent 2 input.json

jq . input.json              # 2 spaces, the default
jq --indent 4 . input.json
jq --tab . input.json
jq -c . input.json           # compact

var buf bytes.Buffer
if err := json.Indent(&buf, data, "", "  "); err != nil {
    return err
}

// json.Indent works on raw bytes, so unlike Unmarshal it does
// not touch your numbers at all.

require 'json'

pretty = JSON.pretty_generate(JSON.parse(text))

$pretty = json_encode(
    json_decode($text),
    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
);

Domande frequenti

C’è un limite di dimensione?

Questa pagina non ne impone nessuno. Il tetto reale è il tuo browser: un motore JavaScript limita una singola stringa a circa 512 MB, quindi niente di più grande può essere tenuto in memoria. Formattare un documento da 10 MB richiede qui circa 780 millisecondi di lavoro, eseguiti in un worker in background così la pagina resta reattiva.

La formattazione modifica i miei dati?

No. Lo spazio bianco fuori dalle stringhe non ha significato in JSON, e questo formattatore riemette ogni valore esattamente come lo hai scritto invece di analizzarlo e riserializzarlo. Attivare l’ordinamento delle chiavi modifica invece il documento, ed è per questo che è disattivato di default.

Perché il mio file formattato è diverso da quello che produce il mio editor?

Con ogni probabilità si tratta del ritorno a capo finale o dello stile degli array di oggetti. Alcuni formattatori tengono gli array brevi su una sola riga; questo è coerente, il che produce più righe ma diff molto più leggibili.