Working with YAML
YAML is the format people choose so a human can read the file, and the one most likely to interpret that file differently than the human did.
YAML exists because nobody wants to write braces in a config file, and it succeeded — Kubernetes manifests, CI pipelines, Ansible playbooks and Docker Compose files are all YAML. The 1.2.2 specification is far longer than JSON's, and the length is the warning: this is a format with anchors, aliases, multiple documents per file, three ways to write a multi-line string, and an implicit typing system that decides what your unquoted text meant.
That last one is where the real bugs live. Write version: 1.20 and you have written the number 1.2, because a version string is indistinguishable from a decimal. Write enabled: on under YAML 1.1 and you have written a boolean. The famous case is a two-letter country code — under the 1.1 typing rules NO resolves to false, which is why it is known as the Norway problem.
What is more interesting than the trap itself is that it depends on your parser. PyYAML implements YAML 1.1 and does turn NO into false. js-yaml follows the 1.2 core schema, which narrowed booleans to true and false only, and leaves it as the string it looks like. So the same file, byte for byte, means two different things depending on whether Python or Node reads it — and a service written in one language handing config to a service written in the other is where that surfaces.
Indentation has its own rule worth memorising early: tabs are not permitted as indentation anywhere in a YAML document. An editor set to insert tabs will produce a file that no parser will read, and the error it produces rarely says the word "tab". Worth knowing too that YAML is a superset of JSON, so any valid JSON document is already a valid YAML one — occasionally the quickest way out of an ambiguous file is to write the awkward part as JSON and stop arguing with the typing rules.