YAML

Basic Syntax

# Key-value pairs (colon + space required)
name: John Doe
age: 30
city: New York

# Nested objects (indentation matters - use spaces, not tabs)
person:
  name: John Doe
  age: 30
  address:
    street: 123 Main St
    city: New York

Data Types

# Strings (quotes optional for simple strings)
string1: Hello World
string2: "Hello World"
string3: 'Hello World'

# Numbers
integer: 42
float: 3.14
exponential: 1.23e+3

# Booleans
enabled: true
disabled: false
yes_value: yes      # Also boolean true
no_value: no        # Also boolean false

# Null values
empty: null
tilde: ~            # Also null
no_value:           # Also null (no value after colon)

Comments

# This is a comment
name: John  # Inline comment

# Multi-line comment:
# Line 1
# Line 2
# Line 3

Lists (Arrays)

# Block style (recommended)
fruits:
  - apple
  - banana
  - orange

# Flow style (inline)
numbers: [1, 2, 3, 4, 5]

# List of objects
users:
  - name: Alice
    age: 25
  - name: Bob
    age: 30

Multi-line Strings

# Literal block (preserves newlines, indicated by |)
description: |
  This is a multi-line string.
  Line breaks are preserved.
  Useful for long text.

# Folded block (converts newlines to spaces, indicated by >)
summary: >
  This text will be folded
  into a single line with
  spaces between words.

# With indentation control
code: |2
    def hello():
        print("Hello")  # Keeps 2-space indent

Anchors and Aliases

# Define anchor with &
defaults: &default_settings
  timeout: 30
  retry: 3
  debug: false

# Reference anchor with *
development:
  <<: *default_settings  # Merge all default settings
  debug: true            # Override specific value

production:
  <<: *default_settings
  timeout: 60           # Override timeout

Complex Structures

# Mixed nested data
application:
  name: MyApp
  version: 1.0.0
  
  database:
    host: localhost
    port: 5432
    credentials:
      username: admin
      password: secret
  
  features:
    - authentication
    - logging
    - caching
  
  settings:
    debug: false
    max_connections: 100
    allowed_hosts:
      - example.com
      - api.example.com

Common Use Cases

Docker Compose

version: '3.8'

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    environment:
      - NGINX_HOST=example.com
  
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

GitHub Actions

name: CI Pipeline

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

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test

Application Config

app:
  name: MyApplication
  version: 2.1.0
  
server:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: true
    cert: /path/to/cert.pem
    key: /path/to/key.pem

logging:
  level: info
  format: json
  outputs:
    - console
    - file

database:
  type: postgres
  connection:
    host: db.example.com
    port: 5432
    database: myapp
    pool_size: 20

Special Characters

# Strings containing special characters need quotes
special: "key: value"
colon: "text with : colon"
hash: "text with # hash"

# Escaping quotes
single: 'It''s escaped'
double: "He said \"hello\""

# Multiple documents in one file (separated by ---)
---
document: first
---
document: second

Best Practices

# ✅ Use consistent indentation (2 spaces recommended)
good:
  nested:
    value: 123

# ✅ Quote strings with special characters or leading/trailing spaces
path: "/usr/local/bin"
name: " padded "

# ✅ Use explicit types when ambiguous
version: "1.20"      # String, not float
enabled: "true"      # String, not boolean

# ✅ Use lists for ordered data
steps:
  - compile
  - test
  - deploy

# ✅ Use objects for key-value mappings
settings:
  timeout: 30
  retry: 3