YAML Cheat Sheet

YAML syntax, multiline strings, anchors and common traps.

​
ScalarsCollectionsMulti-line stringsAnchors, aliases and merge keysDocuments and commentsCommon pitfallsWhere YAML is used
36 entries

Scalars

name: Alice

String without quotes

quoted: "yes"

Quote strings that look like other types

count: 42

Integer

pi: 3.14

Float

enabled: true

Boolean (true / false)

empty: null or empty: ~

Null

date: 2026-01-31

Timestamp (parser dependent)

Collections

key: child: 1

Mapping: indentation with spaces creates nesting

- apple - pear

Sequence: one dash per item

list: [a, b, c]

Inline (flow) sequence

map: { a: 1, b: 2 }

Inline (flow) mapping

- name: x value: 1

Sequence of mappings

? [complex, key] : value

Complex mapping key

Multi-line strings

text: | line 1 line 2

Literal block: keeps newlines

text: > folded text

Folded block: newlines become spaces

text: |-

Strip the final newline

text: |+

Keep all trailing newlines

text: "a\nb"

Escapes work in double quotes only

Anchors, aliases and merge keys

base: &defaults retries: 3

Define an anchor with &

prod: <<: *defaults

Merge an anchored mapping with <<: *name

copy: *defaults

Reuse the anchored value with an alias

Documents and comments

# comment

Comment until the end of the line

---

Start of a document

...

Optional end of a document

--- !tag

Explicit type tag (e.g. !!str, !!int)

Common pitfalls

Tabs

Tabs are not allowed for indentation; use spaces

no: / yes: / on: / off:

YAML 1.1 parsers read these as booleans; quote them

version: 1.10

Parsed as the number 1.1; quote it as "1.10"

key: value: more

A second colon needs quotes: "value: more"

- item -item

A dash needs a space after it

country: NO

The Norway problem: NO becomes false in YAML 1.1

Where YAML is used

docker-compose.yml

Docker Compose services

.github/workflows/*.yml

GitHub Actions workflows

deployment.yaml

Kubernetes manifests

openapi.yaml

OpenAPI API descriptions

_config.yml

Jekyll and other static site configs

YAML Cheat Sheet

YAML is the configuration language behind Docker Compose files, Kubernetes manifests, GitHub Actions workflows, OpenAPI documents and many static site generators. It reads easily, but its reliance on indentation and its flexible typing rules produce surprises. This cheat sheet shows the syntax you need and the traps to avoid.

Core syntax

Mappings are key and value pairs written as key: value. Lists use a dash and a space before each item. Nesting is expressed by indenting with spaces, never tabs. Strings usually need no quotes, but values that look like numbers, booleans, null or dates should be quoted if you want them to stay text. Comments start with a hash sign and run to the end of the line.

Multi-line text

Use a literal block with | when line breaks matter, for example in shell scripts inside a CI file. Use a folded block with > for long sentences that should become a single line. A trailing minus (|-) removes the last newline and a plus (|+) keeps every trailing newline.

Reuse with anchors

Anchors, aliases and merge keys (written with the &, * and << symbols) let you define shared settings once and reuse them in several places, which keeps large Compose or CI files short and consistent.

Classic pitfalls

  • A tab in the indentation causes an error.
  • Unquoted yes, no, on, off and NO are booleans in YAML 1.1.
  • A version such as 1.10 becomes the number 1.1 unless quoted.
  • A value that contains a colon followed by a space must be quoted.
  • Inconsistent indentation silently changes the structure instead of raising an error.

Validate before you deploy

Run your file through a linter such as yamllint or convert it to JSON to see what the parser really understood. When something behaves strangely, the JSON view usually reveals the unexpected type or nesting right away.

Frequently Asked Questions

Spaces only. Tabs are not allowed for indentation, and mixing the two is a frequent cause of parse errors. Two spaces per level is the common convention.

A literal block (|) keeps line breaks exactly as written, which suits scripts and certificates. A folded block (>) joins lines with spaces, which suits long paragraphs of text. Add - or + to strip or keep the final newline.

YAML 1.1 parsers treat yes, no, on, off, y and n as booleans, so the country code NO becomes false. Quote the value ("NO") or use a YAML 1.2 parser, which only treats true and false as booleans.

Mark a node with &name to define an anchor and reuse it with *name. Combine with the merge key (<<: *name) to inherit a mapping and override only some of its keys.