Why Use YAML Over JSON?

The short answer

Use YAML when a human writes and maintains the file. Use JSON when a machine produces and consumes it. Almost every real argument about YAML vs JSON dissolves once you ask who the audience is.

Concretely: YAML wins for Kubernetes manifests, Docker Compose files, CI pipelines, and app settings. JSON wins for API payloads, browser storage, and anything a parser reads a million times a day.

1. YAML has comments. JSON does not.

This is the single most common reason teams move config from JSON to YAML. The JSON spec has no comment syntax, so you cannot explain why a value is what it is.

# Raised from 30s after the 2024 timeout incident
timeout: 60
retries: 3   # keep in sync with the gateway

In JSON, the usual workaround is a fake key such as "_comment", which pollutes the data and is silently passed to your application. Supersets like JSON5 and JSONC add comments back, but then you are no longer using portable JSON.

2. Multi-line strings stay readable

Embedding a script, certificate, or SQL query in JSON means escaping every newline into \n, producing one unreadable line. YAML has block scalars:

startup: |
  #!/bin/sh
  echo "migrating"
  ./manage.py migrate
description: >
  This folds onto a single line
  when parsed, but stays readable here.

The | keeps newlines; > folds them into spaces. The JSON equivalent is "#!/bin/sh\necho \"migrating\"\n./manage.py migrate\n".

3. Anchors let you reuse blocks

JSON has no way to say "same as above". YAML has anchors (&), aliases (*), and merge keys (<<):

defaults: &defaults
  adapter: postgres
  pool: 5

development:
  <<: *defaults
  database: app_dev

test:
  <<: *defaults
  database: app_test

In JSON you would copy the shared block into every environment and then keep the copies in sync by hand.

4. Several documents in one file

YAML separates documents with ---, which is why a single Kubernetes file can hold a Deployment and a Service together:

apiVersion: v1
kind: Service
metadata:
  name: web
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web

JSON has exactly one root value per file, so the same content needs either an artificial wrapper array or separate files.

5. Diffs and code review are cleaner

Because YAML has no closing brackets and no trailing commas, changing one setting produces a one-line diff. JSON edits often touch neighbouring lines just to add or remove a comma, which makes review noisier than it needs to be.

When JSON is still the right choice

• APIs and data exchange — every language parses JSON natively and fast.
• Machine-generated output — nobody reads it, so readability buys nothing.
• Strictness matters — JSON has fewer ambiguous cases; YAML's type coercion can turn no into false and 1.0 into a float.
• Whitespace risk is unacceptable — YAML breaks on bad indentation, and a misplaced space can silently change nesting.

If indentation is your main worry, see the YAML indentation guide for the rules and the errors they cause.

The practical answer: use both

Most teams author config in YAML and convert to JSON at the boundary where a tool demands it. That is a one-step conversion, not a commitment:

• YAML to JSON converter — feed a JSON-only tool.
• JSON to YAML converter — turn an exported JSON blob into an editable config.
• YAML validator — catch syntax errors with line numbers before you commit.

All of them run entirely in your browser: nothing is uploaded, so you can paste production config safely.

FAQ

Keep reading

• YAML vs JSON — the side-by-side comparison.
• YAML vs JSON vs XML — adding a third format.
• What is YAML? — syntax basics from scratch.
• How to convert YAML to JSON — step by step.