The YAML Norway problem

What is the Norway problem?

Write country: NO in a YAML file and a great many parsers will hand you the boolean false rather than the string "NO". Norway's ISO country code is a spelling of false in YAML 1.1, along with fifteen other ordinary words, and nothing in the file marks it as unusual — the value simply arrives as a boolean and something downstream fails much later.

It happens because there are two YAML specifications in daily use. YAML 1.1, published in 2005, accepts twenty-two spellings of a boolean: y, Y, yes, Yes, YES, n, N, no, No, NO, true, True, TRUE, false, False, FALSE, on, On, ON, off, Off and OFF. YAML 1.2 cut that to six — true, True, TRUE, false, False, FALSE — so the other sixteen became ordinary text. Both versions are widely implemented, so the same file genuinely means two things.

Booleans are the famous case and not the only one. In YAML 1.1 a value like 12:30 is a number in base sixty, so it becomes 750; a leading zero means octal, so 0755 is 493; and underscores are digit separators, so 1_000 is a thousand. In YAML 1.2 all three are strings or plain decimals. This page checks a file for every member of that family at once.

How to use it

1. Paste your YAML. A whole file or the fragment you are worried about. Nothing is uploaded — the check runs in the page.
2. Read the table. Every plain value whose meaning depends on the version, with what YAML 1.1 makes of it, what 1.2 makes of it, and which rule is responsible.
3. Quote what it flags. A quoted scalar is a string in every version and every parser. Wrapping the value in quotes is the whole fix, and the table empties as you do it.

Which parser am I actually using?

This is the question the Norway problem really turns on, and the answer is rarely obvious from the outside. PyYAML — by far the most used YAML library in Python, and therefore what sits underneath a great deal of infrastructure tooling — implements YAML 1.1, so it reads NO as false today. JavaScript's js-yaml resolves YAML 1.2's core schema, so the same file gives you the string. Go, Ruby and Java libraries vary by version and by which schema they were configured with.

The practical consequence is that a file can pass every test on one machine and change meaning on another, with no error anywhere. A configuration written and validated in a JavaScript toolchain, then read by a Python service, is exactly the shape of that failure — and country codes, feature flags written as on and off, and cron-like times written as 12:30 are all common enough to meet it.

That is also why the fix is quoting rather than choosing a side. You cannot control which parser reads your file downstream, and a quoted string means the same thing to all of them.

Honest limits

This page reads values line by line rather than parsing YAML properly, and it is deliberately narrow about it: only plain key/value lines and list items are checked, anything already quoted is skipped, and a block scalar introduced with a pipe or an angle bracket is skipped along with its whole indented body. That last one matters — a shell script inside a block scalar can contain lines that look exactly like YAML, and flagging them would be a false positive rather than a finding.

The narrowness costs something. Flow collections written on one line, multi-document files, anchors and merge keys are not analysed, so a value hidden inside one of those will not be flagged. The scanner errs toward saying nothing rather than saying something wrong.

The YAML 1.1 rules here are transcribed from yaml.org's own type pages, which publish the resolution regexes, and the transcription is checked against those pages rather than trusted. The 1.2 answers are checked against js-yaml, the library this site already uses elsewhere. Neither of those makes this page a substitute for running your actual parser on your actual file.

Finally, a value being flagged does not mean your setup is broken. If everything that reads the file is on YAML 1.2, NO is already a string and nothing is wrong. The table tells you where a file depends on that assumption, not that the assumption is currently false.

Why is it free?

The check is a few hundred lines of pattern matching that run in your browser. There is no server involved, so there is nothing to bill for and no account to create — which matters here, because a configuration file usually names internal hosts, buckets and services.

Nothing is uploaded and nothing is stored. Reload the page and it has forgotten the file.