YAML for Configuration Files: Complete Guide

What is YAML?

YAML (YAML Ain't Markup Language) is a human-readable data serialization format commonly used for configuration files. It emphasizes readability and simplicity, making it ideal for config files in applications like Docker, Kubernetes, CI/CD pipelines, and more.

Basic YAML Syntax

Key-Value Pairs

name: John Doe
age: 30
email: john@example.com

Lists/Arrays

colors:
  - red
  - green
  - blue

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

Nested Objects

person:
  name: John Doe
  age: 30
  address:
    street: 123 Main St
    city: New York
    country: USA

Multiline Strings

# Preserve newlines (|)
description: |
  This is a multiline string.
  Each line break is preserved.
  Great for long text.

# Fold newlines (>)
summary: >
  This is also multiline
  but newlines are replaced
  with spaces.

Common Use Cases

Docker Compose

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: example

GitHub Actions CI/CD

name: Deploy
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build
        run: npm run build
      - name: Deploy
        run: npm run deploy

Kubernetes Config

apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

Best Practices

✓

Use Consistent Indentation: Always use 2 spaces (never tabs). YAML is whitespace-sensitive.

✓

Quote Strings When Needed: Use quotes for strings with special characters, colons, or leading/trailing spaces.

✓

Add Comments: Use # for comments to document complex configs.

✓

Validate Before Deploying: Use YAML validators to catch syntax errors early.

✓

Use Anchors for Reusability: Define common values once and reference them with & and *.

✗

Avoid Complex Nesting: Keep configs flat when possible for better readability.

✗

Don't Mix Tabs and Spaces: This will break your YAML file.

Advanced Features

Anchors and Aliases

Reuse common values across your YAML file:

defaults: &defaults
  adapter: postgres
  host: localhost

development:
  <<: *defaults
  database: dev_db

production:
  <<: *defaults
  database: prod_db
  host: db.example.com

Data Types

# String
name: "John Doe"

# Number
age: 30
price: 19.99

# Boolean
enabled: true
disabled: false

# Null
middle_name: null
# or
middle_name: ~

# Date
date: 2025-11-02

Common Pitfalls

⚠️ Boolean Values

Words like "yes", "no", "on", "off" are interpreted as booleans:

# This becomes boolean true, not string "yes"
answer: yes

# Quote it to keep as string
answer: "yes"

⚠️ Colon in Strings

Colons can cause parsing errors:

# Wrong - will cause error
title: Time: 5:30 PM

# Correct - quote the string
title: "Time: 5:30 PM"

⚠️ Indentation Errors

YAML is indentation-sensitive. Inconsistent indentation will break parsing.

Convert YAML to JSON

Need to convert between YAML and JSON? Our free converter makes it easy:

YAML ↔ JSON Converter →

Need advanced YAML validation? Check out YAML Validator Pro for schema validation and linting.