YAML Cheat Sheet

YAML syntax essentials.

Basics

# comment
name: Ada Lovelace        # string (quotes optional)
age: 36                   # integer
ratio: 0.75               # float
active: true              # boolean
manager: null             # null (also ~ or empty)
skills:                   # sequence (list)
  - math
  - poetry
address:                  # mapping (nested object)
  city: London
  zip: "W1"
inline_list: [a, b, c]
inline_map: {x: 1, y: 2}

Indentation uses spaces only, never tabs. Any consistent number of spaces works; two is the convention. Items of the same list or map must line up exactly.

Strings and quoting

WriteGivesWhen
plain text"plain text"Most strings
'it''s'"it's"Single quotes: no escapes, double '' for a quote
"tab\there"tab escape processedDouble quotes: \n, \t, é
"8080:80"stringValues with : , #, leading *, &, @ or {
"yes", "no", "on"stringYAML 1.1 parsers read bare yes/no/on/off as booleans
"012"stringLeading zeros, version numbers like 1.10

Multi-line strings

literal: |          # keeps line breaks
  line one
  line two
folded: >           # joins lines with spaces
  this becomes
  one line
stripped: |-        # no trailing newline (use >- for folded)
  text

Anchors, aliases and merge keys

defaults: &defaults
  adapter: postgres
  host: localhost
development:
  <<: *defaults      # merge the anchored map
  database: dev_db

Multiple documents

---
kind: Service
---
kind: Deployment

--- starts a new document in the same file (common in Kubernetes manifests); ... optionally ends one.

The usual errors

Check a file with the YAML validator, or convert it with YAML to JSON to see exactly how it was parsed.

FAQ

Is JSON valid YAML?

Almost always. YAML 1.2 is a superset of JSON, so a JSON document parses as YAML with the same meaning.

.yml or .yaml?

Both work. The official recommendation is .yaml; .yml is common in Docker Compose and GitHub Actions.