Cheatsheets:Yaml

Quick reference for smart people — part of our dev cheatsheets collection.

YAML (YAML Ain't Markup Language) is a human-friendly data format — the de-facto standard for configuration files: GitHub Actions, Docker Compose, Ansible, Kubernetes, and the front matter of Quarto documents. It describes plain data with just three building blocks: scalars, lists and maps.

New to YAML? The Learn YAML in Y minutes tour may interest you.

Basic example

A config file is mostly nested maps and lists. YAML parses to the JSON structure on the right:

YAML	Parsed as (JSON)
# pancake-service.yaml service: name: Pancake API port: 8080 debug: true database: host: localhost user: admin password: "s3cret!" features: - billing - search - loyalty	{ "service": { "name": "Pancake API", "port": 8080, "debug": true }, "database": { "host": "localhost", "user": "admin", "password": "s3cret!" }, "features": ["billing", "search", "loyalty"] }

Scalars

Scalars are the leaf values. YAML guesses their type from the spelling:

YAML	Parsed as
name: Pancake API	string "Pancake API"
port: 8080	integer 8080
price: 4.50	float 4.5
debug: true	boolean true
note: null	null
released: 2024-01-15	date
code: "1234"	string — quotes force a string

Null also accepts ~ or an empty value (note:). Booleans also accept True/False. In YAML 1.1 parsers yes/no/on/off are booleans too — see Gotchas.

Strings and quoting

Most strings need no quotes at all. Quote the value when its spelling could be misread:

Want the string	Write	Why
"Pancakes: the recipe"	title: "Pancakes: the recipe"	a colon followed by a space would start a nested key
"#ffcc00"	color: "#ffcc00"	a # at the start of a value begins a comment
"00123"	zip: "00123"	leading zeros can parse as octal (YAML 1.1)
"2024-01-15"	day: "2024-01-15"	an unquoted date becomes a date, not a string
"NO"	country: "NO"	YAML 1.1 parsers read NO as the boolean false
" Ada "	name: " Ada "	leading/trailing spaces are stripped in plain scalars

Single vs double quotes — the two styles that guarantee a string:

YAML	Parsed value
title: 'It''s ready'	It's ready — single quotes escape by doubling
message: "line1\nline2"	line1 + newline + line2 — double quotes process \n, \t, \"

Collections

Lists

A dash and a space, one item per line:

features:
  - billing
  - search
  - loyalty

Short lists can use flow style with square brackets:

features: [billing, search, loyalty]

Maps

Key–value pairs; nesting by indentation:

database:
  host: localhost
  port: 5432
  options:
    pool: 10
    timeout: 30

Flow style:

database: {host: localhost, port: 5432}

Lists of maps

Configs are often a list of items, each item a map:

users:
  - name: Ada
    role: admin
  - name: Bo
    role: viewer

Two spaces per level is the convention, but any consistent number of spaces works. Tabs are forbidden for indentation.

Multi-line strings

Long text uses block scalars: | keeps newlines (literal), > folds them into spaces:

YAML	Parsed value
description: | Line one Line two	Line one Line two
summary: > Folded lines become one paragraph	Folded lines become one paragraph

Chomping indicators control the trailing newline: | keeps one (default), |- strips it, |+ keeps all. An explicit number (|2) sets the block's indentation.

Comments

# a whole-line comment
name: Pancake API   # a trailing comment

Anchors and aliases

Anchor a block with &name, reuse it with *name. The merge key << copies an anchor's keys into a map:

defaults: &defaults
  region: eu-west
  tier: free

service-a:
  <<: *defaults
  name: A

service-b:
  <<: *defaults
  name: B
  tier: paid          # overrides the merged value

Result:

service-a  →  {region: eu-west, tier: free, name: A}
service-b  →  {region: eu-west, tier: paid, name: B}

The merge key is a YAML 1.1 feature — supported by PyYAML, Ruby and most JavaScript parsers, but a strict YAML 1.2 parser may reject it.

Multiple documents

Separate several documents in one stream with a line of --- (e.g. several Kubernetes objects in one file):

---
name: v1
---
name: v2

Gotchas

Tabs are illegal in indentation. YAML indentation must be spaces; a tab raises an error in most parsers.

The Norway problem. In YAML 1.1 parsers (PyYAML, Ruby, older JS libraries), yes/no/on/off/y/n are booleans:

YAML	YAML 1.1 parser	YAML 1.2 parser
country: NO	boolean false	string "NO"

Duplicate keys: the last one wins.

name: Ada
name: Bo

parses to name: Bo — most parsers do not complain.

An empty value is null. note: (nothing after the colon) is null, not an empty string. For an empty string, write note: "".

Any JSON is valid YAML. YAML 1.2 is a superset of JSON — you can paste JSON straight into a .yaml file.

Further reading

• YAML 1.2 spec — the official specification
• Learn YAML in Y minutes — a brisk syntax tour
• yaml-multiline.info — a playground for the block scalars (| and >)
• Cheatsheets:Quarto — YAML front matter in Quarto documents