JSON vs YAML for config
Published: 2026-05-16
When YAML shines for human-edited config, when JSON is the safer default, and how to convert between them locally in your browser.
JSON and YAML both describe trees of data: objects (maps), arrays, strings, numbers, booleans, and null. The difference is mostly syntax and culture: YAML optimizes for people writing files by hand; JSON optimizes for machines and strict interchange.
YAML: readable, expressive, easy to mistype
YAML uses indentation for nesting, allows comments (# …), and often lets you omit quotes on simple keys and values. That makes long service configs, CI pipelines, and Helm-style values easier to scan than brace-heavy JSON.
YAML also has advanced features (anchors, aliases, custom tags) that some parsers enable and others ignore. Whitespace and colons matter: a misplaced space after a colon can change a string into something else. For large files, a small indentation slip can produce a valid parse that does not match what you meant—so reviews and schema checks help.
Common homes for YAML: docker-compose.yml, many GitHub Actions snippets, Kubernetes manifests (often authored as YAML), Ansible playbooks, static-site generators.
JSON: strict, boring, everywhere
JSON has explicit delimiters ({}, [], ,), double-quoted strings only, and no comments. That rigidity reduces ambiguity: two compliant parsers usually agree on the same structure.
Common homes for JSON: package.json, tsconfig.json, REST and GraphQL responses, CLI --json output, browser fetch bodies, and anything that must round-trip through JavaScript without extra dependencies.
Choosing for “config” specifically
| Concern | Lean YAML | Lean JSON |
|---|---|---|
| Human authors need comments | Yes | No native comments (use _comment keys or external docs) |
| Many tools already expect one format | Match the ecosystem (e.g. K8s YAML) | Match the ecosystem (e.g. Node package metadata) |
| Machine-generated or API-adjacent | Either works; JSON is the default on the wire | Strong default |
| Merge conflicts in Git | Neither is magic; smaller, flatter files help both | Often slightly noisier diffs |
| “Just tell me if this file is valid” | Validate against a schema or parser | Same; JSON errors are often very local |
If your file is hand-edited and commented, YAML is a natural fit—provided your team agrees on indentation and reviews changes. If the file is generated, consumed by browsers, or must match an API, JSON keeps surprises down.
Convert and format without uploads
To flip between JSON and YAML and compare shapes side by side, use the JSON ↔ YAML converter. To format or validate JSON on its own, use the JSON Formatter & Validator. On LocalTools, pasted content stays in your browser.
Related reading
- What is JSON? — syntax basics and why APIs love JSON.
- What is JSONPath? — query language basics, then the JSONPath evaluator for nested JSON (and YAML converted to JSON) once you know the tree shape you need.