JSON vs YAML: Differences, When to Use Each

Side-by-side comparison

The same data in both formats:

# YAML
server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - https://example.com
    - https://staging.example.com
  database:
    url: postgres://localhost/mydb
    pool_size: 10

// JSON
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": [
      "https://example.com",
      "https://staging.example.com"
    ],
    "database": {
      "url": "postgres://localhost/mydb",
      "pool_size": 10
    }
  }
}

Key syntax differences

Comments

YAML supports comments with #. JSON does not. This is the most common reason developers prefer YAML for configuration files.

# YAML — comments work fine
database:
  pool_size: 10   # increase to 20 under heavy load

// JSON — no comments. Workarounds like "_comment" keys are hacks.
{ "pool_size": 10 }

Strings

JSON requires double quotes on all strings. YAML allows bare strings — but some bare values get parsed as booleans or numbers, which causes subtle bugs.

# YAML 1.1 — dangerous bare values
version: 1.0    # number, not string
enabled: yes    # boolean true
country: NO     # boolean false — "The Norway Problem"

# Safe: always quote strings that could be misread
country: "NO"
version: "1.0"

Multiline strings

YAML has native multiline support. JSON requires manual \n escaping.

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

// JSON
{ "message": "Line one
Line two" }

Null and booleans

# YAML — multiple valid forms
null_value: null
null_value: ~

boolean: true
boolean: false

// JSON — only one valid form each
{ "null_value": null, "boolean": true }

When to use JSON

• APIs and HTTP responses — JSON is the universal language of REST APIs. Every HTTP client and server supports it natively.
• Data interchange between systems — JSON's strictness prevents ambiguity. There's no "Norway problem" in JSON.
• package.json, tsconfig.json, manifest files — The npm, TypeScript, and VS Code ecosystems standardize on JSON.
• When you need a formal spec — JSON has one canonical RFC. YAML has multiple incompatible versions (1.1 vs 1.2).

When to use YAML

• CI/CD pipelines — GitHub Actions, GitLab CI, CircleCI all use YAML. Comments let you explain complex workflow logic.
• Kubernetes manifests — The entire Kubernetes ecosystem is YAML-based.
• Application config files — Docker Compose, Ansible, Helm charts use YAML. Comments and multiline strings are genuinely useful.
• Human-edited files — When non-developers need to edit a config, YAML's lack of braces and quotes is less intimidating.

YAML gotchas

• The Norway problem — NO, yes, on, off are all booleans in YAML 1.1. Always quote strings that could be misread.
• Indentation is structure — Unlike JSON, whitespace defines nesting. One wrong indent breaks the file. Tabs are not allowed.
• Document separators — --- starts a new YAML document. A Kubernetes file with multiple --- separators is multiple YAML documents in one file.
• Anchors and aliases — YAML supports reusable blocks (&anchor / *alias). Useful but adds complexity JSON doesn't have.

Converting between JSON and YAML

JSON is a valid subset of YAML 1.2 — every valid JSON file is also valid YAML. Converting from JSON to YAML is always safe. Converting YAML to JSON may fail if the YAML uses features JSON doesn't support (comments are lost, anchors must be resolved, multiline strings collapse).