Migliori pratiche di formattazione JSON — indentazione, leggibilità e i dibattiti che non muoiono

La grammatica di JSON è minima. Sei tipi di valori, nessun commento, nessuna virgola finale, nessuna flessibilità in come le stringhe vengono citate. Quella rigidità è la sua forza per le macchine e la sua debolezza per gli umani. Quando un umano deve leggere o scrivere JSON — in un file di configurazione, una risposta API, un diff — la formattazione conta.

Questo post copre ogni decisione di formattazione che affronterai, cosa ha deciso l’ecosistema e dove i dibattiti infuriano ancora.

Indentazione: 2 spazi vince

La guerra Tab vs Spazi ha un vincitore nel mondo JSON: 2 spazi. Quasi ogni guida di stile, linter e formatter usa l’indentazione di 2 spazi per impostazione predefinita:

• Guida di stile JSON di Google — 2 spazi
• Prettier — 2 spazi (predefinito)
• ESLint — 2 spazi (la maggior parte delle configurazioni)
• AWS CloudFormation — 2 spazi
• Manifesti Kubernetes — 2 spazi

Il motivo è pratico: JSON è già verboso con le sue virgolette e parentesi graffe. L’indentazione di 4 spazi spinge gli oggetti annidati oltre il bordo destro della maggior parte degli editor. 2 spazi mantiene le cose leggibili senza sprecare spazio orizzontale.

Usa 4 spazi se il tuo team lo preferisce e sei coerente. Usa tab se devi, ma sappi che la maggior parte degli strumenti JSON assume spazi, e l’indentazione mista in un file JSON è un errore di parsing in attesa di accadere.

Virgole finali: ancora no

JSON non permette virgole finali. Questo è l’errore di sintassi più comune nei file JSON modificati a mano. Scrivi:

{
  "name": "Alice",
  "items": ["a", "b",],
}

E un parser rigoroso lo rifiuta. La virgola finale dopo "b" e la virgola finale dopo la graffa chiusa } sono entrambe illegali.

YAML permette virgole finali (e la maggior parte dei linguaggi lo fa). JSON no. Se i tuoi strumenti supportano JSONC (JSON con Commenti, usato in tsconfig.json e settings.json di VS Code), le virgole finali sono permesse. Ma JSON puro — il tipo che viaggia via API — non le tollera.

La migliore difesa: usa un formatter che rilevi automaticamente questo. Incolla il tuo JSON in un validatore prima del commit.

Carino vs compatto

JSON carino ha nuove righe e indentazione. È leggibile, ha diff ed è debuggabile:

{
  "status": "ok",
  "count": 42
}

JSON compatto non ha spazi bianchi tra i token. È più piccolo sulla rete:

{"status":"ok","count":42}

La regola empirica:

• Rivolto agli umani (file di configurazione, log, risposte API durante il debug) → carino.
• Rivolto alle macchine (payload API in produzione, code di messaggi, stream di eventi) → compatto.
• Archiviazione (database, cache) → compatto, a meno che tu debba leggerlo manualmente durante il debug.

Il JSON compatto risparmia circa il 20-30% di dimensione rispetto al JSON carino a 2 spazi. Per un payload da 10KB, sono 2-3KB. Su milioni di richieste, si accumula. Per un file di configurazione che modifichi a mano, la leggibilità del JSON carino vale i byte extra.

Chiavi ordinate

Le chiavi degli oggetti dovrebbero essere ordinate alfabeticamente?

A favore: i diff sono deterministici. Se aggiungi una chiave, solo quella riga appare in un diff git. Senza chiavi ordinate, inserire una chiave nel mezzo può spostare ogni chiave successiva, creando un rumoroso diff.

Contro: il raggruppamento logico è più leggibile. Mettere "name" prima e "id" secondo è intuitivo. L’ordinamento alfabetico mette "address" prima di "name" senza motivo semantico.

La risposta pragmatica: ordina le chiavi nel JSON generato dalla macchina (API, config, diff). Mantieni l’ordine logico nel JSON scritto a mano. La maggior parte dei formatter (Prettier, jq, python -m json.tool) ha un flag --sort-keys che puoi abilitare nel CI.

Convenzioni di denominazione delle chiavi

Le chiavi di JSON sono stringhe, e l’ecosistema si è stabilizzato su due convenzioni:

• camelCase — il predefinito JavaScript/Node.js. firstName, lastName, createdAt.
• snake_case — il predefinito Python/Ruby/Rust. first_name, last_name, created_at.
• kebab-case — raro in JSON, più comune in URL e CSS. Da evitare per le chiavi API.

Scegline una e attieniti ad essa. La maggior parte delle API usa camelCase. Se stai costruendo un’API REST per consumatori JavaScript, camelCase è la via di minor resistenza. Se stai interfacciando con servizi Python, snake_case riduce l’attrito.

La peggior cosa che puoi fare è mescolare: firstName in un endpoint, last_name in un altro. Scegli una convenzione, imponila con un linter e vai avanti.

Formattazione dei numeri

JSON non distingue interi da float. 42 e 42.0 sono entrambi validi, e la maggior parte dei parser li tratta identicamente. Ma la formattazione conta per la leggibilità:

• Interi: nessun punto decimale. 42, non 42.0.
• Float: usa quante cifre servono. 3.14159, non 3.14159000000000.
• Numeri grandi: usa la notazione scientifica se il numero è enorme. 1e10 è più chiaro di 10000000000.

JSON non supporta Infinity, -Infinity o NaN. Se il tuo linguaggio serializza questi, l’output non è JSON valido e i parser lo rifiuteranno.

Stringhe: virgolette singole vs doppie

JSON richiede virgolette doppie per le stringhe. Questo non è negoziabile. 'hello' non è JSON valido. "hello" lo è.

Se il tuo linter o editor permette virgolette singole nei file JSON, sta parsando JSONC o un superinsieme, non JSON standard. Le API e i parser che si aspettano JSON rigoroso rifiuteranno stringhe con virgolette singole.

Commenti: ancora non permessi

JSON non ha sintassi per i commenti. Questo è per design (la specifica dice che JSON è “un formato di scambio dati”, non un linguaggio di configurazione), ma è il lamento più comune degli sviluppatori che usano YAML.

Soluzioni:

• Usa una chiave "comment" o "_comment". È brutto ma valido.
• Usa JSONC (il formato di VS Code) se i tuoi strumenti lo supportano.
• Passa a YAML o TOML per i file di configurazione dove i commenti contano.

Il workflow del formatter

Il miglior workflow per la formattazione JSON:

1. Scrivi JSON come vuoi. Non perdere tempo a indentare a mano.
2. Esegui un formatter al salvataggio. Prettier, jq o il formatter integrato del tuo editor.
3. Commita l’output formattato. Diff coerenti, nessun dibattito sullo stile.
4. Valida nel CI. Un passo di lint JSON cattura virgole finali ed errori di sintassi prima che arrivino in produzione.

Questo elimina ogni dibattito di formattazione. Il formatter decide, tutti gli altri scrivono codice.

Errori comuni

• Virgole finali — l’errore di parsing più frequente nei JSON modificati a mano.
• Virgolette singole — valide nei letterali oggetto JavaScript, invalide in JSON.
• Chiavi senza virgolette — { name: "Alice" } è JavaScript, non JSON.
• Commenti — // questo non è JSON o /* neanche questo */.
• Indentazione mista — mescolare tab e spazi nello stesso file.

Incolla il tuo JSON in un validatore prima del deploy. Ci vuole un secondo e risparmia trenta minuti di debug di un misterioso errore 400.