YAML cheat sheet: syntax, multiline strings and gotchas

YAML structures data with indentation (spaces only, never tabs), key: value pairs and - list items. The examples are parsed with PyYAML, which implements YAML 1.1, the version most tools still use.

The basics, parsed

cat > basics.yaml <<'EOF'
name: errcodex
ports: [80, 443]
servers:
  - host: a.example.com
    weight: 2
  - host: b.example.com
    weight: 1
description: |
  Line one
  Line two
summary: >
  folded into
  one line
EOF
python -c "import yaml, json; print(json.dumps(yaml.safe_load(open('basics.yaml')), indent=2))"

{
  "name": "errcodex",
  "ports": [
    80,
    443
  ],
  "servers": [
    {
      "host": "a.example.com",
      "weight": 2
    },
    {
      "host": "b.example.com",
      "weight": 1
    }
  ],
  "description": "Line one\nLine two\n",
  "summary": "folded into one line\n"
}

| keeps newlines, > folds them into spaces; both keep one trailing newline (|- and >- remove it).

YAML 1.1 surprises

python -c "
import yaml
print(yaml.safe_load('''
country: no
answer: on
version: 1.10
zip: 012345
quoted: '012345'
'''))"

{'country': False, 'answer': True, 'version': 1.1, 'zip': 5349, 'quoted': '012345'}

In YAML 1.1, no, off, yes, on are booleans, 1.10 is the float 1.1, and a leading zero means octal. YAML 1.2 only treats true and false as booleans, but many parsers still default to 1.1. Quote values that must stay strings.

Syntax reference