YAML syntax guide with examples
YAML is the most common format for configuration files. These are the rules you need to read and write it without errors.
The building blocks
| Element | YAML | Meaning |
|---|---|---|
| Mapping | name: web | A key with a value |
| Nested mapping | Indent the child keys by 2 spaces | An object inside an object |
| List | - first item | One entry of a list |
| Inline list | [a, b, c] | A short list on one line |
| Comment | # note | Ignored by programs |
| Null | ~ or null or nothing | No value |
Multi-line text
Use | to keep line breaks exactly as written, which suits scripts and certificates. Use > to fold the lines into one paragraph, which suits long descriptions. Add - after the symbol (|- or >-) to drop the final line break.
Anchors and multiple documents
- Write &name before a value to mark it, and *name later to reuse it.
- Use <<: *name to merge a reused mapping into another one.
- Separate several documents in one file with a line of three hyphens (---).
- End a document with ... if a tool needs an explicit end.