What is YAML?

YAML (YAML Ain’t Markup Language) is a human-readable data serialization format that uses indentation to represent structure, commonly used for configuration files and data exchange. It’s a superset of JSON — any valid JSON document is also valid YAML.

Syntax basics

YAML uses whitespace indentation (spaces, never tabs) to denote nesting. Key-value pairs use a colon and space. Lists use dashes.

server:
  host: localhost
  port: 8080
  features:
    - logging
    - compression
  tls: true

Strings don’t require quotes unless they contain special characters. Multi-line strings use | (preserves newlines) or > (folds into a single line).

Why developers use YAML

YAML is the de facto format for DevOps and infrastructure configuration. Docker Compose files, Kubernetes manifests, GitHub Actions workflows, Ansible playbooks, CI/CD pipelines — all YAML. It won this space because it’s more readable than JSON for deeply nested structures and supports comments (JSON doesn’t).

# Deploy to production
name: deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest

The ability to add comments inline is a major advantage for configuration files that need explanation.

YAML vs. JSON

JSON is better for data interchange (APIs, storage). YAML is better for human-authored configuration. JSON is unambiguous and fast to parse. YAML’s flexibility introduces edge cases — for example, yes, no, on, off are parsed as booleans in YAML 1.1, which has caused bugs in countless projects (the infamous “Norway problem” where the country code NO becomes false).

YAML 1.2 fixed many of these quirks, but not all parsers implement 1.2.

Common pitfalls

• Indentation errors: YAML is whitespace-sensitive. Mixing tabs and spaces or inconsistent indentation breaks parsing.
• Implicit typing: Unquoted 3.10 becomes the float 3.1, not the string "3.10". This has bitten many Python version specifications.
• Complex syntax: Anchors (&), aliases (*), and merge keys (<<) add power but also confusion.

Format YAML with the YAML Formatter, validate syntax with the YAML Validator, or convert between formats with JSON to YAML and YAML to JSON.