What YAML stands for

YAML stands for "YAML Ain't Markup Language" — a recursive acronym. It's a human-readable data serialization format designed to be easy to write and read, especially for configuration files.

YAML is a superset of JSON — every valid JSON document is also valid YAML. But YAML's primary purpose is human-written configuration, where readability matters more than compactness.

Basic YAML syntax

YAML represents data as key-value pairs with indentation showing structure. Critical rule: use spaces, not tabs. Tabs are illegal in YAML and will cause a parse error.

# This is a comment
name: John Doe
age: 30
email: john@example.com
active: true
score: 9.5

Equivalent JSON:

{
"name": "John Doe",
"age": 30,
"email": "john@example.com",
"active": true,
"score": 9.5
}

Lists (sequences)

# Block sequence (most readable)
fruits:
  - apple
  - banana
  - cherry

# Flow sequence (inline, like JSON)
colors: [red, green, blue]

Nested objects (mappings)

user:
  id: 42
  name: Jane Doe
  address:
  street: 123 Main St
  city: Springfield
  country: US

Multi-line strings

YAML has two ways to write multi-line strings:

# Literal block (|) — preserves newlines
description: |
  This is the first line.
  This is the second line.
  Newlines are preserved.

# Folded block (>) — newlines become spaces
summary: >
  This long text will be
  folded into a single line
  with spaces between parts.

Real-world examples

Docker Compose

version: "3.8"
services:
  web:
  image: nginx:latest
  ports:
  - "80:80"
  volumes:
  - ./html:/usr/share/nginx/html
  db:
  image: postgres:15
  environment:
  POSTGRES_PASSWORD: secret
  POSTGRES_DB: myapp

GitHub Actions workflow

name: CI
on:
  push:
  branches: [main]
  pull_request:
  branches: [main]

jobs:
  test:
  runs-on: ubuntu-latest
  steps:
  - uses: actions/checkout@v4
  - name: Install dependencies
    run: npm install
  - name: Run tests
    run: npm test

Common YAML pitfalls

1. Tabs vs spaces (the #1 error)

# WRONG — tab character at the start
	name: John # TAB — will throw ParseError

# RIGHT — spaces only
  name: John # 2 spaces

2. Strings that look like other types

version: 3.8  # Parsed as float: 3.8
version: "3.8"  # Stays a string: "3.8" ← correct for Docker

enabled: yes  # Parsed as boolean: true (YAML 1.1)
enabled: "yes"  # Stays string: "yes"

country_code: NO  # Parsed as boolean: false (NO = Norway, also false!)
country_code: "NO"  # Correct — stays string

In YAML 1.1 (used by many tools), yes, no, on, off, true, false are all booleans. Wrap strings in quotes when the value might be misinterpreted.

3. Colon in values

# WRONG — colon without quotes
url: https://example.com # Parse error

# RIGHT
url: "https://example.com"
# OR
url: 'https://example.com'

4. Indentation inconsistency

# WRONG — mixing 2-space and 4-space indentation
user:
  name: John
  email: john@example.com # 4 spaces — wrong level

# RIGHT — consistent 2-space indentation
user:
  name: John
  email: john@example.com

Converting between YAML and JSON

Since YAML is a superset of JSON, conversion between them is lossless (with minor caveats around comments and anchors). The free YAML to JSON converter handles both directions — paste YAML and get JSON, or paste JSON and get clean YAML.

Useful when:

  • An API expects JSON but your config is in YAML
  • You want to validate YAML structure by converting to JSON and using a JSON formatter
  • Migrating configuration files between systems that expect different formats

Related tools

Written by Achraf A., founder of TheFreeAITools.