YAML Is Beautiful Until It Isn't

⏱ 5 min read · Developer Tools

YAML arrived as a relief. After the angle-bracket sprawl of XML and the noise of JSON — where even a simple configuration file required quotes around every string, commas between every value, and curly braces around every object — YAML felt clean. Just keys and values, indented hierarchies, human-readable defaults. Finally, a format that looked like someone designed it for people.

Then you accidentally mixed tabs and spaces, and a deploy failed silently at 11pm.

The Case for YAML

YAML's design philosophy is genuinely appealing. It supports comments — something JSON explicitly doesn't. Its native data types map closely to how people think about data: strings, numbers, lists, maps, booleans. A list in YAML looks like a list: items prefixed with hyphens, one per line. Nesting is expressed through indentation, not brackets, which means less visual punctuation and more visible structure.

For configuration files, these properties are valuable. Reading a GitHub Actions workflow or a Kubernetes deployment manifest in YAML is far more approachable than the equivalent JSON would be. The same configuration in JSON looks like an exam about bracket matching.

The Indentation Problem

YAML's indentation is semantic. Two spaces versus four spaces isn't a style preference — it's a structural decision. Moving a block by one space in either direction changes its position in the hierarchy. A key that belongs to one map accidentally becomes part of another. The YAML is still valid, the parser doesn't complain, and your deployment now refers to the wrong Kubernetes namespace.

The most insidious YAML bugs are structurally valid configurations that do something different than intended. No error. No warning. Just unexpected behavior.

The Tab Problem

YAML forbids tab characters for indentation entirely. This sounds reasonable until you're editing a YAML file in an editor configured to insert tabs when you press the Tab key, or when you paste a code snippet from a source that uses tabs. The parser throws an error, but the error message — "found character that cannot start any token" — doesn't always make the cause obvious to someone encountering it for the first time.

Norway Problem and Other Type Surprises

YAML 1.1 had a surprising set of implicit type conversions. The string "no" became the boolean false. "on" became true. "off" became false. Country codes like "NO" — for Norway — were parsed as booleans in some contexts, leading to what programmers called the "Norway problem." Country code data processing produced a mysterious missing Norway entry.

YAML 1.2 fixed most of these, but many parsers still use 1.1 behavior. The lesson: strings that look like keywords should be quoted. Port numbers, version numbers, and values like "yes", "no", "on", "off", "true", "false" all benefit from explicit quoting in YAML.

Why YAML Won Anyway

Despite these friction points, YAML is dominant in the configuration ecosystem. Kubernetes uses it. GitHub Actions uses it. Docker Compose uses it. Ansible, Helm, and most CI/CD pipelines use it. The reason isn't that YAML is perfect — it's that the alternatives have problems too, and YAML's problems are at least learnable.

The friction is known and manageable: use spaces not tabs, quote ambiguous values, validate your YAML before deploying. These habits become second nature quickly, and the readability gains are real.