YAML (YAML Ain’t Markup Language) is a human-readable data format used for configuration files. If you’ve worked with Docker Compose, Kubernetes, GitHub Actions, or almost any CI/CD tool, you’ve written YAML.

It’s designed to be easy to read and write — no curly braces, no quotes required for most strings, and indentation defines structure (like Python).

Basic syntax

# Strings (quotes optional for simple values)
name: Alice
title: "Senior Developer"

# Numbers and booleans
age: 30
active: true
salary: 95000.50

# Lists
languages:
  - JavaScript
  - Python
  - Go

# Nested objects
address:
  street: 123 Main St
  city: Brussels
  country: Belgium

# Inline list and object
tags: [docker, kubernetes, devops]
config: { debug: true, port: 3000 }

YAML vs JSON

YAML and JSON represent the same data structures. In fact, valid JSON is valid YAML. The difference is readability:

{
  "services": {
    "app": {
      "image": "node:20",
      "ports": ["3000:3000"],
      "environment": {
        "NODE_ENV": "production"
      }
    }
  }
}

The same thing in YAML:

services:
  app:
    image: node:20
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production

YAML is more readable for configuration. JSON is better for data exchange between systems (APIs, databases) because it’s unambiguous and faster to parse.

Convert between them with our JSON to YAML converter.

Common gotchas

Indentation must be spaces, not tabs. YAML doesn’t allow tabs. Use 2 spaces per level (the convention).

Strings that look like other types need quotes:

# ❌ These are interpreted as booleans/numbers
version: 3.10    # becomes 3.1 (float)
country: NO      # becomes false (boolean)
zip: 01onal      # becomes 1 (octal number)

# ✅ Quote them
version: "3.10"
country: "NO"
zip: "01onal"

Multi-line strings:

# Literal block (preserves newlines)
description: |
  This is line one.
  This is line two.

# Folded block (joins lines with spaces)
description: >
  This is a long paragraph
  that wraps across multiple
  lines but becomes one line.

Where you’ll encounter YAML

• Docker Compose — docker-compose.yml defines your container stack
• Kubernetes — all resource definitions (pods, services, deployments)
• GitHub Actions — .github/workflows/*.yml for CI/CD
• Ansible — infrastructure automation playbooks
• Helm — Kubernetes package manager charts
• CloudFormation / Terraform — infrastructure as code
• ESLint, Prettier — .eslintrc.yml, .prettierrc.yml

Basically, if a tool needs a config file and JSON feels too verbose, it probably uses YAML.

Validating YAML

YAML’s indentation sensitivity means a single misplaced space can break your config. Use a linter:

# Install yamllint
pip install yamllint

# Check a file
yamllint docker-compose.yml

Or paste your YAML into our Docker Compose validator to check for issues.

Learn more

• JSON to YAML converter — convert between formats
• Docker complete guide — YAML-heavy Docker workflows
• Kubernetes complete guide — YAML for container orchestration
• What is GitHub Actions? — YAML-based CI/CD

Related: What Is Webassembly