What Is YAML? A Beginner's Guide
If you've ended up here, something probably handed you a .yaml or .yml file and expected you to know what to do with it. That's honestly how most people meet YAML — not by choice, but because a tool they wanted to use needed a config file, and this is the format it picked.
YAML stands for "YAML Ain't Markup Language" (yes, it's a recursive joke, programmers do that). The whole idea behind it was to be a format humans could read and write comfortably, unlike XML with its endless closing tags, and more expressive than a plain properties file.
What YAML actually looks like
Here's a small one:
name: Aditi Verma
role: backend engineer
skills:
- python
- postgres
- docker
remote: trueThat's it. No curly braces, no commas at the end of lines, no quotes required around most strings. Indentation is what tells YAML how things are nested — which is also, honestly, where most of the pain comes from later. Two spaces in the wrong place and the meaning of the whole file changes.
The building blocks
- Key-value pairs —
key: value, the most basic unit. - Lists — lines starting with a dash, like the
skillsblock above. - Nested maps — a key whose value is itself a set of indented key-value pairs.
- Comments — anything after a
#is ignored, handy for leaving notes in a config file.
Once you can read those four things, you can read almost any YAML file you'll come across, even a long one. It's really just those patterns repeated and nested.
Why it caught on
YAML ended up as the default format for a lot of infrastructure tools — Docker Compose, Kubernetes, GitHub Actions, Ansible — mostly because config files in those tools tend to be read by humans a lot more often than they're written by machines. A format that's easy to skim, with comments allowed, was a better fit than JSON for that job.
The tradeoff is that YAML is stricter about whitespace than most people expect from something that looks so casual. If you're pasting a file in and something won't parse, our guide to common YAML errors is a fast way to spot the usual suspects, and you can drop the whole file into the formatter to get the exact line number.