JSON vs YAML: differenze e quando usare ciascuno

JSON e YAML risolvono lo stesso problema —— rappresentare dati strutturati come testo —— ma fanno trade-off opposti. JSON è ottimizzato per il parsing macchina senza ambiguità; YAML è ottimizzato per la scrittura umana. Da YAML 1.2, ogni documento JSON valido è anche YAML valido. Questa guida confronta la loro sintassi, i tipi e le funzionalità, e spiega quando usare l'uno o l'altro.

La risposta breve

Usa JSON per dati scambiati tra programmi —— risposte API, payload di messaggi, qualsiasi cosa generata dalla macchina. Usa YAML per file che gli umani scrivono e modificano a mano —— pipeline CI, manifest Kubernetes, configurazione di app —— dove commenti e leggibilità contano.

Sintassi a confronto

Gli stessi dati in entrambi i formati:

# YAML
service: api
replicas: 3
ports:
  - 8080
  - 8443
env:
  LOG_LEVEL: info
  DEBUG: false

// JSON
{
  "service": "api",
  "replicas": 3,
  "ports": [8080, 8443],
  "env": {
    "LOG_LEVEL": "info",
    "DEBUG": false
  }
}

YAML usa l'indentazione al posto di parentesi graffe e quadre, elimina la maggior parte delle virgolette e permette i commenti. JSON è più verboso ma non ha whitespace significativo, il che lo rende molto più semplice da parsare e generare in modo affidabile.

YAML è un superset di JSON

Da YAML 1.2 (2009), YAML è un superset stretto di JSON —— qualsiasi documento JSON valido è YAML valido, perché YAML ha adottato direttamente la sintassi «flow» di JSON. È per questo che puoi incollare del JSON in un file YAML e funziona così com'è. Per la storia dietro tutto questo, vedi YAML 1.2 e compatibilità JSON.

# Questo è YAML valido —— ed è anche JSON valido
{"service": "api", "replicas": 3}

Confronto delle funzionalità

Gestione dei tipi: i bordi taglienti di YAML

La fretta di YAML di inferire i tipi causa sorprese che le virgolette esplicite di JSON evitano:

# Il «Norway problem» —— questi diventano booleani nei parser YAML 1.1
countries:
  - NO   # → false (!)
  - SE
  - true # → booleano, non la stringa "true"

version: 1.20   # → il numero 1.2, lo zero finale viene perso
zip: 01234      # → 668 (parsato come ottale) in alcuni parser

JSON non ha nessuna di queste ambiguità: "NO" è sempre la stringa NO, e "01234" è sempre quella stringa. Quando un valore YAML deve essere una stringa, mettilo tra virgolette esplicite.

Dove si inseriscono TOML e JSON5

Altri due formati di config «human-friendly» che spuntano nella stessa conversazione:

• TOML —— stile section/key, progettato per la configurazione di app modificata a mano (Cargo, Poetry, Hugo). Più rigido di YAML, niente indentazione significativa, valori tipati nativi (datetime, intero, float, array, inline table). Ottimo quando i dati sono per lo più tabelle piatte.
• JSON5 —— JSON con concessioni dev-friendly: commenti, virgole finali, key senza virgolette, apici singoli, stringhe multi-riga. Non è qualcosa che un parser JSON standard accetti; fai opt-in con una libreria JSON5 (o un parser JSONC per il sottoinsieme commenti + virgole finali, es. tsconfig.json).

Collocazione di massima: JSON per lo scambio macchina, YAML per config profondamente annidata modificata da umani, TOML per config piatta di app/tool, JSON5/JSONC quando vuoi JSON-con-commenti per config di editor senza adottare le regole di whitespace di YAML.

Quando usare cosa

• Usa JSON per: API REST/GraphQL, code di messaggi, localStorage del browser, package.json, qualsiasi cosa generata o consumata da codice.
• Usa YAML per: GitHub Actions / GitLab CI, Kubernetes e Docker Compose, playbook Ansible, config di app che gli umani modificano e vogliono commentare.

Un pattern comune: scrivi la config in YAML per leggibilità, poi convertila in JSON al build o al load così la tua applicazione parsa solo JSON.

Convertire tra JSON e YAML

# Python —— da YAML a JSON
import yaml, json
data = yaml.safe_load(open('config.yaml'))
print(json.dumps(data, indent=2))

# Riga di comando con yq
yq -o=json '.' config.yaml      # YAML → JSON
yq -P '.' config.json           # JSON → YAML

Oppure converti istantaneamente nel browser con il convertitore YAML ⇄ JSON di fixjson —— incolli YAML, ottieni JSON (o viceversa), senza inviare dati ad alcun server.

Domande frequenti

YAML è meglio di JSON?

Nessuno dei due è «meglio» —— sono tarati per compiti diversi. YAML è meglio per config modificata da umani (commenti, leggibilità); JSON è meglio per scambio dati macchina (parsing semplice, veloce, senza ambiguità).

JSON è YAML valido?

Sì. Da YAML 1.2, YAML è un superset stretto di JSON, quindi qualsiasi documento JSON valido è anche YAML valido. Il viceversa non è vero —— la maggior parte di YAML non è JSON valido.

Perché YAML trasforma «NO» in false?

YAML inferisce i tipi dagli scalari senza virgolette, e alcuni parser leggono NO, yes, on, off come booleani (il «Norway problem»). Metti il valore tra virgolette ("NO") per forzarlo a stringa. JSON evita tutto questo con virgolette obbligatorie.

Per i file di config dovrei usare YAML o JSON?

Usa YAML se gli umani modificano il file e traggono beneficio da commenti e stringhe multi-riga; usa JSON se è generato o consumato da tooling. Molti team scrivono YAML e convertono in JSON al load.

Converti e valida nel tuo browser

• Convertitore YAML ⇄ JSON —— converti in entrambe le direzioni, lato client
• Formatter YAML —— formatta, ri-indenta e valida YAML
• Cos'è JSON? —— il formato di cui YAML è superset
• Come formattare JSON —— pretty-print dell'output convertito
• YAML 1.2 e compatibilità JSON —— come YAML è diventato un superset di JSON