HowToCodePage

YAML for configuration

Block and flow styles, the type-inference surprises that turn version numbers into floats, anchors and aliases, multi-document files, and the indent rules that cost hours.

Structure without brackets

YAML replaces braces with indentation. Spaces only — a tab character in indentation is an error, not a style choice.

# block style
service:
  name: api
  ports:
    - 8080
    - 8443
  env:
    LOG_LEVEL: info

# the same document in flow style
service: {name: api, ports: [8080, 8443], env: {LOG_LEVEL: info}}
  • key: value for maps, - item for sequences.
  • Scalars may be quoted or bare; quoting removes all type ambiguity.
  • | keeps newlines in a block string, > folds them into spaces, and - after either strips the trailing newline.
  • Comments start with # and must be preceded by whitespace.

The type inference trap

You writeYAML seesWhy it bites
version: 1.10float 1.1Trailing zero is dropped; version comparison breaks
country: NOboolean falseNorway's country code becomes a boolean
time: 22:30sexagesimal integer 1350Legacy YAML 1.1 numeric form
zip: 01234octal 668Leading zero means base 8
on: truebooleanBuild keys named on/off/yes/no
version: "1.10"     # string, not float
country: "NO"       # string, not boolean
zip: "01234"        # string, not octal
enabled: true       # the only boolean you should write

The rule is dull but effective: quote anything that must survive as text, especially versions, IDs and country codes.

Reuse and multiple documents

defaults: &defaults
  retries: 3
  timeout: 30

prod:
  <<: *defaults        # merge key
  timeout: 60          # overrides the anchor

---
# a second document in the same file
kind: ConfigMap

Anchors (&name) define a node and aliases (*name) reuse it, which removes duplication in large config files. The << merge key is a widely supported extension rather than core YAML.

💡
Use the YAML 1.2 core schema and a real parser (ruamel.yaml in Python, yaml in Node) instead of hand-editing. Duplicate keys in the same mapping are an error in the spec but are silently accepted by many loaders, hiding the last-wins surprise.

FAQ

Why does my deployment fail on an indentation change?
YAML has no braces, so indentation is the structure. A one-space shift moves a key under a different parent. Configure your editor to show whitespace and to reject tabs.
When should I not use YAML?
When machine-generated. YAML has many valid spellings of the same value, which makes diffs noisy and generation error-prone. Generate JSON or TOML and keep YAML for hand-edited config.

TOML and INI files Choosing a format: size, speed, readability and tooling

Last refreshed 2026-09-18.