YAML spiegato + JSON vs. YAML

Se hai mai modificato un file di configurazione per uno strumento moderno — Docker Compose, GitHub Actions, Kubernetes — hai scritto YAML. È progettato per essere il formato di dati più leggibile per le persone, ma quella leggibilità porta con sé qualche spigolo tagliente. Questa guida spiega come funziona YAML, le insidie da tenere d'occhio e come si confronta con JSON.

Cos'è YAML

YAML («YAML Ain’t Markup Language») è un formato di dati per rappresentare le stesse cose di JSON — coppie chiave/valore, elenchi e strutture annidate — ma con una sintassi calibrata perché le persone la leggano e scrivano a mano. È la scelta di riferimento per i file di configurazione proprio perché è facile da scorrere.

name: RunWebTools
active: true
tags:
  - json
  - free
address:
  city: London
  postcode: null

Come funziona la sintassi

Tre idee coprono la maggior parte di YAML:

• L'indentazione mostra la struttura. L'annidamento si esprime con spazi, non con parentesi graffe. Gli elementi allo stesso livello di indentazione sono fratelli.
• Le coppie chiave/valore usano key: value (lo spazio dopo i due punti è obbligatorio).
• Gli elenchi usano un - iniziale per ogni elemento.

Le insidie

Spazi, mai tab

YAML vieta i caratteri di tabulazione per l'indentazione — provocano un errore di analisi. Configura il tuo editor perché inserisca spazi, perché i due appaiono identici sullo schermo ma solo uno è valido.

Il «problema della Norvegia»

YAML cerca di indovinare i tipi, cosa che ogni tanto gli si ritorce contro. Senza virgolette, no, yes, on e off diventano booleani — è celebre che il codice paese NO della Norvegia possa trasformarsi in false. Quando intendi una stringa letterale, mettila tra virgolette: "NO".

Gli errori di indentazione sono silenziosi

Poiché lo spazio bianco ha significato, una singola riga disallineata può cambiare la struttura senza alcun errore — il file viene semplicemente analizzato come qualcosa che non intendevi. Passarlo per un validatore YAML che riemette il risultato analizzato è il modo più rapido per vedere cosa YAML ha davvero capito.

YAML vs. JSON

Possono rappresentare gli stessi dati — anzi, ogni JSON valido è anche YAML valido. I compromessi:

• Leggibilità: YAML vince per le persone — niente parentesi graffe o virgolette, e supporta i commenti (#), cosa che JSON non fa.
• Rigore: JSON vince per le macchine — la sua sintassi rigida lascia poco spazio all'indovinare i tipi e alle sorprese di indentazione che YAML consente.
• Caso d'uso: scegli YAML per i file che le persone modificano (configurazione) e JSON per i dati che i programmi si scambiano (API).

Devi passare dall'uno all'altro? Formatta e controlla entrambi con il formattatore YAML e il formattatore JSON. Se YAML ti sembra permaloso, la nostra guida su JSON e i suoi errori comuni è una buona lettura di accompagnamento.