Che cos’è un file YAML?

YAML è un formato di testo semplice che si apre in qualsiasi editor. Si usa per spostare dati fra programmi e la modifica.

L’estensione è .yaml e il nome per esteso è YAML Ain't Markup Language. Contano entrambi meno di ciò che il file può contenere, ed è di questo che parla il resto della pagina.

Risale al 2001. La specifica è YAML 1.2.

L’età serve saperla per un motivo pratico: più un formato è vecchio, più programmi hanno avuto tempo di impararlo.

È pubblicata per intero, quindi la si può implementare partendo dal documento invece che per osservazione: è per questo che il formato compare in così tanti programmi, ed è per questo che file scritti vent’anni fa si aprono ancora. Una specifica pubblicata però non è la stessa cosa di una esente da royalty: dove un formato incapsula un codec, le licenze sui brevetti restano una questione a parte che lo standard non risolve.

YAML conserva il suo contenuto esattamente. Risalvarlo non cambia nulla, quindi puoi aprirlo, modificarlo e risalvarlo quante volte vuoi senza accumulare danni: è questo che ne fa un formato di lavoro e non di consegna.

YAML ha una sintassi per i commenti, ed è la differenza fra un file che cura una persona e uno che scrive un programma. I commenti sono la prima cosa che si perde convertendo in un formato che non li ha, e nessuno ti avvisa.

Visual Studio Code e yq lo leggono, e così fanno quasi tutti i programmi dello stesso tipo.

Quando un file non si apre, il formato è raramente il problema: più spesso è il programma a essere più vecchio di lui. Convertire in qualcosa di più vecchio è la via d’uscita affidabile, ed è a questo che serve il resto di questo sito.

Nessun browser lo legge.

È di gran lunga il motivo più comune per convertirlo: non che il formato sia scadente, ma che il posto in cui vuoi mostrare il file non sappia leggerlo.

YAML è pensato per essere aperto e modificato. Tieni il file in questo formato per tutto il tempo in cui il lavoro va avanti, ed esporta da lì ogni volta che serve una copia finita.

Pochissime persone scelgono questo formato. Lo ricevono: manifesti Kubernetes, pipeline di GitHub Actions e GitLab CI, playbook Ansible, Docker Compose, specifiche OpenAPI, l’intestazione dei generatori di siti statici. Tutti si sono assestati qui, e gli ecosistemi che li circondano sono abbastanza grandi da far sì che la decisione non sia più sul tavolo.

Questo condiziona cosa sia una pagina utile sullo YAML. La domanda quasi mai è se usarlo, ma come evitare i modi specifici in cui si rompe, perché fallisce in silenzio più spesso di qualsiasi altro formato di configurazione di uso comune.

Non ci sono parentesi graffe né marcatori di chiusura. La profondità a cui è scritta una riga determina da cosa dipende, quindi uno spazio in più cambia il significato del documento — e piuttosto spesso produce un documento ancora valido che dice qualcos’altro.

Due regole evitano quasi tutto. Mai tabulazioni: la specifica le vieta per l’indentazione, e un editor che ne inserisca una provoca un errore il cui messaggio raramente menziona la causa. E indentazione costante, due spazi per livello per convenzione, perché mescolare larghezze diverse nello stesso file è legale e rende la struttura illeggibile a colpo d’occhio.

Lo YAML deduce cosa sia un valore scritto senza virgolette, e le sue deduzioni hanno causato incidenti reali. Quella famosa è il problema della Norvegia: nello YAML 1.1 un no senza virgolette è il booleano falso, quindi in un elenco di codici paese quello della Norvegia smette di essere NO e diventa false. Lo stesso vale per on, off, y e n.

I numeri di versione sono la seconda trappola: 1.20 viene letto come il decimale 1,2 e lo zero finale sparisce. Gli orari sono la terza, perché 22:30 può essere interpretato come un numero in base sessanta invece che come testo. E un valore come 0755 può essere letto come ottale.

