Cheatsheet: YAML

Q: What is the correct YAML syntax for a list of key-value maps?

Combine the dash-prefixed sequence syntax with indented map keys, e.g. `services:\n - name: web\n image: nginx\n - name: db\n image: postgres`. Each `- ` starts a new map item in the list.

Q: Why does YAML turn my string into a boolean or null unexpectedly?

This is the "Norway problem": unquoted `no`, `yes`, `on`, `off`, `true`, `false`, `null`, and `~` are parsed as booleans/null by many YAML 1.1 parsers. Quote them (`"no"`, `"NO"`) whenever they should stay strings, e.g. a country code.

Q: Can I use tabs for indentation in YAML?

No. YAML indentation must use spaces only — a tab character anywhere in the indentation is invalid and most parsers will throw a syntax error. Configure your editor to insert spaces for YAML files.

Q: How do I write a multi-line string in YAML without breaking existing formatting?

Use a literal block scalar with `|` to preserve line breaks exactly (good for scripts), or a folded scalar with `>` to join lines into a single paragraph. Add chomping indicators (`|-`, `|+`) to control the trailing newline.

Q: Why is a YAML value being read as a string instead of a number, or vice versa?

YAML infers types from unquoted plain scalars, so `version: 1.0` becomes a float, not the string "1.0". Wrap ambiguous values (versions, dates, leading-zero codes like `007`) in quotes to force a string, or use `!!str`/`!!int` tags to force a type explicitly.

Last updated 2026-09-18

Basic syntax

Scalars are simple values such as strings, numbers, booleans, and nulls.

name: John Doe
age: 30
is_active: true
middle_name: null

Lists are sequences represented by a dash followed by a space.

fruits:
  - apple
  - banana
  - cherry

Flow-style lists use JSON-like brackets.

fruits: [apple, banana, cherry]

Maps are key-value pairs separated by a colon and indented for nesting.

person:
  name: John Doe
  age: 30
  is_active: true

Flow-style maps use JSON-like braces.

person: {name: John Doe, age: 30, is_active: true}

Nested lists and maps are expressed with indentation, not braces.

services:
  web:
    image: nginx
    ports:
      - "8080:80"

Comments start with # and continue to the end of the line.

# This is a comment
name: John Doe # Inline comment

Strings and scalars

Plain strings usually do not need quotes, but quoting avoids ambiguity.

plain: hello world
single_quoted: 'keeps backslashes as text'
double_quoted: "supports escapes like 
"

Use single quotes by doubling them inside single-quoted strings.

message: 'It''s YAML'

Literal block scalars with | preserve line breaks.

script: |
  echo "one"
  echo "two"

Folded block scalars with > fold most line breaks into spaces.

summary: >
  This long sentence
  becomes one paragraph.

Chomping indicators control the final newline of block scalars.

keep: |+
  keep trailing newlines
strip: |-
  strip final newline

Explicit tags can force values to strings or other types.

version: !!str 1.0
count: !!int "42"

Reuse and documents

Anchors name a node and aliases reuse it elsewhere.

defaults: &defaults
  retries: 3
  timeout: 30
api: *defaults

Merge keys copy mappings from an anchored map.

defaults: &defaults
  image: node:20
  restart: unless-stopped
worker:
  <<: *defaults
  command: npm run worker

Multiple YAML documents in one stream are separated with ---.

---
name: first
---
name: second
...

Use explicit booleans and nulls for configuration values.

enabled: true
disabled: false
empty: null

Quote values that look like booleans, numbers, dates, or special characters when they must remain strings.

version: "1.0"
date: "2026-06-21"
yes_value: "yes"
colon_value: "host:port"

Common gotchas

The "Norway problem": unquoted no/yes/on/off/true/false/null are parsed as booleans or null, not strings.

country: "NO"     # stays the string "NO"
country: NO       # parsed as boolean false in many parsers
flag: "off"       # stays the string "off"
flag: off         # parsed as boolean false

Indentation must use spaces only. A tab anywhere in the indentation is a syntax error.

# invalid: a tab character before "name" breaks parsing
person:
	name: John Doe

A colon inside an unquoted plain string (e.g. a URL or ratio) can be misread as a key/value separator. Quote it.

url: "http://example.com"
ratio: "16:9"

Leading zeros and version-looking numbers are inferred as numbers unless quoted, which can strip the zero.

zip_code: "07030"   # stays "07030"
zip_code: 07030     # may be parsed as octal/invalid or lose the leading zero
version: "1.0"      # stays "1.0"
version: 1.0        # becomes the float 1

Duplicate keys in the same map are not an error in the spec; the last one silently wins, which hides typos.

# only "prod" survives; the first "env" is silently discarded
env: dev
env: prod

Trailing whitespace after a colon or dash can turn a plain scalar into an unexpected empty value.

name:
# ^ trailing space after the colon above still yields name: null

YAML in CI/CD and config files

GitHub Actions workflows combine mapping keys with sequence steps.

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Docker Compose service definitions rely on nested maps and lists for ports, volumes, and environment variables.

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    environment:
      - NODE_ENV=production
    volumes:
      - ./html:/usr/share/nginx/html

Kubernetes manifests use --- to separate multiple resources in one file and rely on strict indentation.

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  ports:
    - port: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment

Cheatsheet: YAML

See also

FAQ

What is the correct YAML syntax for a list of key-value maps?

Why does YAML turn my string into a boolean or null unexpectedly?

Can I use tabs for indentation in YAML?

How do I write a multi-line string in YAML without breaking existing formatting?

Why is a YAML value being read as a string instead of a number, or vice versa?