YAML for Developers: Syntax, Indentation and Common Pitfalls
YAML is the configuration language of Kubernetes, Docker Compose, GitHub Actions and many other tools. It is pleasant to read, but its reliance on indentation and its automatic typing cause errors that are hard to spot by eye. This guide covers the syntax you need and the pitfalls to watch for.
Mappings, lists and indentation
A mapping is a set of key: value pairs. A list (sequence) is a set of items that start with - . Nesting is shown by indentation, using spaces only.
app: shop
replicas: 2
ports:
- 80
- 443
database:
host: db.internal
port: 5432Any consistent number of spaces works, but two per level is the common convention. Items in the same mapping or list must line up exactly.
Scalars and automatic typing
Unquoted values are typed automatically. The tools on this site use js-yaml 4, which follows the YAML 1.2 core schema:
| Unquoted value | Parsed as (YAML 1.2) |
|---|---|
| 42 | integer |
| 3.14 | float |
| true / false | boolean |
| null or ~ | null |
| yes / no / on / off | string in YAML 1.2 (boolean in older YAML 1.1 parsers) |
| 2024-01-05 | timestamp (js-yaml also reads unquoted dates; written as an ISO date-time in JSON) |
| "42" | string, because it is quoted |
Different tools use different YAML versions, so a value like no (the country code for Norway, for instance) can be a string in one tool and false in another. Quote any value that must stay text. Version numbers are a classic trap: version: 1.10 becomes the float 1.1.
Multi-line strings
literal: |
Line one
Line two
folded: >
These lines are
joined with spaces.| keeps line breaks exactly. > folds lines into one, turning single line breaks into spaces. Add - (as in |-) to remove the final line break.
Anchors, aliases and merge keys
Anchors (&name) label a node and aliases (*name) reuse it. The merge key << copies a mapping into another, which many tools support for shared defaults:
defaults: &defaults
timeout: 30
retries: 3
production:
<<: *defaults
timeout: 60When YAML is converted to JSON, anchors and aliases are expanded into full copies, since JSON has no references.
Common pitfalls and their errors
| Mistake | Typical js-yaml message | Fix |
|---|---|---|
| Tab used for indentation | tab characters must not be used in indentation | Replace tabs with spaces |
| Item indented one space too far or too little | bad indentation of a mapping entry | Line items up exactly |
| Same key twice | duplicated mapping key | Remove or rename one |
| Colon followed by a space inside a value | incomplete explicit mapping pair or a nested mapping error | Quote the value: "time: 10:30" |
| Value starts with a special character such as * or & | unidentified alias or unexpected anchor | Quote the value |
The YAML Validator reports these with a line and column, and YAML to JSON shows exactly how each value was typed.
YAML and JSON
YAML 1.2 is designed as a superset of JSON, so most JSON documents are also valid YAML. Converting is common: use YAML to JSON when a tool needs JSON, and JSON to YAML to make JSON easier to edit by hand.
Frequently asked questions
Why does YAML not allow tabs?
The specification forbids tabs for indentation to avoid ambiguity, since a tab can display as different widths in different editors.
Is YAML a superset of JSON?
YAML 1.2 was designed to be, so most JSON parses as YAML. There are rare edge cases, but in practice JSON is valid YAML.
How do I keep a value like 1.10 as text?
Quote it: version: "1.10".
Comments
Comments start with
#and run to the end of the line. They are not part of the parsed data, so any tool that parses and rewrites YAML, including the YAML Formatter, drops them.