YAML vs JSON: Choosing the Right Configuration Format

YAML and JSON are both popular formats for configuration files and data exchange. JSON is strict and unambiguous; YAML is human-friendly but has surprising edge cases. This guide compares them head-to-head so you can make an informed choice.

Same Data, Two Formats

Here's the same configuration in JSON and YAML:

// JSON
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "ssl": true
  },
  "database": {
    "url": "postgres://localhost/mydb",
    "pool": 5
  },
  "tags": ["web", "api", "v2"]
}

# YAML
server:
  host: localhost
  port: 8080
  ssl: true

database:
  url: postgres://localhost/mydb
  pool: 5

tags:
  - web
  - api
  - v2

YAML is ~30% shorter and reads more like natural language. But that brevity comes with complexity.

Key Differences

YAML Gotchas

The Norway Problem

YAML's loose type inference is its biggest footgun. Unquoted values are interpreted by the parser as their "natural" type:

# These unquoted values become booleans/null in YAML 1.1
country: NO         # → false  (not the string "NO"!)
flag: yes           # → true
value: null         # → null
nothing: ~          # → null

# Fix: always quote ambiguous strings
country: "NO"
flag: "yes"

YAML 1.2 fixed many of these, but parsers vary. The Norway Problem (NO being parsed as false) famously caused real bugs in configuration systems.

Tabs are forbidden

# This will throw a parse error
server:
	host: localhost  # ← tab character, not spaces!

Multiline strings

# Literal block (preserves newlines)
message: |
  Line one
  Line two

# Folded block (newlines become spaces)
description: >
  This is a long sentence
  that gets folded into one line.

Accidental type coercion

port: 8080         # integer
version: 1.0       # float
api_key: 123456    # integer (not a string!)
zip: 01234         # integer (leading zero gone!)

# Fix
api_key: "123456"
zip: "01234"

YAML is a Superset of JSON

Every valid JSON document is also valid YAML. This means you can often use JSON syntax inside a YAML file, which is useful for machine-generated sections embedded in human-written config.

When to Use Each

Use JSON for: API responses, data serialization, machine-generated config, anything programmatically read and written.

Use YAML for: human-written configuration files (CI/CD pipelines like GitHub Actions, Kubernetes manifests, Docker Compose, Ansible playbooks) where readability and comments matter and humans edit the files directly.

Try It

Use the JSON formatter on io9.me to validate and convert JSON. YAML conversion is also available under the JSON tools.