YAML Explained: How It Works and When to Use It

YAML is one of the most widely used configuration languages in modern development. You’ll find it in Docker Compose files, Kubernetes manifests, GitHub Actions workflows, static site generators, and countless other tools.

Its main strengths are readability, simplicity, and being human-friendly—but YAML also has strict rules that can trip developers up.

In this guide, you’ll learn:

1. What YAML is and why it exists
2. YAML syntax basics
3. How YAML compares to JSON
4. How to convert JSON ↔ YAML
5. Common mistakes and how to avoid them

---

What is YAML?

YAML stands for YAML Ain’t Markup Language, a recursive acronym emphasizing that YAML is not meant for markup, but for data serialization.

It is designed to be:

• Human-readable
• Easy to write and modify
• Flexible for configuration files
• Structured without excessive symbols

You’ll often encounter YAML in:

• Kubernetes (deployment.yaml)
• Docker Compose (docker-compose.yml)
• GitHub Actions (ci.yml)
• Home Assistant
• Ansible

---

YAML Syntax Basics

YAML uses indentation to represent structure.
Indentation matters (spaces, not tabs!), and incorrect spacing is the #1 source of errors.

Key rules:

• Use spaces, never tabs
• Indentation defines hierarchy
• Key-value pairs use key: value
• Lists start with -

Example YAML

name: John Doe
age: 30
isDeveloper: true
languages:
  - JavaScript
  - Python
  - Rust
address:
  street: "123 Main St"
  city: "New York"

---

YAML vs JSON

You can think of YAML as a more human-friendly JSON.

JSON

{
  "name": "John",
  "age": 30
}

YAML

name: John
age: 30

JSON is stricter and predictable for machines.
YAML is more flexible and pleasant for humans.

---

Convert JSON ↔ YAML Instantly

Use this tool for:

• Kubernetes manifests
• CI/CD workflows
• Docker Compose files
• GitHub Actions

---

Common YAML Mistakes

1. Using tabs instead of spaces

YAML does not allow tabs.

2. Misaligned indentation

Consistent indentation is required for nested structures.

3. Forgetting quotation marks

Strings with special characters require quotes.

4. Accidental nesting

A single extra space may create a child node unintentionally.

5. Boolean formatting inconsistencies

YAML accepts yes/no, on/off, true/false. JSON does not.

---