Guide
YAML 1.1 vs 1.2, and the Norway problem
The single most expensive YAML bug has a country code at the center of it.
By yamltojsonfree · Published · Updated
What the Norway problem is
In YAML 1.1, the unquoted words y, yes, on, n, no, and off are booleans — in upper case, lower case, or capitalized. So a list of country codes containing Norway — NO — quietly becomes false. Nothing errors. The document parses, the deploy succeeds, and somewhere downstream a country is missing from a list because a boolean can’t be a dictionary key or match a string comparison.
YAML 1.2, published in 2009, removed this: only true and false are booleans, and those six words are ordinary strings. It also dropped YAML 1.1’s other implicit conversions — 022 is no longer an octal for 18, and 12:30 is no longer a base-60 number worth 750.
The catch is that both versions are still in wide use, more than fifteen years later. The same file can therefore mean two different things depending on which tool opens it — which is exactly why the YAML to JSON converter on this site defaults to YAML 1.2 and flags every value in your document that would read differently under 1.1.
Every value that changes meaning
The same source, read by each version of the specification.
| YAML source | Read as YAML 1.2 | Read as YAML 1.1 | Safe form |
|---|---|---|---|
| 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" |
Note the last row: 1.10 loses its trailing zero in both versions, because it’s parsed as a number. Version strings should always be quoted.
Which parsers read which version
You rarely choose a YAML version directly — you inherit one from whatever library your tooling happens to use. This is roughly how the ecosystem splits:
| Parser | Version | Notes |
|---|---|---|
| PyYAML (Python) | YAML 1.1 | The default for most Python tooling, including Ansible. |
| ruamel.yaml (Python) | YAML 1.2 | The maintained successor to PyYAML; 1.1 available as an option. |
| js-yaml v5 (JavaScript) | YAML 1.2 | The engine this site uses. Earlier versions read 1.1. |
| go-yaml / sigs.k8s.io (Go) | Mostly 1.2 | What Kubernetes uses; keeps a few 1.1 behaviors for compatibility. |
| SnakeYAML (Java) | YAML 1.1 | The default in Spring Boot configuration loading. |
| libyaml (C bindings) | YAML 1.1 | The base of many language bindings, PyYAML included. |
The practical consequence: a file written on one side of that table and read on the other can silently change values. If your YAML is produced by Python and consumed by Kubernetes — a very common pipeline — it crosses the version boundary. The full code-level details are in the convert YAML to JSON in code guide.
How to write YAML that is safe in both
Three habits remove the entire class of bug. Quote any string that could be mistaken for something else — country codes, version numbers, values with leading zeros, and anything containing a colon. Write booleans only as true and false, never yes, on, or their relatives. And before a file crosses tools, run it through a converter or validator that reports version-dependent values — seeing your YAML as explicit JSON is the fastest way to catch a type you didn’t intend.
References
- YAML 1.1 specification (2005)— the boolean, octal, and sexagesimal forms described above
- YAML 1.2.2 specification— the core schema that limits booleans to true and false
- YAML 1.1 boolean type— the full list of words YAML 1.1 reads as booleans
- PyYAML documentation— YAML 1.1 behaviour in Python
- ruamel.yaml documentation— YAML 1.2 by default, 1.1 as an option
- js-yaml— the YAML 1.2 engine used on this site
- sigs.k8s.io/yaml— the Go library Kubernetes uses
Check your own YAML
Paste a document into the free YAML to JSON converter and every value that changes meaning between YAML 1.1 and 1.2 is flagged, with the value each version produces. Nothing is uploaded — it runs in your browser.
Common YAML errors
The six errors behind almost every failed parse — what each one means, why the parser complains, and the exact fix.
Read the guideConvert YAML to JSON in code
The command line and script equivalents of this site: yq, Python, Node.js, and Go — with the version gotchas each one carries.
Read the guideYAML to JSON
Convert YAML into formatted or minified JSON, with errors pinned to the exact line.
OpenJSON to YAML
Turn JSON back into readable YAML, with control over indentation and key order.
OpenYAML Validator
Check YAML for syntax errors and get a plain-English explanation of what went wrong.
OpenYAML Formatter
Reformat messy YAML with consistent indentation and keep your comments intact.
Open