JSON vs YAML: le differenze spiegate

Avrai sicuramente notato che alcuni progetti usano file .json per la configurazione mentre altri usano .yaml o .yml. Entrambi i formati rappresentano dati strutturati. Entrambi sono leggibili dagli umani. Qual è la differenza reale, e quando dovresti scegliere l'uno o l'altro?

Li ho usati entrambi ampiamente — JSON è il mio driver quotidiano per API e scambio di dati, mentre YAML è il mio go-to per manifest Kubernetes, GitHub Actions e Docker Compose. Risolvono problemi simili ma hanno personalità molto diverse.

Fianco a Fianco: La Stessa Config in Entrambi i Formati

Ecco un oggetto di configurazione database scritto in JSON:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true,
    "pool": {
      "min": 2,
      "max": 10
    },
    "replicas": ["replica1.db", "replica2.db"]
  }
}

E qui la stessa config in YAML:

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true
  pool:
    min: 2
    max: 10
  replicas:
    - replica1.db
    - replica2.db

YAML è visibilmente meno caotico. Niente virgolette intorno alla maggior parte delle stringhe, niente parentesi graffe, niente virgole. Per un file di configurazione che gli umani modificano regolarmente, quella chiarezza si accumula. Ma YAML ottiene questo risultato essendo significativamente più complesso sotto il cofano.

Dove Brilla YAML

• File di configurazione modificati dagli umani. Pipeline CI/CD (GitHub Actions, GitLab CI), manifest Kubernetes, Docker Compose, playbook Ansible. Tutto YAML. Non è una coincidenza — sono file che gli umani scrivono a mano.
• Commenti. YAML supporta i commenti con #. Fondamentale per i file di configurazione dove vuoi spiegare perché un'impostazione è quella che è. JSON non supporta affatto i commenti.
• Stringhe multi-riga. YAML ha scalari a blocco per contenuti multi-riga che si leggono naturalmente. JSON richiede sequenze di escape \n.
• Meno rumore visivo. Non è necessario mettere le virgolette alla maggior parte delle stringhe, niente parentesi graffe di chiusura, niente virgole finali di cui preoccuparsi.
• Anchor e alias. YAML ti permette di definire un valore una volta e riferirlo altrove con &anchor e *alias — comodo per file di configurazione DRY.

Dove Vince JSON

• Rigidità. JSON ha una sola rappresentazione valida per qualsiasi struttura dati. YAML ha una dozzina di modi per scrivere la stessa cosa, il che crea incoerenza tra i team.
• Nessuna trappola da indentazione. JSON usa parentesi graffe e quadre. YAML usa l'indentazione, il che significa che un singolo spazio mal posizionato può rompere silenziosamente l'intera tua config.
• Performance di parsing. I parser JSON sono veloci e semplici. I parser YAML sono complessi — YAML 1.1 ha regole di coercizione di tipo implicito notoriamente insidiose.
• Supporto universale delle librerie. Ogni linguaggio ha un parser JSON battle-tested e zero-dependency. Le librerie YAML variano in qualità e conformità alle specifiche.
• Tooling. Linter, formatter, validatori di schema — il tooling JSON è più maturo e ampiamente disponibile.
• Payload API. JSON è il linguaggio universale delle API web. Inviare YAML via HTTP sarebbe non convenzionale e causerebbe attriti.

Le Insidie di YAML che Ti Faranno Soffrire

YAML ha alcuni comportamenti genuinamente sorprendenti che hanno causato veri incidenti in produzione. La maggior parte deriva dalle regole di tipo implicito in YAML 1.1, che YAML 1.2 ha reso più rigide. Conoscile prima di affidarti a YAML per qualcosa di critico:

# YAML 1.1 implicit type coercion — all of these become booleans:
enabled: yes   # → true
disabled: no   # → false
country: NO    # → false (!)  ← the Norway Problem

# Safe practice: quote strings that look like booleans
country: "NO"
enabled: "yes"

• Interi ottali. In YAML 1.1, 010 viene parsato come 8 (ottale), non 10. Rilevante per cose come i permessi dei file.
• Tab vs spazi. YAML vieta i tab per l'indentazione. Inserisci un tab da un editor di codice e il tuo file si rompe silenziosamente o genera un errore criptico.
• Null impliciti. Un valore vuoto in YAML diventa null. Facile da perdere quando si modifica a mano.
• Ambiguità stringa vs numero. port: 8080 ti dà un intero. version: 1.0 potrebbe darti un float. A volte vuoi la stringa "1.0". Metti sempre le virgolette quando conta.

Guida Pratica alla Decisione

Scegli YAML quando:

• Scrivi file di configurazione che gli umani modificano direttamente: CI/CD, Kubernetes, Docker Compose, Ansible
• Il file avrà commenti che spiegano le impostazioni
• I valori stringa multi-riga sono comuni
• L'ecosistema in cui lavori usa già YAML (non combattere la convenzione)

Scegli JSON quando:

• Invii o ricevi dati tramite un'API
• I dati sono generati e consumati programmaticamente (nessuna modifica umana)
• Hai bisogno di coerenza garantita nel parsing tra diversi strumenti e linguaggi
• Lavori in un ecosistema che standardizza su JSON: npm (package.json), VS Code (settings.json), Angular, TypeScript

Conversione tra i Due Formati

Hai bisogno di convertire la configurazione YAML in JSON per uno strumento che non capisce YAML? Usa il convertitore da YAML a JSON. Vuoi fare il contrario? Il convertitore da JSON a YAML lo gestirà. Il YAML Formatter è anche utile quando incolli YAML che si è disallineato. E se il tuo YAML non si parsifica, il YAML Validator ti dirà esattamente dov'è il problema.

La Conclusione

JSON e YAML sono complementari, non in competizione. Usa JSON per lo scambio di dati — API, archiviazione programmatica dei dati, serializzazione. Usa YAML per i file di configurazione che gli umani leggono e modificano. La maggior parte dei progetti maturi usa entrambi: package.json per le dipendenze, .github/workflows/*.yml per il CI. Una volta capito per cosa è ottimizzato ogni formato, la scelta diventa ovvia.