YAML validator that catches the quiet mistakes

Because YAML 1.1 defined the boolean type as ten spellings — yes, no, on, off and true, false, each in lower, title and upper case — and the loaders most people use still implement 1.1. The consequence has a name, the Norway problem: a country list written as country codes turns NO into the boolean false while every other code stays a string, so Norway vanishes from the data with no error anywhere. YAML 1.2 fixed it by shrinking the core schema to true and false alone, but PyYAML, Ruby's Psych and go-yaml v2 predate that decision and js-yaml 4 and go-yaml v3 do not, which means the same file can produce two different values depending on what reads it. Quoting the value settles it everywhere.

Because a tab has no defined width, and in YAML the width is the structure. The specification bans tabs from indentation outright — it is one of the very few flat prohibitions in the format — precisely because a parser deciding whether a line is a child or a sibling has to count columns, and it cannot count a character whose size depends on an editor setting. Tabs are perfectly legal inside a value and inside a block scalar; it is only the whitespace that marks a block off that must be spaces. The usual fix is to set your editor to insert spaces for YAML files rather than to convert them by hand.

By the specification yes, in practice almost never. YAML 1.2 states that the keys of a mapping must be unique and calls a repeat an error, yet PyYAML, go-yaml, Psych and js-yaml in its default mode all take the last occurrence and discard the earlier ones without a word. The Kubernetes API server rejects the document, and js-yaml in strict mode does too, so the same manifest can be accepted by your local tooling and refused by the cluster. It matters most in files assembled by templating, where two branches each contribute a resources: block and only one of them survives.

Because an unquoted 1.0 is a float, and a float has no memory of the zero you typed. Load it and re-serialise it and you get 1, which is how docker-compose files acquired the famous "version: 3.0 became 3" complaint. The same shape catches API revisions, firmware numbers and anything measured in tenths. Note the asymmetry that makes it hard to spot: 1.2.3 has two dots and stays a string, so most of your version fields survive and the one with a single dot does not. Quote every version number and the problem disappears.

Because a # that follows a space opens a comment, so colour: #4c1d95 sets colour to null and throws the rest of the line away. There is no special case for values that look like something else — the parser sees whitespace, then a hash, and stops reading. The same rule eats a fragment identifier in an unquoted URL and an issue reference such as fixes #214. Quote anything that starts with a hash. A # with no space in front of it, as in tag: v1#build, is just a character in the value.

YAML 1.2 aligned the language with JSON and moved almost all of the old type magic out of the default behaviour; YAML 1.1 resolved yes and no to booleans, numbers with a leading zero to octal, and colon-separated digits to base 60. Which one you get depends entirely on the library: PyYAML implements 1.1 and has done for twenty years, Ruby Psych follows 1.1 for booleans, go-yaml v2 is 1.1 while v3 is 1.2 core, and js-yaml has been 1.2 since version 4. This page parses the structure as 1.2 and then tells you every place where a 1.1 loader would disagree, because a config file usually gets read by more than one of them.

It means a colon turned up inside something the parser had already decided was a plain scalar. The two usual causes are a value that runs onto the next line — because a plain scalar folds across lines, and once it does a second key: on the following line has nowhere to live — and a missing space after a colon higher up, as in port:8080, which makes the whole line one scalar that then swallows the line below it. Both are reported here with the line that started the scalar as well as the line the parser choked on, since the first is where the fix goes.