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

Free YAML to JSON Converter — convert between YAML and JSON instantly
Free JSON Formatter — format and validate the converted JSON output

Written by Achraf A., founder of TheFreeAITools.

What Is YAML and How Do You Use It? A Practical Guide