YAML Explained: Syntax, the Norway Problem and Other Traps We Tested

A configuration file lists the countries a feature is enabled for: GB, SE, FI and NO. Everything works except Norway. The code receives False instead of the string “NO”, because the YAML parser decided that “NO” means “no”. This is the famous Norway problem, and it is only one of several ways YAML quietly changes your data.

We parsed a deliberately tricky file with PyYAML 6.0 on Python 3.13. Every value and type shown below comes from that run. Other parsers, especially those that follow YAML 1.2, can give different results, which is part of the problem.

What is YAML?

YAML, short for “YAML Ain’t Markup Language”, is a human-friendly format for structured data. It holds the same kinds of things as JSON, maps, lists, strings, numbers, booleans and nulls, but uses indentation instead of braces and allows comments. In fact, valid JSON is almost always valid YAML. Its readability made it the default for configuration in DevOps tooling: Kubernetes manifests, Docker Compose files, GitHub Actions workflows and Ansible playbooks.

Basic syntax

# a comment
name: shop-api            # a map: key, colon, space, value
replicas: 3
enabled: true
tags:                     # a list: each item starts with "- "
  - web
  - payments
database:                 # a nested map, indented by two spaces
  host: db.internal
  port: 5432
inline_list: [a, b, c]
inline_map: {x: 1, y: 2}

Indentation shows nesting, and spaces are required after colons and dashes. Two spaces per level is the common convention. Lists of maps, very common in Kubernetes, combine both: each - starts a new map whose keys line up underneath it.

How YAML guesses types

An unquoted value is not automatically a string. The parser looks at it and decides whether it is a boolean, a number, null or a string. Here is what PyYAML produced from our test file:

Only the quoted values came through exactly as written. Every row above the quoted ones is a potential bug.

The Norway problem

countries: [GB, NO, SE, FI]
# parsed: ['GB', False, 'SE', 'FI']

Under the YAML 1.1 rules, which PyYAML follows, the words yes, no, on, off, y and n in various capitalisations are booleans. So the country code for Norway became False, while its neighbours stayed strings. The same thing can happen to answers in a survey file, to feature flags named “on”, or to any short code that matches one of those words. The fix is simple once you know it: quote the value, "NO".

Numbers that change

Versions become floats

1.10 and 3.10 were parsed as the numbers 1.1 and 3.1, losing the trailing zero. A CI file that asks for Python 3.10 may really be asking for Python 3.1. GitHub Actions users have hit exactly this, and the standard advice is to quote versions: python-version: "3.10". See also our semantic versioning guide for why versions are not numbers.

Leading zeros mean octal

The zip code 01234 became 668, because a leading zero marks an octal (base 8) number in YAML 1.1. That is useful for file permissions like 0755, which became 493, but disastrous for postcodes, phone numbers and IDs. Oddly, 08 stayed a string, because 8 is not a valid octal digit, so similar-looking values can end up with different types in the same file.

Times become seconds

12:30 became 750. YAML 1.1 reads colon-separated numbers as base 60, the “sexagesimal” format, so 12 × 60 + 30 = 750. A schedule or a port mapping such as 22:22 can be silently converted. Docker Compose documentation recommends quoting port mappings for this reason.

And the opposite surprise

1e10 stayed a string in PyYAML, because its float pattern requires a decimal point. Another parser might read it as ten billion. Relying on the parser to guess is the root of every problem in this section.

YAML 1.1 vs 1.2

YAML 1.2, published in 2009, fixed much of this. It accepts only true and false as booleans, uses 0o for octal, and drops base-60 numbers. But many widely used libraries, including PyYAML, still follow 1.1 by default, and tools built on them inherit the behaviour. Libraries such as ruamel.yaml for Python implement 1.2. Because two tools may read the same file differently, the only safe habit is to quote ambiguous values regardless of version.

Indentation and tabs

YAML does not allow tab characters for indentation. Our test with a tab produced an error starting while scanning for the next token. Misaligned indentation is just as fatal: a list item indented one space less than its siblings produced while parsing a block mapping. Configure your editor to insert spaces and to show whitespace, and always validate after editing. Indentation errors are the most common reason a deployment fails right after a “small config change”.

Duplicate keys

name: first
name: second
# parsed: {'name': 'second'}

PyYAML accepted the duplicate silently and kept the last value. The YAML specification says keys must be unique, and some parsers reject duplicates, but many do not. In a long Kubernetes manifest, a duplicated key can quietly override a setting defined earlier. Linters catch this reliably.

Multi-line strings

literal: |
  line one
  line two
folded: >
  line one
  line two

# literal: 'line one\nline two\n'
# folded:  'line one line two\n'

The pipe | keeps line breaks, which suits scripts, certificates and SQL. The > folds lines into one, which suits long descriptions. Adding -, as in |-, removes the final newline, which matters when the value is compared exactly or used as a secret.

Anchors and merge keys

defaults: &defaults
  retries: 3
  timeout: 30
prod:
  <<: *defaults
  timeout: 60

# prod: {'retries': 3, 'timeout': 60}

&defaults names a block, *defaults reuses it, and << merges it into a map, with local keys winning. This avoids repetition in Docker Compose and CI files. Use it sparingly: heavy anchor use makes files hard to read, and the << merge key is not part of YAML 1.2, so support varies between tools.

Safe loading

Some YAML loaders can create arbitrary programming-language objects from special tags, which means loading untrusted YAML can run code. PyYAML’s safe_load refuses such tags. When we tried to load a document that asked for os.system, it failed with could not determine a constructor for the tag 'tag:yaml.org,2002:python/object/apply:os.system'. Always use yaml.safe_load unless you have a specific reason not to, and never use the unsafe loaders on files from users or the internet.

Linting and validation

• yamllint catches tabs, bad indentation, duplicate keys, trailing spaces and truthy values like yes.
• Schemas check structure and types; editors such as VS Code can validate Kubernetes, Compose and GitHub Actions files against JSON Schemas as you type.
• Tool-specific checks, such as kubectl apply --dry-run=server or docker compose config, validate against what the tool will actually accept.
• Run them in CI, so a broken config fails a pull request, not a deployment.

We did not run yamllint or these tool checks for this article. For secrets, keep them out of YAML files altogether and load them from environment variables or a secrets manager.

Final thoughts

YAML is pleasant to read and dangerous to trust blindly. Its type guessing turned a country code into a boolean, versions into floats, a postcode into an octal number and a time into seconds in our test. Quote anything that is meant to be text, use spaces not tabs, load with a safe loader, and put a linter in your pipeline.

Frequently asked questions

Keep learning