YAML Syntax Guide: A Practical Reference for Developers

What is YAML?

YAML (YAML Ain't Markup Language) is a human-friendly data serialization format. It uses indentation to define structure rather than braces, brackets, or tags. That makes it the preferred choice for configuration files in tools like Kubernetes, Docker Compose, GitHub Actions, and Ansible.

If you have ever written a .yml file, you already know the basics. This guide covers everything from fundamentals to advanced features — and the pitfalls that trip up even experienced developers.

Basic Structure

Key-Value Pairs

The building block of YAML is the key-value pair:

name: Alice
age: 30
active: true

Keys are separated from values by a colon followed by a space. The space is mandatory — name:Alice is invalid.

Lists

Use a hyphen and space to create a list:

skills:
  - Python
  - JavaScript
  - Go

Lists can also appear inline:

skills: [Python, JavaScript, Go]

Nested Dictionaries

Indentation creates nested structures. Use consistent spaces (2 is the convention) — never tabs:

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

Data Types

YAML infers types automatically based on how values are written:

Watch out: Unquoted values like on, off, yes, no, y, n are parsed as booleans in YAML 1.1. Always quote strings that could be misinterpreted:

# YAML 1.1 treats these as booleans!
feature_flag: "on"      # String (quoted)
auto_save: "no"         # String (quoted)
answer: "yes"           # String (quoted)

Multiline Strings

YAML gives you two operators for multiline content — and choosing the wrong one changes your output.

Literal Block (|)

Preserves newlines exactly as written:

message: |
  Line one
  Line two
  Line three

Result: "Line one\nLine two\nLine three\n" — note the trailing newline.

Folded Block (>)

Converts newlines to spaces (paragraph style):

message: >
  This is a long paragraph
  that wraps across multiple
  lines in the YAML file.

Result: "This is a long paragraph that wraps across multiple lines in the YAML file.\n"

Quick Reference

Anchors and Aliases

Anchors (&name) define a reusable fragment. Aliases (*name) reference it. The merge key (<<) injects an anchor's content into a mapping:

default_config: &default
  timeout: 30
  retries: 3
  verbose: false

# Merge defaults and override specific values
development:
  <<: *default
  verbose: true

production:
  <<: *default
  timeout: 60
  retries: 10

Key points:

• Anchors work within a single file only.
• You can override merged values by listing them after the merge key.
• Aliases cannot create circular references.
• When converting YAML to JSON, all anchors expand inline — the deduplication is lost.

Explicit Type Tags

YAML lets you force a specific type with !! tags:

count: !!int "42"          # Integer 42
price: !!float "9.99"      # Float 9.99
flag: !!bool "yes"         # Boolean true
label: !!str 123           # String "123"
empty: !!null ""           # null
timestamp: !!timestamp "2026-01-15"

Use type tags when the inferred type is wrong or ambiguous. They are especially helpful for values that YAML might misparse.

Common Pitfalls

1. Indentation Errors

YAML is picky about indentation. Mixing spaces and tabs, or using inconsistent depths, causes parse errors:

# WRONG — mixed indentation
server:
  port: 3000
    host: localhost    # Tab here — parser error!

# RIGHT — consistent 2-space indentation
server:
  port: 3000
  host: localhost

Rule: Configure your editor to convert tabs to spaces. Set the indent size to 2.

2. Unquoted Special Characters

Strings containing :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, or ` must be quoted:

# WRONG — colon causes parsing issues
url: http://example.com:8080

# RIGHT
url: "http://example.com:8080"

3. Tabs Instead of Spaces

YAML forbids tabs for indentation. A single tab anywhere in the indentation will produce a cryptic parse error. Configure your editor to use spaces.

4. Boolean Coercion Pitfalls

In YAML 1.1, many values are booleans:

YAML 1.2 (the latest spec) only recognizes true and false as booleans. But many parsers still use YAML 1.1 by default. Always quote ambiguous values.

Practical Examples

Docker Compose

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html
    restart: unless-stopped

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

volumes:
  pgdata:

GitHub Actions

name: CI Pipeline
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

Kubernetes Manifest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: myapp:1.0.0
          ports:
            - containerPort: 3000

Key Takeaways

• Use consistent 2-space indentation — never tabs.
• Quote strings containing colons, special characters, or boolean-like values.
• Use | to preserve newlines, > to fold them into spaces.
• Anchors (&) and aliases (*) reduce repetition in large configs.
• Beware YAML 1.1 boolean coercion — yes, no, on, off are not strings.
• Always validate your YAML files before deploying.

Try It Yourself

Want to validate or convert your YAML? Try this tool:

• JSON to YAML Converter — Convert between JSON and YAML formats instantly

Related Guides

• JSON vs YAML — Compare both formats side by side with a decision tree
• Configuration File Formats — Compare JSON, YAML, TOML, and INI for your next project