Engineering guide

The YAML Norway Problem: Why NO Becomes false in YAML

The YAML Norway problem explained: why the country code NO is read as false, which other values change meaning, and how to protect your YAML files.

A YAML list of country codes where the entry NO is crossed out and replaced by a false switch, beside a quoted NO that stays text

Write a list of country codes in YAML: GB, IE, FR, DE, NO. Read it with a YAML 1.1 parser such as PyYAML and you get four pieces of text, followed by the boolean false. Norway has gone, because the parser decided that NO means no, and that no means false. The file is valid, no error is raised, and the damage shows up later, in whatever code receives a false where it expected a country. This is called the Norway problem, and it is the best-known example of a wider habit: YAML guesses the type of every plain value.

This guide explains how the guess works, which other values are changed by it, what the YAML 1.2 specification did about it, and how to write files that every parser reads the same way. It draws on the YAML 1.1 type definitions, the YAML 1.2.2 specification and its list of changes, the StrictYAML article that named the problem, the yamllint documentation, and the PyYAML documentation, all linked at the end. It also uses a comparison that was run for the YAML converter on this site: 700 generated documents, read by PyYAML for YAML 1.1 and by ruamel.yaml for YAML 1.2.

The short answer: put every value that is meant as text in quotes, write booleans as true and false, and do not assume that two tools read the same file in the same way.

What the Norway problem is

The problem is easy to reproduce. A configuration file lists the countries a service supports, one code per line. Four of the codes come back as text. The fifth, written as NO, comes back as the boolean false. The StrictYAML documentation, which gave the problem its name, shows exactly this list, GB, IE, FR, DE, NO, and the result that PyYAML gives for it: four strings and False.

Two things make it nasty. The first is that nothing fails at the point of the mistake. The file is correct YAML, the parser reads it without a warning, and the wrong value travels on until something looks Norway up, compares it with a string, or tries to print it. The second is that the bug depends on the parser. A tool that reads the same file as YAML 1.2 returns the text NO, so a file that works on one machine can break on another, or pass in a test that uses a different library from production.

It is a matter of types, not of syntax. YAML does not make you say whether a value is text, a number, or a boolean. It looks at the characters and decides, and for a handful of plain words the decision differs between versions of the language.

Why a plain NO is a boolean

In YAML, a value that is not in quotes is called a plain scalar, and the parser works out its type by matching it against patterns. The YAML 1.1 definition of the boolean type says that booleans are formatted as English words, true and false, yes and no, or on and off, and may be abbreviated as a single character, y or n. The regular expression on that page lists the spellings that count.

A value in quotes is different: 'NO' and "NO" are always text. Quoting is the way to tell the parser that you have already decided the type. The pattern list applies only to values that are left bare.

  • y, Y, yes, Yes, YES
  • n, N, no, No, NO
  • true, True, TRUE
  • false, False, FALSE
  • on, On, ON
  • off, Off, OFF

Why YAML works this way

YAML was designed for files that people write and read. Letting a person write on or yes, as they would in a settings screen, was meant to be friendly, and so was leaving out quotes around words and numbers. The cost is that the meaning of a file depends on a table of patterns that most authors have never seen.

That table is also where versions differ. The same plain word can be a boolean under one set of rules and text under another, and because the language does not record which set a file was written for, the file itself cannot tell you. Authors who add a %YAML directive can state the version, but most files have none, and what a library does with the directive varies.

Other values that change meaning

NO is only the most famous case. Every plain value goes through the same matching, and the YAML 1.1 types include several more that surprise people. The examples below are written the way they appear in files.

  • yes, no, on, and off become booleans. A key written as on becomes the key true, which is why a settings key named on needs quoting.
  • A number with a leading zero is octal in YAML 1.1. A file mode written as 0755 becomes 493, and 010 becomes 8. Under YAML 1.2 the same text means the decimal 755 and 10, because octal needs the prefix 0o. Neither reading is the mode that the author meant.
  • A number with colons is read in base 60 in YAML 1.1. The specification gives 190:20:30 as an example and says the colon form is convenient for time and angle values. So a clock time such as 12:30:45 becomes the integer 45045, and a port mapping such as 22:22 can become a number.
  • A number with a dot is a decimal. A version written as 1.10 becomes 1.1, and a version such as 9.3 becomes the number 9.3. A version with two dots, such as 3.5.3, stays text.
  • null, Null, NULL, a tilde, and an empty value are all null. A word that happens to be Null becomes nothing.
  • In YAML 1.1 an underscore is ignored inside a number, so 1_000 is 1000. In YAML 1.2 the underscore is not allowed in a number, and the same text is a string.
  • A date such as 2001-01-23 is a timestamp in YAML 1.1. The core schema of YAML 1.2 has no timestamp type, but some libraries that read YAML 1.2 still turn dates into timestamps.

What YAML 1.2 changed

The YAML 1.2 specification was published in 2009. Its history section says its main focus was making YAML a strict superset of JSON, and that it also removed many of the problematic implicit typing recommendations. The list of changes on the specification site spells out the booleans: only the strings true and false are booleans, including the capitalized and upper-case forms, and y, yes, on, and their negative counterparts are parsed as strings.