La difesa non è saperlo, è un’abitudine: mettete fra virgolette tutto ciò che deve significare testo. Versioni, codici paese, identificatori, orari, qualsiasi cosa con zeri iniziali. Lo YAML 1.2 ha risolto diversi di questi casi e molti analizzatori continuano a implementare l’1.1, quindi a proteggervi è l’abitudine e non la specifica.

Lo YAML permette di definire un blocco una volta e riutilizzarlo. Un’ancora lo marca, un alias lo referenzia, e una chiave di fusione inserisce un blocco comune in più punti — è così che una pipeline di integrazione continua evita di ripetere le stesse sei righe in ogni task.

È genuinamente utile ed è il punto in cui lo YAML smette di essere leggibile per chi non ha mai visto questa sintassi. Due avvertenze pratiche: un alias è un riferimento e non una copia, quindi ciò che è condiviso è condiviso; e diversi strumenti che consumano YAML non implementano le ancore o le espandono in modi sorprendenti. Vale la pena verificarlo prima di costruirci sopra una configurazione grande.

Un blocco scritto con una barra verticale conserva gli a capo: è corretto per uno script, un certificato o un messaggio con paragrafi. Scritto con il segno di maggiore, le righe si piegano in una sola, corretto per una frase lunga spezzata per comodità dentro il file.

Ciascuno ammette un suffisso che controlla l’a capo finale — un meno lo rimuove, un più conserva tutti quelli presenti. Conta molto più di quanto sembri quando il valore è una chiave, un token o uno script: un a capo di troppo è la spiegazione classica per cui un certificato viene rifiutato o un comando si comporta diversamente nella pipeline rispetto alla vostra macchina.

Tre trattini su una riga propria iniziano un nuovo documento, così un unico file può contenerne una sequenza. Kubernetes lo usa costantemente — un deployment, un service e una configmap nello stesso file — e qualsiasi strumento che lo legge se lo aspetta.

Vale la pena saperlo perché cambia cosa significhi «analizzare questo file». Un lettore che carica un documento ignora silenziosamente tutto ciò che viene dopo il primo separatore, ed è così che si perde metà configurazione senza un solo errore. La funzione corretta si chiama di solito «carica tutti i documenti», non «carica il documento».

Verso JSON, XML, TOML e NDJSON l’albero resta com’è, con le chiavi nell’ordine in cui erano: nulla in questo convertitore le ordina. Verso INI non è possibile alcun albero, perché un INI è un elenco piatto di sezioni e chiavi: la struttura annidata viene appiattita in chiavi con il percorso separato da punti — il primo livello diventa il nome della sezione e ciò che vi pende sotto diventa la chiave al suo interno — con gli indici degli array trasformati in tratti dello stesso percorso.

Ciò che non sopravvive a nessuna di queste uscite sono i commenti. Né YAML, né TOML, né INI, né XML li conservano qui: l’analizzatore produce un valore e non c’è alcun canale dove salvare il testo che li accompagnava. Convertire un manifesto documentato in JSON e tornare indietro lo lascia senza una sola spiegazione, il tipo di perdita che nessuno nota finché non torna sul file sei mesi dopo. La conversione avviene nel vostro browser, con un tetto di 100 MB per file.

Usate un editor con modalità YAML. Vi mostrerà le guide di indentazione, convertirà le tabulazioni e segnalerà un errore strutturale dove si trova, invece di lasciare che lo scopra un deployment. Per qualsiasi cosa destinata a un repository, un analizzatore nel git hook di commit vale i dieci minuti che costa configurarlo.

E validate prima di pubblicare quando esiste uno schema. Kubernetes, OpenAPI e la maggior parte dei sistemi di integrazione continua pubblicano il proprio, e una validazione cattura la chiave messa nel posto sbagliato che l’analizzatore accetta volentieri e il sistema rifiuta alle tre di notte.