JSON vs YAML: Differences and When to Use Each
JSON and YAML can describe exactly the same data: objects, lists, strings, numbers, booleans and null. JSON is the language of APIs. YAML is the language of configuration files: Docker Compose, Kubernetes, GitHub Actions and many more. Here is how they differ and when to choose each.
The same data in both formats
{
"name": "api",
"version": 2,
"env": ["dev", "prod"],
"db": { "host": "localhost", "port": 5432 }
}name: api
version: 2
env:
- dev
- prod
db:
host: localhost
port: 5432YAML uses indentation instead of braces and brackets, and quotes are usually optional.
Side-by-side comparison
| JSON | YAML | |
|---|---|---|
| Structure | Braces and brackets | Indentation (spaces only, no tabs) |
| Comments | Not allowed | # like this |
| Quotes | Required for keys and strings | Usually optional |
| Multi-line text | Escaped \n | Block styles | and > |
| Reuse a value | No | Anchors and aliases (&base, *base) |
| Several documents in one file | No | Yes, separated by --- |
| Parsing speed and safety | Simple, fast, built into every language | More complex; use a safe loader for untrusted input |
| Best for | APIs, data exchange, machine-written files | Human-edited configuration |
YAML pitfalls to know
1. Unquoted values are guessed
YAML guesses the type of unquoted values, and the guess is sometimes wrong:
version: 3.10 # becomes the number 3.1, not "3.10"
zip: 01234 # may become a number and lose the zero
country: NO # YAML 1.1 parsers read this as false (the "Norway problem")
time: 12:30 # YAML 1.1 can read this as a number of minutesThe "Norway problem" comes from the older YAML 1.1 rules, where yes, no, on and off are booleans. YAML 1.2 fixed this, but many tools still use 1.1 rules. When in doubt, quote it: country: "NO".
2. Indentation errors are silent
A wrong indent does not always cause an error. Sometimes it just moves a key to a different parent, and the config means something else. Use an editor that shows indentation guides, and never use tabs.
3. JSON is (almost) valid YAML
YAML 1.2 is designed as a superset of JSON, so most JSON files can be read by a YAML parser as they are. This is handy: you can paste JSON into a YAML config when you're in a hurry.
When to use which
- Use JSON for API requests and responses, data stored or exchanged between programs, and anything generated by code. It is strict, so errors show up early.
- Use YAML for configuration that people edit by hand, especially when comments help explain settings.
- Use whatever your tool expects: Kubernetes, Docker Compose and GitHub Actions use YAML, and
package.jsonis JSON.
.json files break standard parsers. See common JSON errors.Converting between them
Online: JSON โ YAML converts in both directions with a swap button. In code:
import json, yaml # pip install pyyaml
data = yaml.safe_load(open("config.yaml"))
print(json.dumps(data, indent=2))
print(yaml.safe_dump(json.load(open("data.json")), sort_keys=False))import { load, dump } from 'js-yaml' // npm install js-yaml
const obj = load(yamlText)
const yamlOut = dump(JSON.parse(jsonText))Note that comments are lost when converting YAML to JSON, because JSON has no place to put them.