YAML Syntax Cheatsheet

Q: Why is YAML strict about indentation?

YAML uses indentation to represent nesting (similar to Python). Each level must use the same number of spaces, and tabs are forbidden. The convention is 2 spaces per indentation level.

Q: What is the difference between single and double quotes in YAML?

Double-quoted strings parse escape sequences (e.g., \n for newline), while single-quoted strings are treated literally without escape processing. In double quotes, backslashes must be escaped (\\).

Q: What are YAML anchors and aliases used for?

Anchors (&) define reusable nodes, aliases (*) reference defined anchors, and merge keys (<<) merge anchor key-value pairs into the current mapping. This avoids duplication and keeps complex configs concise.

Q: What is yq and how do you read YAML with it?

yq is a lightweight YAML processor (like jq for JSON). Use 'yq eval ".key" file.yaml' to read a specific key's value, and 'yq eval ".key[]" file.yaml' to traverse arrays. It supports pipes, path expressions, and file writes.

Q: How do you represent null, boolean, and timestamps in YAML?

Nulls use null, ~, or leaving the value blank. Booleans use true/false, yes/no, on/off (case-insensitive). Timestamps use ISO 8601 format, e.g., 2026-07-17T14:30:00Z or 2026-07-17.

YAML (YAML Ain't Markup Language) is a human-readable data serialization format widely used for configuration files, CI/CD pipeline definitions, and cross-language data exchange. This cheatsheet covers common patterns from basic syntax to advanced features like anchors, multiline strings, and type system.

Updated: 2026-07-17·32 commands

Overview

YAML (YAML Ain't Markup Language) is a human-readable data serialization format commonly used for configuration files. This cheatsheet covers YAML syntax, data types, multiline strings, anchors, and advanced features.

Quick Start

``yaml key: value list: - item1 - item2 map: subkey: subvalue``

Refer to the command table below for detailed usage.

Basic Syntax(6)

Command	Level	Example
`key: value` Basic key-value mapping	Basic	`name: John Doe`
`- item` List/array definition	Basic	`- apple - banana - cherry`
`nested mapping` Nested mapping (indentation for nesting)	Basic	`person: name: Alice age: 30 address: city: Beijing`
`list of mappings` List of mappings (each element is key-value pairs)	Basic	`- name: Alice age: 30 - name: Bob age: 25`
`# comment` Comment (from # to end of line)	Basic	`# This is a YAML comment key: value # inline comment`
`indentation rules` Indentation rules (2 spaces, no tabs)	Basic	`parent: child: grandchild: value`

Data Types(7)

Command	Level	Example
`'single quoted'` Single-quoted string (no escape processing)	Basic	`'Don''t escape \n here'`
`"double quoted"` Double-quoted string (escapes processed)	Basic	`"Line1\nLine2\tTabbed"`
`unquoted string` Unquoted string (simple values)	Basic	`hello world`
`true / false` Boolean values (case-insensitive)	Basic	`enabled: true debug: no verbose: on`
`null / ~` Null value representations	Basic	`value: null also_null: ~ blank:`
`integer / float` Integer and floating-point numbers	Basic	`count: 42 pi: 3.14 hex: 0x1A sci: 1e6`
`ISO 8601 timestamp` ISO 8601 timestamp	Intermediate	`created: 2026-07-17T14:30:00Z updated: 2026-07-17`

Multiline(4)

Command	Level	Example
`\|` Literal block scalar (preserves newlines)	Intermediate	`script: \| echo hello echo world`
`>` Folded block scalar (newlines become spaces)	Intermediate	`description: > This is a long description that will be folded into one line`
`\|-` Literal block with trailing newline stripped	Intermediate	`script: \|- line1 line2`
`\|+` Literal block with all trailing newlines kept	Intermediate	`block: \|+ keep blank lines`

Anchors(5)

Command	Level	Example
`&-name` Define an anchor	Intermediate	`defaults: &defaults timeout: 30 retries: 3`
`*-name` Reference an anchor (alias)	Intermediate	`server1: <<: *defaults host: host1.example.com`
`<<` Merge key (merge anchor mapping into current)	Intermediate	`base: &base x: 1 y: 2 item: <<: *base z: 3`
`nested anchors` Nested anchors and aliases	Intermediate	`conn: &conn host: localhost port: 5432 db: <<: *conn name: mydb`
`multiple aliases` Single anchor referenced multiple times	Intermediate	`shared: &shared env: prod srv1: <<: shared name: web srv2: <<: shared name: worker`

Advanced(10)

Command	Level	Example
`GitHub Actions workflow` YAML in GitHub Actions	Intermediate	`name: CI on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4`
`GitLab CI pipeline` YAML in GitLab CI	Intermediate	`stages: - build - test build_job: stage: build script: - make build`
`yq eval` yq read YAML value	Basic	`yq eval '.name' config.yaml`
`yq eval array` yq traverse array elements	Basic	`yq eval '.items[]' config.yaml`
`yq eval with pipe` yq piped queries	Intermediate	`yq eval '.users[] \| select(.active == true)' config.yaml`
`yq eval -i` yq in-place edit YAML file	Intermediate	`yq eval -i '.version = "2.0"' config.yaml`
`yq --yaml-all` yq process all documents in multi-doc YAML	Expert	`yq eval --yaml-all '.kind' multi.yaml`
`yq path expressions` yq path expressions (wildcard, recursive)	Expert	`yq eval '.. \| select(. == "target")' config.yaml`
`merge YAML files` Merge multiple YAML files	Expert	`yq eval-all '. as $item ireduce ({}; . * $item)' a.yaml b.yaml`
`multi-document YAML` Multi-document YAML (separated by ---)	Intermediate	`--- apiVersion: v1 kind: Pod --- apiVersion: v1 kind: Service`

FAQ

Why is YAML strict about indentation?

What is the difference between single and double quotes in YAML?

What are YAML anchors and aliases used for?

What is yq and how do you read YAML with it?

How do you represent null, boolean, and timestamps in YAML?

This cheatsheet is compiled from official tool documentation. Last updated: 2026-07-17.