YAML Syntax Cheat Sheet
A concise reference covering YAML indentation rules, scalars, collections, anchors, and multi-document files.
Scalars & Mappings
Key-value pairs and basic scalar types.
name: Alice # string (unquoted)age: 30 # integerheight: 1.68 # floatactive: true # booleannickname: ~ # null (also 'null' or empty)description: "Uses colon: needs quotes"multiline: | Line one Line twofolded: > This becomes one long line.
Lists & Nesting
Sequences and nested structures.
fruits: - apple - banana - cherry# Inline (flow) stylecolors: [red, green, blue]person: { name: Bob, age: 25 }users: - name: Alice role: admin - name: Bob role: viewer
Anchors, Aliases & Multi-doc
Reusing values and separating multiple documents in one file.
defaults: &defaults adapter: postgres host: localhostdevelopment: <<: *defaults database: dev_dbtest: <<: *defaults database: test_db---# Second document starts herename: doc2
Rules & Common Gotchas
Indentation and quoting rules that trip people up.
- Indentation- Uses spaces only, never tabs; consistent indent defines nesting level
- Colons in strings- `key: value: extra` breaks parsing — quote the whole value: `key: "value: extra"`
- Booleans- `true/false`, `yes/no`, `on/off` all parse as booleans depending on the YAML version/parser
- Comments- Start with `#`; no block comment syntax exists
- Document separator- `---` starts a new document, `...` optionally ends one
- Quoting numbers as strings- Wrap in quotes (e.g. `version: "1.0"`) to prevent numeric coercion
Block Scalar Chomping Indicators
Fine-grained control over trailing newlines when using literal (|) or folded (>) block scalars.
clip: | line one line two# 'clip' (default): single trailing newline keptstrip: |- line one line two# '-' strips all trailing newlines -> no final \nkeep: |+ line one line two# '+' keeps ALL trailing blank lines as-isindented: |2 still indented after 2-space strip# explicit indentation indicator overrides auto-detection
Complex Keys & Merge Key Semantics
Non-scalar mapping keys and the precedence rules when merging multiple anchors with <<.
# Complex (non-string) key using explicit-key syntax? [ staging, us-east ]: { replicas: 2 }# Merging multiple maps: later keys win, but explicit# local keys always win over any merged keybase: &base { timeout: 30, retries: 3 }overrides: &over { retries: 5 }final: <<: [ *base, *over ] retries: 10 # explicit key beats both merged values -> 10
YAML Directives & Document Markers
Version pragmas and tag shorthand declarations that precede the document start marker.
%YAML 1.2%TAG ! tag:example.com,2026:---kind: !config name: prod...# '...' explicitly ends a document without starting a new one---# A fresh document begins here; directives only apply# to the single document that immediately follows them
YAML 1.1 vs 1.2 Gotchas
Version differences between parsers (PyYAML defaults to 1.1 rules, most modern tools to 1.2) that cause cross-tool inconsistencies.
- Boolean words- 1.1 treats `y/n/yes/no/on/off` as booleans; 1.2 (JSON-compatible) only treats `true/false` that way
- Octal numbers- 1.1 uses `0777` for octal; 1.2 requires `0o777` — the same literal parses to different types across parsers
- Sexagesimal numbers- 1.1 parses `1:30:00` as base-60 (5400); 1.2 does not support this at all and leaves it a string
- Merge key (<<)- Not part of core 1.2 spec but still implemented by nearly every parser as a de facto extension
- Sets- `!!set` maps keys to `?` (null) values to represent a unique collection, rarely used but valid YAML
- JSON is (almost) valid YAML- Any JSON document is valid YAML 1.2 flow-style, which is why `key: {"a": 1}` parses fine
Watch out for the 'Norway problem': an unquoted `no` or `yes` value can be silently parsed as a boolean by YAML 1.1 parsers — always quote country codes and similar short strings.
