YAML Basics

Indentation is the syntax

In YAML, whitespace is not decoration — it is the entire structure. A mapping is a key, a colon, a space, then a value; a nested value is written on the next line, indented further, and two lines at the same indentation are siblings. Tabs are forbidden outright: the spec cannot decide how wide a tab is, so parsers reject them instead of guessing. Editors keep inserting tabs on copy-paste, which is why so many files look perfect and refuse to parse.

The convention is two spaces per level. Four or six are equally valid — the spec only forbids tabs — but two is what Kubernetes and Compose use, what every linter expects, and what keeps deep manifests from scrolling sideways. Mixing widths inside one file is how indentation errors are born, so pick two and let the editor enforce it.

• One level = any fixed space count; two is the convention.
• Tabs in indentation are rejected by parsers, not converted.
• A sequence item may sit at its parent key's indent — the dash is the marker.
• Values can also be written inline in flow style: ports: [8080].

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  cache:
    image: redis:7

services
├─ web
│  ├─ image: "nginx:1.27"
│  └─ ports: ["8080:80"]
└─ cache
   └─ image: "redis:7"

Scalars and the Norway problem

Quoted values are strings, always. Unquoted values are typed by inference, and inference is where YAML's reputation comes from: a bare 8080 becomes the number 8080 and an empty value becomes null, which helps — until inference types something you meant as text, like a country code or a version string.

The classic failure is a list of ISO country codes in which NO — Norway — parses as boolean false: the Norway problem, funny until it silently disables a deployment flag. Version 1.1 went much further, as the table shows. The 1.2 core schema resolves only true and false as booleans and reads the rest of the table below as plain strings or decimal numbers — but because so much deployed software still applies 1.1 rules, the defensive habit is to quote anything that must stay a string.

Quoting and block scalars

YAML offers three ways to write a string. Unquoted is the default and fine for most values. Single quotes are literal — the only escape is doubling a quote ('it''s fine'). Double quotes support backslash escapes like \n and \t, the style JSON uses. The defensive rule carries over: if a value contains anything that could be mistaken for structure — colons, hashes, reserved words — quote it deliberately.

Multi-line text gets block scalars. A literal block, written |, keeps every newline exactly as typed — the right shape for shell scripts and certificates. A folded block, written >, joins lines into one flowing paragraph — the right shape for a long description. Both take a chomping indicator: |- strips the final newline, |+ keeps every trailing one, and plain | keeps exactly one.

script: |
  set -e
  make build
  make deploy

summary: >
  Deploys finish
  in under a minute.

script:   "set -e\nmake build\nmake deploy\n"
summary:  "Deploys finish in under a minute.\n"

Anchors, aliases and reuse

YAML lets one node carry a name other nodes reference. Write &name after a key to anchor its value; write *name anywhere else to alias it, and the parser substitutes a copy of the anchored node. Jobs sharing one retry policy then point at a single definition, and the change lands once.

Two extensions ride on this mechanism. Merge keys, written <<: *name, splice every key of an anchored mapping into the current one — common in Compose and Ansible files, and a 1.1-era convention that never entered the 1.2 core grammar. Anchors can also be abused: aliases nested inside aliases let ten definitions expand to a million nodes — the billion-laughs attack — so parsers you trust budget expansion and report the cap rather than hang.

defaults: &base
  retries: 3
  timeout: 30s

staging:
  retries: 3
  timeout: 30s
  log: *base

defaults:  { retries: 3, timeout: "30s" }
log alias: { retries: 3, timeout: "30s" }   (staging.log)

Comments and multiple documents

Comments start with # and run to the end of the line; a hash inside a quoted string does not count. This is YAML's biggest ergonomic win over JSON, which removed comments by design, and the reason human-maintained config gravitates here: the file explains itself inline, and reviews quote a line and its comment in one diff hunk.

One file may also hold several documents, separated by lines of three dashes; a leading --- is the optional start marker and ... ends a document. This is how one artifact carries a staging config and a production config side by side. This site's converters parse every document and operate on the last one, matching common CLI behaviour.

env: staging
region: eu-1
---
env: production
region: us-2

env: production
region: us-2   (the last document)

What this site's converters accept

Every YAML parser is a parser of a subset — the full 1.2 grammar is famously large — and a converter earns trust by stating its subset instead of letting you discover it by failure. This site's YAML library implements the 1.2 core schema over the block and flow constructs that appear in real configuration files, with deliberate limits where the spec allows unbounded work. The table is the contract.