YAML Cheat Sheet

name: my-app
replicas: 3

The space after the colon is required. Keys are case-sensitive, so Name and name are two different keys.

# Settings for production
port: 8080  # after a value

Everything after # to the end of the line is ignored. After a value, the # needs a space before it. There are no block comments, so put # on every line.

server:
  host: localhost
  port: 8080

Indent with spaces, never tabs. Two spaces is the habit, but any number works as long as keys at the same level line up exactly.

---
kind: Service
---
kind: Deployment

Three dashes start a new document. Kubernetes uses this to keep several objects in one file. The --- before the first document is optional.

fruits:
  - apple
  - banana

A dash and a space start each item. The dashes may also sit level with the parent key instead of indented; both are valid.

users:
  - name: Ada
    role: admin
  - name: Lin
    role: dev

Each dash starts a new item. The item’s other keys line up with the first key after the dash, not with the dash.

ports: [80, 443]
branches: [main, develop]

Flow style, written like JSON. Handy for short lists; switch to dashes once it gets long.

limits: {cpu: 500m, memory: 128Mi}

Flow style for small maps. Any JSON object is also valid YAML, so {"a": 1} works too.

matrix:
  - [1, 2]
  - [3, 4]
grid:
  - - a
    - b

A list inside a list, either inline or with a second dash. The inline form is easier to read.

tags: []
labels: {}

Use these when the key must exist but hold nothing. A key with nothing after it is null, not an empty list.

title: Hello world
url: https://example.com/path

Most text needs no quotes, even with spaces or a colon that is not followed by a space. Quote it when it looks like a number, true/false or null, or starts with a special character.

message: "Line one\nLine two"
color: "#ff6600"

The only style where escapes such as \n, \t and \" work. Without quotes, " #" would start a comment and ": " a new key.

path: 'C:\Users\me'
note: 'It''s fine'

Everything is taken literally, backslashes included, which suits Windows paths and regular expressions. Write a single quote as two: ''.

python: "3.10"
zip: "02134"
answer: "yes"
port: "22:22"

Unquoted, 3.10 becomes 3.1 and 02134 loses its zero, and older parsers read yes as true and 22:22 as 1342. Quotes keep each one exactly as typed.

script: |
  npm ci
  npm test

Every line break is kept and one newline is added at the end. The usual choice for shell scripts, certificates and SQL.

description: >
  This long sentence is
  wrapped in the file.

Lines are joined with spaces into one paragraph, with one newline at the end. A blank line inside the block becomes a real line break.

key: |-
  -----BEGIN KEY-----
  abc123
  -----END KEY-----

The minus strips the newline at the end. Use it when a trailing \n would break the value, such as a token or a key.

footer: |+
  Thanks,
  The team

next: value

The plus keeps every blank line at the end of the block. Rarely needed.

count: 42
price: 9.99
big: 1e6
hex: 0x1F
forever: .inf

Unquoted digits are numbers. 0x1F is 31, .inf is infinity and .nan is not-a-number. Quote anything that must stay text, such as phone numbers.

enabled: true
debug: False

true and false in lower, Title or UPPER case. YAML 1.1 parsers (PyYAML, older Kubernetes tools) also treat yes, no, on and off as booleans.

owner: null
backup: ~
notes:

All three are null. A key with nothing after it is null too, which is easy to do by accident.

released: 2024-03-15
updated: 2024-03-15T09:30:00Z

YAML 1.2 keeps these as text. PyYAML, Ruby and other YAML 1.1 parsers turn them into date objects, so quote dates if the value must stay a string.

port: !!str 8080
count: !!int "42"

A tag overrides the guess. Quotes are simpler for making text; tags are mainly seen in older files.

base_image: &img node:22
build:
  image: *img
test:
  image: *img

&name labels a value and *name repeats it. The anchor must come first in the file.

defaults: &defaults
  retries: 3
  timeout: 30
prod:
  <<: *defaults
  timeout: 60

Copies every key from the anchored map, then your own keys override them, so prod gets retries 3 and timeout 60. Docker Compose, GitLab CI and PyYAML support it; it is not part of YAML 1.2, so check your tool.

x-logging: &logging
  driver: json-file
services:
  web:
    logging: *logging
  worker:
    logging: *logging

Compose ignores top-level keys that start with x-, which makes them a safe place to keep anchors.

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    environment:
      - TZ=Europe/London
    restart: unless-stopped

Ports are quoted on purpose: short values such as 22:22 could be read as a number by older parsers.

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

Each step starts with a dash. Quote versions in a matrix ("3.10"), or 3.10 is read as 3.1.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:1.27

containers is a list of maps, so it needs the dash. Labels under selector and template must match.