What is YAML? A Practical Guide

The short answer

YAML(YAML Ain't Markup Language) is a human-friendly data serialization format. It is designed to be easy for humans to read and write, making it popular for configuration files, infrastructure definitions, and data exchange between tools.

You have probably seen YAML in Docker Compose files, GitHub Actions workflows, Kubernetes manifests, and many CI/CD configuration files.

YAML vs JSON — same data, different format

{
  "name": "Ana",
  "age": 28,
  "skills": [
    "Python",
    "Docker"
  ],
  "active": true
}

name: Ana
age: 28
skills:
  - Python
  - Docker
active: true

YAML is more compact and readable — no quotes on keys, no curly braces, no commas.

YAML syntax basics

name: Ana García
age: 28
city: Madrid

fruits:
  - apple
  - banana
  - orange

# Inline list
colors: [red, green, blue]

address:
  street: Calle Mayor
  city: Madrid
  country: Spain

# Preserve newlines with |
description: |
  This is line one.
  This is line two.

# Fold newlines into spaces with >
summary: >
  This long text will be
  joined into one line.

# This is a comment — unlike JSON, YAML supports them!
name: Ana  # inline comment

Data types in YAML

string: Hello World
quoted: "Hello World"    # same result
integer: 42
float: 3.14
boolean_true: true
boolean_false: false
null_value: null
date: 2024-01-15         # parsed as a date by some parsers

Be careful with booleans — YAML 1.1 (used by many older tools) treats yes/no, on/off, and true/false as booleans. YAML 1.2 only accepts true/false. Quote values like "yes" if you want a string.

YAML vs JSON — when to use which

Common YAML mistakes

• Tabs instead of spaces — YAML does not allow tabs for indentation, only spaces
• Inconsistent indentation — the indentation level must be consistent within a block
• Unquoted special values — values like yes, no, null are parsed as booleans/null unless quoted
• Colons in values — if a value contains a colon, quote it: "http://example.com"