Guida

YAML 1.1 vs 1.2

Il bug YAML più costoso in assoluto ha un codice paese al centro.

Di yamltojsonfree · Pubblicato il 25 agosto 2026 · Aggiornato il 1 settembre 2026

Che cos’è il problema Norway

In YAML 1.1 le parole senza virgolette y, yes, on, n, no e off sono booleani — in maiuscolo, minuscolo o con l’iniziale maiuscola. Così un elenco di codici paese che contiene la Norvegia — NO — diventa silenziosamente false. Nulla fallisce. Il documento si analizza, il deploy riesce, e da qualche parte a valle manca un paese in un elenco perché un booleano non può essere una chiave di dizionario né soddisfare un confronto tra stringhe.

YAML 1.2, pubblicato nel 2009, ha eliminato tutto questo: solo true e false sono booleani, e quelle sei parole sono stringhe ordinarie. Ha anche abbandonato le altre conversioni implicite di YAML 1.1 — 022 non è più un ottale che vale 18, e 12:30 non è più un numero in base 60 che vale 750.

Il problema è che entrambe le versioni sono ancora ampiamente in uso, più di quindici anni dopo. Lo stesso file può quindi significare due cose diverse a seconda dello strumento che lo apre — ed è esattamente per questo che il convertitore da YAML a JSON di questo sito usa YAML 1.2 di default ed evidenzia ogni valore del tuo documento che verrebbe letto diversamente in 1.1.

Ogni valore che cambia significato

La stessa sorgente, letta da ciascuna versione della specifica.

Sorgente YAML	Letto come YAML 1.2	Letto come YAML 1.1	Forma sicura
country: NO	"NO"	false	country: "NO"
enabled: yes	"yes"	true	enabled: true
debug: off	"off"	false	debug: false
mode: 022	22	18	mode: "022"
start: 12:30	"12:30"	750	start: "12:30"
version: 1.10	1.1	1.1	version: "1.10"

Nota l’ultima riga: 1.10 perde lo zero finale in entrambe le versioni, perché viene analizzato come numero. Le stringhe di versione andrebbero sempre messe tra virgolette.

Quali parser leggono quale versione

Raramente scegli direttamente una versione di YAML — la erediti dalla libreria che i tuoi strumenti usano. Ecco più o meno come si divide l’ecosistema:

Parser	Versione	Note
PyYAML (Python)	YAML 1.1	Il default della maggior parte degli strumenti Python, Ansible incluso.
ruamel.yaml (Python)	YAML 1.2	Il successore mantenuto di PyYAML; 1.1 disponibile come opzione.
js-yaml v5 (JavaScript)	YAML 1.2	Il motore usato da questo sito. Le versioni precedenti leggevano 1.1.
go-yaml / sigs.k8s.io (Go)	Prevalentemente 1.2	Ciò che usa Kubernetes; mantiene alcuni comportamenti 1.1 per compatibilità.
SnakeYAML (Java)	YAML 1.1	Il default nel caricamento della configurazione di Spring Boot.
libyaml (C bindings)	YAML 1.1	La base di molti binding di linguaggio, PyYAML incluso.

La conseguenza pratica: un file scritto da un lato di quella tabella e letto dall’altro può cambiare valori in silenzio. Se il tuo YAML è prodotto da Python e consumato da Kubernetes — una pipeline molto comune — attraversa il confine di versione. I dettagli a livello di codice sono nella guida Convertire YAML in JSON nel codice.

Come scrivere YAML sicuro in entrambe le versioni

Tre abitudini eliminano l’intera classe di bug. Metti tra virgolette qualsiasi stringa che potrebbe essere scambiata per altro — codici paese, numeri di versione, valori con zeri iniziali e qualsiasi cosa contenga due punti. Scrivi i booleani solo come true e false, mai yes, on o i loro parenti. E prima che un file passi da uno strumento all’altro, fallo passare da un convertitore o da un validatore che segnali i valori dipendenti dalla versione — vedere il tuo YAML come JSON esplicito è il modo più rapido per cogliere un tipo che non intendevi.

Riferimenti

Specifica YAML 1.1 (2005) — le forme booleana, ottale e sessagesimale descritte sopra
Specifica YAML 1.2.2 — lo schema core che limita i booleani a true e false
Tipo booleano di YAML 1.1 — l’elenco completo delle parole che YAML 1.1 legge come booleani
Documentazione PyYAML — il comportamento YAML 1.1 in Python
Documentazione ruamel.yaml — YAML 1.2 di default, 1.1 come opzione
js-yaml — il motore YAML 1.2 usato su questo sito
sigs.k8s.io/yaml — la libreria Go che usa Kubernetes

Controlla il tuo YAML

Ogni valore della tabella qui sopra viene evidenziato dal convertitore e dal validatore di questo sito, con ciò che ciascuna versione produrrebbe. Niente viene caricato.