The same list covers the other surprises from the previous section. Octal numbers need a 0o prefix, so 010 is now parsed as 10 and not 8. Underscores cannot be used inside numbers. The binary and base-60 integer formats were dropped. Under these rules, the Norway list comes back as five strings.

That did not end the problem, because a specification does not change the files and libraries that already exist. Many tools still follow the older rules, and many files were written when yes and no were booleans. The StrictYAML article also argues that the 1.2 specification allows the behavior in some form, while the specification's list of changes says the opposite for booleans. The practical point is that a version number is not enough to know what a given library will do.

Which tools read which version

PyYAML documents support for YAML 1.1, and it turns yes, no, on, and off into booleans in any capitalization that the 1.1 pattern lists. ruamel.yaml reads YAML 1.2 by default, so NO stays text. Those two were the references for the comparison run for the converter on this site, and they agreed with each other, and with the page, in the 1,055 readings of ordinary documents that both could read.

The comparison also showed that a version label is not the whole story. PyYAML leaves a single y or n as text, although the YAML 1.1 type definition lists them as booleans. ruamel.yaml, reading YAML 1.2, still reads numbers with underscores, binary numbers such as 0b101, and dates, which the 1.2 core schema does not define. Every library makes its own choices about which old forms to keep, and that is why a file with tricky values should be tested with the library that will read it in production.

The libraries that you do not use are not covered here. Parsers in Go, Ruby, Java, and other languages each make their own choices, and the way to find out what one does is to give it a file with the values from this guide and look at the types it returns.

How to protect your files

The most reliable protection is to say what you mean. A value that is text should be in quotes, and a value that is a boolean should be true or false, which every version of YAML reads the same way. These habits remove the guesswork without changing the parser.

Docker documents a real case of the same kind. Its Compose file reference says that a port mapping written as HOST:CONTAINER should always be specified as a quoted string, to avoid conflicts with the YAML base-60 float. The advice is general: when a value has a colon, a leading zero, or a dot and is not a number, quote it.

  • Quote country codes, answers such as yes and no that are meant as text, postal codes with a leading zero, identifiers, version strings, and values with colons.
  • Write real booleans as true and false, in lower case.
  • Run a linter. The yamllint truthy rule forbids truthy values other than true and false by default, so an unquoted YES or off is reported. It applies to keys as well as values unless you turn that off.
  • State the version with a %YAML 1.2 directive where your tools understand it, and test that they do.
  • Check the parsed data against a schema, so that a boolean where a country should be fails at once instead of three layers away.
  • Consider a stricter format where you can. StrictYAML turns implicit typing off and treats everything as a string until you say otherwise, and JSON has no implicit typing at all.

How to see what your file really means

Reading a YAML file by eye tells you what it looks like, not what a program will receive. The surest check is to parse it with the same library and the same settings as your application and print the types as well as the values. A list whose last item prints as False, or a version that prints as a number, shows the problem at once.

A second check is to read the file with more than one parser. If a YAML 1.1 reader and a YAML 1.2 reader give different results, the file contains a value whose meaning depends on the version. The YAML converter on this site does this for you: it reads the text as 1.2 or as 1.1, as you choose, and lists every value that the other version would read differently, with its path. That list is a quick way to find the values that need quotes.

Put the check where it will keep working. A short test that loads your configuration and asserts the types of the fields that matter costs a few lines, and it catches the problem the first time someone adds a country, a version, or a flag.

Why JSON does not have this problem

JSON, defined in RFC 8259, has no guessing. Text is always in double quotes. A bare word can only be true, false, or null, and a number has a strict form that does not allow a leading zero or a colon. NO in JSON is not valid until you write it as a string, and when you do, it is a string in every parser.

YAML 1.2 was designed to be a superset of JSON, and the specification says so, which means that a YAML 1.2 reader reads valid JSON as the same data. Writing values JSON-style, with quotes around every string, inside a YAML file therefore gives you the safe behavior, and a flow style written as JSON is a common compromise for files where the types matter more than the look. Tools that turn JSON into YAML should quote text that looks like another type, and the converter on this site does, so that either version of YAML reads the result back as the text it was.

Practical checklist

  • Quote every value that is text, especially country codes, yes and no answers, version strings, and values with colons or leading zeros.
  • Write booleans as true and false, in lower case, and nothing else.
  • Add a YAML linter with the truthy rule to your checks.
  • Parse the file with the same library as production and print the types, not only the values.
  • Test the file with a YAML 1.1 reader and a YAML 1.2 reader if more than one tool will read it.
  • Validate the parsed data against a schema.
  • Quote port mappings and other values with colons, as the Docker documentation advises.
  • Do not rely on the version of a library to know how it reads yes, no, on, and off.

Research and references

This guide was prepared from the authoritative references below.

  1. YAML Version 1.1 type repository: Boolean Language-Independent Type
  2. YAML Version 1.1 type repository: Integer Language-Independent Type
  3. YAML Ain't Markup Language (YAML) revision 1.2.2
  4. YAML 1.2.2 specification: Changes from earlier revisions
  5. StrictYAML: The Norway Problem, why StrictYAML refuses to do implicit typing
  6. yamllint documentation: the truthy rule
  7. Docker Docs: Compose file reference, services, ports
  8. PyYAML documentation