YAML: Configuration Files Without the Clutter

Every Kubernetes manifest. Every GitHub Actions workflow. Every Docker Compose file.

YAML is everywhere for configuration. It's readable, it's flexible, and it has some surprising quirks.

Why YAML?

JSON is strict: double quotes, no comments, no trailing commas.

YAML is forgiving: minimal syntax, comments allowed, human-readable.

# YAML configuration
database:
  host: localhost
  port: 5432
  name: myapp

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  }
}

Same data, less noise in YAML.

The Basics

Key-value pairs:

name: John
age: 30

Nested structures (use spaces, not tabs):

person:
  name: John
  age: 30

Lists:

colors:
  - red
  - green
  - blue

Inline lists and objects:

colors: [red, green, blue]
person: {name: John, age: 30}

The Norway Problem

country: NO

What's NO? A boolean false. YAML interprets NO, Yes, on, off, and others as booleans.

Norway's country code becomes false. Your configuration breaks in mysterious ways.

Fix: Quote strings that could be interpreted as booleans.

country: "NO"

The Multiline String Problem

description: This is a long
  description that continues

Is this two lines or one with "that continues" indented? Depends on the YAML parser.

Explicit multiline:

# Literal (preserves newlines)
description: |
  Line one
  Line two

# Folded (joins lines)
description: >
  This is one long
  line when parsed

Indentation Is Significant

Two spaces. Not tabs. Not one space. Not three.

# Correct
parent:
  child: value

# Wrong - tab character
parent:
	child: value

Mixing tabs and spaces breaks YAML silently. Configure your editor to use spaces.

Number Interpretation

version: 1.10

Is that the string "1.10" or the number 1.1? Most parsers interpret it as 1.1.

Floating point math strikes again. Quote version numbers.

version: "1.10"

Anchors and Aliases

YAML can reference repeated content:

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  timeout: 60

Powerful for reducing duplication. Confusing when overdone.

Validating YAML

YAML's flexibility means many things that look valid aren't.

• Use a linter in your editor
• Validate against a schema when possible
• Convert to JSON to see what the parser actually interpreted

If your config isn't working, check what the parser sees, not what you wrote.

YAML vs JSON vs TOML

YAML: Human-readable, many features, quirky edge cases.

JSON: Strict, simple, widely supported, verbose.

TOML: Explicit, fewer surprises, gaining popularity for configs.

For machine-to-machine data, JSON is safer. For human-edited configs, YAML works if you know the gotchas.

---

YAML prioritizes readability over strictness. That trade-off creates edge cases. Quote strings that look like booleans or numbers, use explicit multiline syntax, and validate before deployment.