If you've worked with Docker Compose, GitHub Actions, or Kubernetes, you've already written YAML — even if you didn't think about it much at the time. It's the config format of choice for a huge slice of the modern developer toolchain.

This guide explains what YAML is, how to write it correctly, and how it compares to JSON.

What is YAML?

YAML (pronounced "yamel") stands for YAML Ain't Markup Language. It's a human-readable data serialization format designed for configuration files and data exchange between programs. Like JSON, it represents strings, numbers, lists, and objects — but instead of curly braces and brackets, YAML uses indentation and line breaks to define structure.

The result is a format that's less noisy and easier to write by hand, at the cost of being stricter about whitespace.

YAML Syntax: The Essentials

JSON vs YAML — the same data

// JSON
{
  "name": "Jane Doe",
  "age": 28,
  "skills": ["JavaScript", "Python"],
  "active": true
}
# YAML
name: Jane Doe
age: 28
skills:
  - JavaScript
  - Python
active: true

The YAML version has no quotes on most strings, no commas, and no brackets. It reads more like a document than code.

Data types

  • String: write without quotes in most cases. Use quotes when the value contains :, #, or leading/trailing spaces
  • Number: write directly — age: 28, price: 9.99
  • Boolean: true or false (lowercase)
  • Null: null or leave the value empty
  • List (sequence): each item on its own line, prefixed with -
  • Map (mapping): key: value pairs

Nested structures

user:
  name: Jane Doe
  address:
    city: London
    zip: SW1A 1AA
  roles:
    - admin
    - editor

Indent with spaces (never tabs). Two spaces per level is the convention.

Comments

YAML supports comments with #. JSON doesn't. This alone makes YAML a much better fit for config files that humans maintain:

# Database connection
database:
  host: localhost
  port: 5432  # default PostgreSQL port
  name: myapp

Multi-line strings

# | preserves newlines
description: |
  Line one
  Line two

# > folds newlines into spaces
summary: >
  This is a long sentence
  that wraps across lines

Where YAML is used

  • Docker Compose: docker-compose.yml defines services and networks
  • GitHub Actions: .github/workflows/*.yml defines CI/CD pipelines
  • Kubernetes: all resource definitions (Deployments, Services, etc.) are YAML
  • Ansible: playbooks for infrastructure automation

Frequently Asked Questions

When should I use YAML vs JSON?
YAML is better for config files that humans edit by hand — it's less verbose and supports comments. JSON is better for machine-to-machine data exchange (APIs, serialized data) because it's stricter and more universally supported across programming languages. Many tools accept both; if comments matter, pick YAML.
Why does my YAML break when I use tabs?
YAML explicitly forbids tabs for indentation. The spec requires spaces. This trips up developers who have their editor set to insert a tab character when they press the Tab key. In VS Code, you can enable "Insert Spaces" for YAML files to avoid this. Two spaces per indent level is standard.
"yes" and "on" are being interpreted as true — how do I fix it?
YAML 1.1 (used by many older tools like PyYAML) treats yes, no, on, and off as boolean values. To treat them as strings, wrap them in quotes: "yes". YAML 1.2 removed this behavior, but you may still hit it depending on which library is parsing your file.
Can I convert YAML to JSON?
Yes — YAML is a superset of JSON, so any valid JSON is also valid YAML. Converting between the two is straightforward. If you're passing YAML config to a JSON-only API, or want to validate your YAML structure, a converter tool can handle it instantly.

Summary

  • YAML uses indentation and line breaks instead of brackets and commas
  • It's designed for human-edited config files — especially because it supports comments
  • Always use spaces for indentation (never tabs); two spaces per level is standard
  • Watch out for yes/no/on/off being interpreted as booleans in older parsers

Need to switch between YAML and JSON?