YAML for JSON Developers: A Practical Introduction

If you work with APIs or configuration files, you've likely encountered YAML. Docker Compose, Kubernetes, GitHub Actions, Ansible — all use YAML. This guide gets you productive fast.

YAML vs JSON at a Glance

Feature	JSON	YAML
Comments	❌	✅
Trailing commas	❌	✅
Quotes for strings	Required for special chars	Usually optional
Indentation	Any whitespace	Spaces only (no tabs!)
Type inference	Limited	Automatic

Basic Syntax

Objects

# JSON equivalent: { "name": "Toolblip", "version": "1.0" }
name: Toolblip
version: "1.0"

Arrays / Lists

# JSON: { "tools": ["JSON Formatter", "Base64", "Cron"] }
tools:
  - JSON Formatter
  - Base64
  - Cron

Nested Structures

server:
  host: api.toolblip.com
  port: 443
  ssl: true
  tags:
    - production
    - api

The Pitfalls

1. Tabs Are Forbidden

YAML parsers expect spaces only. If your editor uses tabs, you're going to have a bad time.

# ❌ Tab indentation will fail
name: Toolblip
	version: 1.0

# ✅ Spaces only
name: Toolblip
version: 1.0

2. Type Coercion Can Bite You

YAML auto-converts values to types — sometimes unexpectedly.

# ⚠️ "yes" becomes boolean true
answer: yes         # → true (boolean!)

# ✅ Use quotes for strings
answer: "yes"       # → "yes" (string)

3. The ? Question Mark

Used when you need to specify both day-of-month and day-of-week without conflict (like cron expressions).

Multi-Document Files

One YAML file can contain multiple documents separated by ---:

---
app: frontend
env: production
---
app: backend
env: staging

When to Use YAML vs JSON

Use YAML for:

• Configuration files (Docker, Kubernetes, GitHub Actions)
• Human-edited files where comments add value
• Files that benefit from cleaner, more readable syntax

Use JSON for:

• API request/response bodies
• Data exchange between systems
• Machine-readable files where every byte matters

Convert Between YAML and JSON

👉 YAML ↔ JSON Converter →

Paste YAML → get JSON, or paste JSON → get YAML. Also validates syntax before converting.

Python and JavaScript

# Python
import yaml

with open('config.yaml') as f:
    config = yaml.safe_load(f)  # safe_load prevents code execution

# Always use safe_load with untrusted input
yaml.safe_load(user_input)

// JavaScript
import yaml from 'js-yaml';

const config = yaml.load(fs.readFileSync('config.yaml', 'utf8'));

Key Takeaways

1. Spaces only — no tabs, ever
2. Quotes protect strings from accidental type conversion
3. Comments are free — use them in configuration files
4. Automatic types — yes/no become booleans, 42 becomes a number
5. --- separates documents in multi-document files

YAML is a superpower for configuration. Once you know the gotchas, it's much more readable than JSON for human-edited files.