YAML Syntax and Common Mistakes

YAML is the de facto config format for Docker Compose, Kubernetes, GitHub Actions, and countless other tools. Its whitespace-sensitive syntax is both its strength and its biggest foot-gun.

Basic Syntax

Scalars

string: hello world
number: 42
float: 3.14
boolean: true
null_value: null

Strings

plain: this is a string
quoted: "this is also a string"
single: 'and this too'
multiline_folded: >
  This long text will be
  folded into a single line.
multiline_literal: |
  This preserves
  line breaks exactly.

Lists

fruits:
  - apple
  - banana
  - cherry

Inline form
colors: [red, green, blue]

Maps

person:
  name: Alice
  age: 30
  address:
    city: Portland

Inline form
point: {x: 1, y: 2}

Common Mistakes

The Norway Problem

YAML 1.1 interprets these as booleans!
country: NO    # false
flag: YES      # true
answer: off    # false

Fix: quote the values: country: "NO"

Indentation Errors

YAML uses spaces, not tabs. And indentation must be consistent:

Wrong: mixed indentation
services:
  app:
    image: node
  	ports:  # <-- tab character here = parse error

Right: consistent 2-space indent
services:
  app:
    image: node
    ports:
      - "3000:3000"

Unquoted Special Characters

These break without quotes
message: he said: hello   # colon interpreted as nested key
path: C:\Users\name      # backslashes need quoting
regex: .*\.txt            # quote it

Duplicate Keys

YAML silently uses the last value for duplicate keys. This is a silent bug:

database:
  host: localhost
  port: 5432
  host: production-db  # silently overrides the first host

Validation

Always validate your YAML files before deploying. Use our YAML Validator tool to check syntax, see error locations with line numbers, and view the parsed structure.

YAML vs JSON vs TOML

|---------|------|------|------|

| Comments | Yes | No | Yes |

| Multiline strings | Yes | No | Yes |

| Anchors/refs | Yes | No | No |

Conclusion

YAML's readability comes at the cost of subtle gotchas. Always quote strings that look like booleans or contain special characters. Use consistent 2-space indentation. Validate before deploying.