JSON vs YAML: Key Differences and When to Use Each Format

At a Glance: JSON vs YAML

JSON in Practice

JSON (JavaScript Object Notation) was created by Douglas Crockford and is standardized as ECMA-404 and RFC 8259. It is deliberately minimal: six value types, strict quoting rules, no comments, no trailing commas. That strictness is a feature — JSON is trivial to parse reliably.

{
  "service": "api-gateway",
  "port": 8080,
  "tls": true,
  "allowedOrigins": ["https://app.example.com", "https://admin.example.com"],
  "database": {
    "host": "db.internal",
    "port": 5432,
    "name": "production"
  }
}

Every key must be a double-quoted string. Values can be strings, numbers, booleans (true/false), null, arrays, or nested objects. Nothing else.

YAML in Practice

YAML (YAML Ain't Markup Language) prioritizes human readability. It uses indentation for structure, makes quotes optional for most strings, and supports comments. The same config as above in YAML:

# API Gateway configuration
service: api-gateway
port: 8080
tls: true
allowedOrigins:
  - https://app.example.com
  - https://admin.example.com
database:
  host: db.internal
  port: 5432
  name: production

Notice: no braces, no quotes around simple strings, no commas, and you can add explanatory comments. YAML is considerably easier to read and edit by hand.

Important Syntax Differences

1. Multiline strings

Embedding multiline text in JSON requires escape sequences (\n). YAML handles it natively with block scalar operators:

# YAML literal block (preserves newlines)
script: |
  #!/bin/bash
  echo "Building..."
  npm install && npm run build

# YAML folded block (newlines become spaces)
description: >
  This is a long description that wraps
  across multiple lines in the source file.

2. Anchors and aliases (YAML only)

YAML's killer feature for config files: define a value once and reuse it with &anchor and *alias:

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults   # Merge the defaults anchor
  endpoint: https://api.prod.example.com

staging:
  <<: *defaults
  endpoint: https://api.staging.example.com

3. Implicit type coercion (YAML gotchas)

YAML infers types from unquoted values. This causes surprising behavior:

• NO (ISO country code for Norway) parses as boolean false in YAML 1.1 — the infamous "Norway Problem"
• 1.0 is a float, 1 is an int — type matters for equality checks
• 0777 parses as octal 511 in some YAML 1.1 parsers
• Tabs are never valid indentation in YAML — only spaces

Fix: quote values that should always be strings: country: "NO".

When to Choose JSON vs YAML