YAML Syntax Cheat Sheet — Scalars, Collections & Gotchas

# Plain string
name: hello world

# Single-quoted — no escape processing
path: 'C:\Users\docs'
apostrophe: 'it''s here'

# Double-quoted — escape sequences work
greeting: "hello\nworld"
unicode: "\u00e9 = e with acute"

# Literal block — newlines preserved
description: |
  Line one
  Line two
  Line three
# Result: "Line one\nLine two\nLine three\n"

# Folded block — newlines become spaces
summary: >
  This is a long
  sentence that gets
  folded into one line.
# Result: "This is a long sentence that gets folded into one line.\n"

# Strip trailing newline
clean: |-
  no trailing newline here

fruits:
  - apple
  - banana
  - cherry

fruits: [apple, banana, cherry]

server:
  host: localhost
  port: 8080
  debug: true

server: {host: localhost, port: 8080, debug: true}

database:
  primary:
    host: db-primary.example.com
    port: 5432
    replicas:
      - host: db-replica-1.example.com
        port: 5432
      - host: db-replica-2.example.com
        port: 5432
  credentials:
    username: admin
    password: secret

users:
  - name: Alice
    role: admin
    permissions:
      - read
      - write
      - delete
  - name: Bob
    role: viewer
    permissions:
      - read

# Block style with flow-style values
endpoints:
  - path: /api/users
    methods: [GET, POST]
    headers: {Content-Type: application/json}
  - path: /api/health
    methods: [GET]

# Full-line comment
name: app  # Inline comment

# Comments cannot appear inside scalars
# This is NOT a comment: "hello # world" -> the # is part of the string

# Define an anchor
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

# Reference with alias
development:
  database:
    <<: *defaults
    database: myapp_dev

production:
  database:
    <<: *defaults
    host: db.prod.example.com
    database: myapp_prod

default_timeout: &timeout 30

services:
  api:
    timeout: *timeout
  worker:
    timeout: *timeout

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  env: production
---
apiVersion: v1
kind: Secret
metadata:
  name: app-secret
type: Opaque
data:
  password: cGFzc3dvcmQ=
...

# Dangerous — NO becomes false in YAML 1.1 parsers
countries:
  - DK
  - NO   # parsed as boolean false!
  - SE

# Safe — always quote ambiguous values
countries:
  - "DK"
  - "NO"
  - "SE"

# These are NOT strings without quotes
version: 1.0       # float 1.0, not string "1.0"
version: 1.10      # float 1.1 (trailing zero lost!)
zip: 01onal        # string (not a valid number, so stays string)
zip: 01onal        # but...
zipcode: 07110     # octal 3656 in YAML 1.1, string in YAML 1.2!
date: 2024-01-01   # datetime object, not string

# Safe — quote when you mean strings
version: "1.0"
version: "1.10"
zipcode: "07110"
date: "2024-01-01"

# Error — YAML sees "http" as a key
url: http://example.com  # actually works (no space after ://)

# Error — space after colon triggers mapping
message: Note: this breaks
# Fix
message: "Note: this breaks"