YAML: Yet Another Markup Language (or is it?)

  • Original name: 'Yet Another Markup Language' (2001)
  • Renamed: 'YAML Ain't Markup Language' — a recursive acronym emphasizing data over documents
  • Superset: All JSON is valid YAML (but not vice versa)

YAML's Infamous Gotchas

  • Norway problem: NO (country code) becomes boolean false. Quote it: 'NO'
  • Time trap: 12:30 becomes 750 (minutes). Use quotes: '12:30'
  • Version floats: 3.10 becomes 3.1. Quote versions: '3.10'
  • Octal surprise: 0777 is parsed as octal (511 decimal) in YAML 1.1
  • On/Off: on, off, yes, no all become booleans—quote them!

Where YAML Dominates

  • Kubernetes: All manifests (pods, deployments, services) are YAML
  • GitHub Actions: .github/workflows/*.yml for CI/CD pipelines
  • Docker Compose: docker-compose.yml for multi-container apps
  • Ansible: Playbooks and roles for infrastructure automation
  • OpenAPI/Swagger: API specifications (though JSON works too)
  • Home Assistant: Smart home automation config

YAML vs JSON vs TOML

  • YAML: Most readable, but whitespace-sensitive. Great for configs humans edit
  • JSON: More verbose, no comments, but zero ambiguity. Best for APIs/data exchange
  • TOML: INI-style, explicit sections. Used by Rust (Cargo.toml), Python (pyproject.toml)

Syntax Quick Reference

  • key: value — basic key-value pair
  • - item — list item (dash + space)
  • nested:\n child: value — indentation creates hierarchy (2 spaces standard)
  • | — literal block scalar (preserves newlines)
  • > — folded block scalar (folds newlines to spaces)
  • &anchor / *alias — reuse values (DRY principle)
  • --- — document separator (multiple YAML docs in one file)

Common Mistakes

  • Tabs instead of spaces: YAML only allows spaces for indentation
  • Inconsistent indentation: Pick 2 spaces and stick with it everywhere
  • Missing space after colon: 'key:value' fails, 'key: value' works
  • Unquoted special chars: Colons, #, @, and & need quoting in strings
  • Trailing whitespace: Some parsers are picky about spaces at line ends

Pro Tips

  • Use yamllint for CI validation: catches issues before deployment
  • VS Code extension 'YAML' by Red Hat adds autocomplete for K8s schemas
  • Multi-line strings: Use | for code/scripts, > for long paragraphs
  • Anchors for DRY: Define once with &name, reference with *name
  • Convert to JSON to debug: Same data, but no ambiguity about parsing