YAML: A Complete Guide for Developers

Master YAML syntax, understand its differences from JSON, and learn how to write clean configuration files for Docker, Kubernetes, GitHub Actions, and more.

By Belqassim Djafer · Published 2026-05-12 · Updated 2026-07-01

What Is YAML?

YAML (YAML Ain't Markup Language) is a human-friendly data serialization standard. Unlike JSON or XML, YAML is designed to be readable by humans first. It is widely used for configuration files, CI/CD pipelines, infrastructure-as-code, and data exchange between services.

YAML is a superset of JSON: every valid JSON document is also valid YAML. However, YAML offers much richer syntax including comments, multi-line strings, and anchors.

Basic YAML Syntax

Scalars (strings, numbers, booleans)

name: Alice
age: 30
active: true
score: 9.5
description: "Quoted string with special chars: & < >"

YAML infers types automatically. true, false, yes, no, on, off are all interpreted as booleans (YAML 1.1). This has caused many bugs — use quotes when the value must be a string.

Mappings (key-value pairs / objects)

user:
  id: 42
  name: Bob
  address:
    city: Paris
    country: France

Indentation defines structure. YAML uses spaces only — never tabs.

Sequences (lists / arrays)

fruits:
  - apple
  - banana
  - cherry

# Inline sequence
colors: [red, green, blue]

Multi-line Strings

YAML has two block scalars:

# Literal block (|): preserves newlines
description: |
  Line one.
  Line two.
  Line three.

# Folded block (>): folds newlines into spaces
summary: >
  This is a long sentence that
  continues on the next line and
  will be folded into one line.

YAML vs JSON

Use JSON for APIs and machine-to-machine communication. Use YAML for configuration files and anything humans will read and edit.

Anchors and Aliases: DRY Configuration

YAML anchors (&) define a reusable block; aliases (*) reference it. This eliminates repetition in large config files.

defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

development:
  <<: *defaults
  debug: true

production:
  <<: *defaults
  replicas: 5

The <<: merge key inlines all keys from the anchor. The result for development includes timeout, retries, log_level, and debug.

YAML in Docker Compose

version: "3.9"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    environment:
      - NGINX_HOST=example.com
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:

YAML in Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 3000
          resources:
            requests:
              memory: "64Mi"
              cpu: "250m"
            limits:
              memory: "128Mi"
              cpu: "500m"

YAML in GitHub Actions

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

Common YAML Mistakes

Tab Characters

YAML strictly forbids tabs for indentation. Always configure your editor to insert spaces.

The Norway Problem (YAML 1.1 boolean coercion)

In YAML 1.1, country codes like NO, ON, OFF are parsed as booleans. This famously broke configurations using country codes as keys or values.

# YAML 1.1 parses this as boolean false!
country: NO

# Fix: always quote
country: "NO"

YAML 1.2 (2009) fixed this by restricting booleans to only true and false.

Indentation Inconsistency

Mixing 2-space and 4-space indentation, or having incorrect indent levels, causes parse errors that are hard to diagnose.

Special Characters in Unquoted Strings

Characters like :, #, [, ], {, } have special meaning. If your value contains them, use quotes:

# Broken: the : breaks parsing
message: Error: connection refused

# Fixed
message: "Error: connection refused"

Validating YAML

Always validate YAML before deploying. A syntax error in a Kubernetes manifest or CI pipeline wastes time debugging. Use our YAML to JSON converter to validate and explore your YAML, and our YAML Compare tool to diff two YAML files side by side.

Conclusion

YAML's readability makes it the preferred format for configuration, but its implicit type coercion and whitespace sensitivity require care. Follow consistent indentation, quote ambiguous values, and use anchors to reduce repetition in large configurations.