YAML vs JSON Explained
YAML and JSON both serialize structured data; JSON is stricter and universal for APIs, while YAML favors human-readable config files.
Quick answer
JSON uses braces, brackets, and double-quoted keys for machine-friendly data exchange—especially APIs. YAML uses indentation and minimal punctuation for human-edited config files like Docker Compose and GitHub Actions. YAML is a superset in practice but many YAML files subset to JSON-compatible structures. Convert between them when migrating configs or validating equivalence.
Overview
Developers encounter YAML in Kubernetes manifests, CI workflows, and Ansible playbooks, while JSON dominates REST APIs and browser JavaScript objects. Both represent maps, lists, strings, numbers, and booleans, but ergonomics differ: YAML tolerates comments and multiline strings; JSON forbids comments and requires strict quoting rules that parsers enforce uniformly. Choosing the wrong format creates friction—JSON in hand-edited config lacks comments; YAML in API responses adds parsing complexity without readability wins. Understanding equivalence, pitfalls like YAML's ambiguous boolean yes/no, and safe conversion workflows keeps pipelines reliable when teams standardize on one format or bridge both during migrations.
Syntax and readability differences
JSON objects use `{ "key": "value" }` with double quotes mandatory on keys and strings. Arrays use `[1, 2, 3]`. No comments, no trailing commas in strict parsers.
YAML relies on indentation (spaces, not tabs) to nest maps and lists. Scalars can be unquoted when unambiguous. `# comments` help document config intent inline—major reason YAML wins for ops files edited in Git.
Typical use cases for each format
JSON: HTTP API request/response bodies, package.json, structured logs, NoSQL document storage, JSON Schema validation. Universal JavaScript native support via JSON.parse.
YAML: Kubernetes, Docker Compose, GitHub Actions, CircleCI, Ansible variables, Swagger/OpenAPI sometimes authored in YAML then compiled to JSON. Human review in pull requests benefits from reduced punctuation noise.
YAML-specific pitfalls JSON avoids
YAML 1.1 treated yes/no/on/off as booleans in some parsers—dangerous for strings like country codes. Quote ambiguous scalars. Tabs in indentation break parsers silently or with cryptic line numbers.
Multiline strings and anchors (`&`, `*`) add power but reduce portability to JSON. JSON's strictness is a feature for cross-language API contracts—predictable parsing beats expressive config when machines primarily consume data.
Converting YAML to JSON and back
Round-trip conversion preserves data for JSON-compatible YAML subsets. Comments, anchors, and custom tags may be lost converting YAML→JSON→YAML. Use conversion to inspect YAML as JSON in browser devtools or validate structure with JSON Schema tools.
CI pipelines sometimes lint YAML then emit JSON artifacts for runtime consumption. Store source in YAML for humans, build step outputs JSON for apps—document which file is authoritative.
How to choose for new projects
Default API payloads to JSON unless clients require something else. Choose YAML when non-developers edit config, comments are essential, or ecosystem tooling expects YAML (K8s).
For shared schemas, OpenAPI and JSON Schema bridge both worlds—author in preferred format, generate the other in build. Avoid storing duplicate divergent copies without automation syncing them.
Examples
Same config in both formats
YAML: `server:\n port: 8080\n debug: true` converts to JSON `{"server":{"port":8080,"debug":true}}` for programmatic consumption.
GitHub Actions workflow
Workflow files stay YAML for comment-documented steps; action outputs may serialize matrix values as JSON strings for downstream jobs.
Common mistakes and edge cases
- Using unquoted yes/no in YAML intended as strings.
- Mixing tabs and spaces in YAML indentation.
- Expecting comments to survive YAML→JSON→YAML round trip.
- Sending YAML bodies to APIs expecting application/json Content-Type.
Related resources
Related tools
Last reviewed: 2026-05-23