YAML

YAML ("YAML Ain't Markup Language") is a human-readable data-serialization format built on significant indentation — no braces or brackets for structure, which makes it easy to read but also means whitespace errors are syntax errors.

Syntax basics

name: Widget
price: 9.99
in_stock: true
tags:
  - new
  - sale
description: null
dimensions:
  width: 10
  height: 5
notes: |
  This is a literal block.
  Line breaks are preserved.
summary: >
  This is a folded block.
  Line breaks become spaces.

• Indentation defines nesting — always spaces, never tabs (YAML forbids tabs for indentation specifically because tab width isn't standardized).
• | (literal block) preserves line breaks exactly as written; > (folded block) joins lines with spaces, useful for long prose that should still read as one paragraph in the source.
• A list item is a line starting with - ; a mapping key is key: followed by a space and the value (the space after the colon is required — key:value with no space is not valid YAML mapping syntax).

Anchors and aliases

defaults: &defaults
  adapter: postgres
  timeout: 30

production:
  <<: *defaults
  database: prod_db

development:
  <<: *defaults
  database: dev_db

&name defines an anchor (a reusable value); *name references it; <<: merges a mapping's keys into the current one. This is YAML's built-in way to avoid repeating the same block — widely used in CI config and Kubernetes manifests to share common settings across otherwise similar blocks.

Multi-document files

---
document: 1
---
document: 2

--- separates multiple YAML documents within one file (and can also mark the start of a single document); ... optionally marks a document's end. Tools that expect one document per file (many config loaders) will only read the first ----delimited block unless explicitly told to parse multiple.

Common pitfalls

• The "Norway problem." Unquoted no, yes, on, off, true, false are parsed as booleans in YAML 1.1 (the version many real parsers still implement) — a country code NO (Norway) or a string value "no" meant as text can silently become the boolean false. Always quote a string value that could be misread this way (country: "NO").
• Leading zeros and version-like strings becoming numbers. version: 1.20 can parse as the number 1.2 (dropping the trailing zero) unless quoted as a string: version: "1.20". The same applies to a value like zip_code: 07030 — quote it, or it becomes a stripped-leading-zero number or is even rejected as invalid octal-looking syntax depending on the parser.
• Tabs in indentation — invalid YAML; an editor that silently inserts tabs (common if YAML editing isn't configured to force spaces) produces a parse error that can be confusing to spot visually.
• Inconsistent indentation width between sibling levels — YAML doesn't require a fixed indent size, but it must be consistent within a given nesting level; mixing 2-space and 4-space indentation at different points in the same file is a common source of "why did this suddenly become a sibling instead of a child."
• Trailing whitespace after a value on the same line as a block scalar indicator (| or >) can silently change how the block is parsed — keep the line clean immediately after the indicator.
• Assuming YAML 1.1 and 1.2 behave identically — the Norway problem and octal-number parsing differ between YAML 1.1 (many older parsers, including PyYAML's default loader) and YAML 1.2 (which narrowed the set of implicit boolean/octal conversions); check which version a specific tool implements when a value parses unexpectedly.

Common uses

YAML is the default configuration format for most CI systems (GitHub Actions, GitLab CI), Kubernetes manifests, Docker Compose, and Ansible playbooks — each layers its own schema/conventions on top of plain YAML syntax, so "is this valid YAML" and "is this a valid GitHub Actions workflow" are different (the second, stricter) questions.

Learn more

• YAML specification — the official 1.2 spec.
• YAML Lint — a quick online syntax validator.
• The Norway Problem — a detailed writeup of the boolean/typing pitfalls above.
• JSON for the simpler, stricter data format YAML is often used as a more human-friendly alternative to.