About the YAML Cheat Sheet
YAML reads as though it needs no explanation until an unquoted value changes type behind your back. This page starts with the plain syntax, mappings, sequences, comments and document markers, then gives indentation a table of its own because it causes more failed parses than anything else. That table includes the rule people rediscover under pressure: a tab character used for indentation stops the parser dead, no matter how the file looks in your editor.
Quoting gets its own section because it is the cure for most YAML bugs. Plain scalars are retyped by the parser, single quotes keep everything literal apart from a doubled apostrophe, and double quotes interpret backslash escapes such as \n. All six block scalar headers are laid out together, so you can see exactly what the pipe, the greater than sign and a trailing minus or plus each do to the newlines. Anchors, aliases and the merge key come with a working configuration example rather than an abstract description.
The last table is a list of traps: country: NO becoming false under YAML 1.1, a version of 1.10 rounding to 1.1 because it parses as a float, postcodes read as octal, and a time such as 12:30 turning into 750 in sexagesimal parsers. Filter by a word like anchor, block or indent when you want a single answer. To act on a real file, run it through the YAML Validator or convert it with YAML to JSON.
How to use
- Open the Indentation rules and Gotchas sections first when a file refuses to parse.
- Narrow the page with the section dropdown, or type a term such as anchor in the filter box.
- Copy the Markdown version for your team wiki, or download it as a .md file.
Common questions
- Can I use tabs in YAML?
- Not for indentation. A tab there aborts the parse immediately. Tabs are only legal inside quoted strings and block scalar content.
- Why did my value NO become false?
- YAML 1.1 treats yes, no, on and off as booleans, so the country code turns into false. Quote it as "NO" and it stays a string.
- What is the difference between | and > in YAML?
- The pipe keeps every newline in the block, while the greater than sign folds single newlines into spaces and keeps blank lines as real breaks.
- How do I reuse a block of settings in YAML?
- Anchor it with &name, then pull it into another mapping with <<: *name. Keys written next to the merge override whatever was merged in.
- Is JSON valid YAML?
- It is, because YAML 1.2 is a superset of JSON, so any JSON document parses as YAML, although the reverse is not true.