YAML Guide

What is YAML?

YAML Syntax Basics

name: Alice
age: 30
active: true
score: 9.5
notes: ~  # null value

server:
  host: localhost
  port: 8080
  tls:
    enabled: true
    cert: /etc/ssl/cert.pem

# Simple list
fruits:
  - apple
  - banana
  - cherry

# List of objects
users:
  - name: Alice
    role: admin
  - name: Bob
    role: viewer

# This is a comment
name: Alice  # inline comment
# age: 30    # commented-out key

# No quotes needed
name: Alice Smith
version: 1.2.3

# Quotes required
message: "Hello: World"     # colon in value
tag: "#production"          # hash in value
path: "  leading space"     # leading space

# Single quotes (literal — no escapes)
regex: 'd+.d+'

# Double quotes (supports escape sequences)
newline: "line1
line2"

YAML Data Types

YAML automatically infers data types. This is powerful but can also surprise you when values like true, null, or 1.0 are interpreted as booleans, null, or floats instead of strings.

# Strings
name: Alice
city: "New York"

# Integers
port: 8080
count: -5

# Floats
ratio: 3.14
temperature: -0.5

# Booleans (true/false, yes/no, on/off)
enabled: true
debug: false

# Null (empty or explicit)
optional: ~
also_null: null

# Multi-line strings
description: |
  This is a literal block scalar.
  Newlines are preserved.
  Great for scripts and SQL.

summary: >
  This is a folded scalar.
  Newlines become spaces.
  Good for long descriptions.

Anchors & Aliases — Avoid Repetition

YAML anchors (&name) mark a value for reuse. Aliases (*name) reference the anchor. This is useful in CI/CD configs and Docker Compose to DRY up repeated blocks:

# Define a reusable block with an anchor
defaults: &defaults
  image: node:18
  restart: unless-stopped
  environment:
    NODE_ENV: production

# Reuse with an alias (merges the block)
web:
  <<: *defaults
  ports:
    - "3000:3000"

worker:
  <<: *defaults
  command: node worker.js

Multi-Document YAML Files

A single YAML file can contain multiple independent documents separated by ---. This is common in Kubernetes, where you might keep a Deployment and Service together in one file:

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  # ...

---
apiVersion: v1
kind: Service
metadata:
  name: my-app-svc
spec:
  selector:
    app: my-app
  ports:
    - port: 80

The YAML formatter on this site handles multi-document files natively. It validates and formats each document independently and shows a document count badge.

Kubernetes YAML Structure

Every Kubernetes manifest follows the same top-level structure. Understanding this structure makes it easier to spot errors:

apiVersion: apps/v1         # API group/version
kind: Deployment            # Resource type
metadata:
  name: my-app              # Required: resource name
  namespace: production     # Optional: namespace
  labels:
    app: my-app
    version: "1.0"
spec:                       # Desired state (varies by kind)
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi

Docker Compose YAML

Docker Compose files define multi-container applications. The top-level keys are services, volumes, and networks:

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    depends_on:
      - app

  app:
    build: .
    environment:
      DATABASE_URL: postgres://db:5432/mydb
      SECRET_KEY: ${SECRET_KEY}  # from .env file
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: secret

volumes:
  db-data:

GitHub Actions Workflow YAML

GitHub Actions workflows live in .github/workflows/*.yml. A malformed workflow fails silently — you only find out after pushing:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

YAML vs JSON — When to Use Each

Rule of thumb: Use YAML for files humans read and edit (config, CI/CD, infrastructure). Use JSON for machine-to-machine data exchange (APIs, databases, serialization). When in doubt, use whichever format the tool or framework already expects.

YAML Best Practices