YAML Syntax: Complete Beginner's Guide

Introduction

YAML (YAML Ain't Markup Language) is a human-readable data serialization format commonly used for configuration files. Its clean syntax and support for comments make it ideal for DevOps tools like Docker, Kubernetes, and CI/CD pipelines.

This guide covers essential YAML syntax rules and best practices to help you write error-free configuration files.

Basic Syntax Rules

YAML uses indentation to represent structure:

# Comments start with hash
  name: John Doe
  age: 30
  email: john@example.com

Indentation: Use 2 spaces (never tabs)
Key-value pairs: Separated by colon and space
Case-sensitive: name ≠ Name
Comments: Use # for comments

Data Types

Strings:

# Without quotes (most common)
  title: Hello World

  # With quotes (for special characters)
  message: "Hello: World"

  # Multi-line strings
  description: |
   This is a multi-line string.
    It preserves line breaks.

  folded: >
    This is also multi-line
    but will be folded into
    a single line.

Numbers:

integer: 42
  float: 3.14
  scientific: 1.23e+3
  hex: 0x1A
  octal: 0o14

Booleans:

enabled: true
  disabled: false
  # Also valid:
  alias_yes: yes
  alias_no: no

Null:

empty: null
  also_empty: ~
  omitted:

Collections

Lists (Arrays):

# Block style
  fruits:
    - apple
    - banana
    - orange

  # Flow style (inline)
  colors: [red, green, blue]

  # Nested lists
  matrix:
    - [1, 2, 3]
    - [4, 5, 6]

Maps (Objects):

# Block style
  user:
    name: John
    age: 30
    email: john@example.com

  # Flow style (inline)
  point: {x: 10, y: 20}

  # Nested maps
  company:
    name: TechCorp
    address:
      street: 123 Main St
      city: New York

Complex Example

A complete Docker Compose configuration:

version: '3.8'

  services:
    web:
      image: nginx:latest
      ports:
        - "80:80"
        - "443:443"
      volumes:
        - ./html:/usr/share/nginx/html
      environment:
        - NODE_ENV=production
        - DEBUG=false
      networks:
        - frontend
    
  database:
    image: postgres:14
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend

  networks:
    frontend:
    backend:

  volumes:
    db-data:

Common Mistakes

Using tabs: YAML only accepts spaces
Inconsistent indentation: Must be exactly 2 or 4 spaces
Missing space after colon: name:value is invalid
Quoting issues: Special chars like : need quotes
Boolean confusion: yes/no vs true/false

Best Practices

Use 2-space indentation consistently
Add comments to explain complex configurations
Quote strings with special characters
Use YAML lint tools to validate syntax
Keep nesting levels shallow (max 3-4 levels)
Use meaningful key names
Group related configuration together

Try Our Tools

Explore our free online developer tools:

YAML to JSON JSON to YAML