JSON and YAML can describe the same data, so the choice comes down to who (or what) reads and writes the file. JSON is strict, small, and easy for software to parse. YAML is looser and friendlier for humans to edit. Picking the right one prevents a surprising number of config bugs.
The same data, two ways
// JSON
{
"name": "api",
"ports": [80, 443],
"debug": false,
"env": { "NODE_ENV": "production" }
}
# YAML
name: api
ports:
- 80
- 443
debug: false
env:
NODE_ENV: production
Where JSON is the better choice
- APIs and data exchange. Every language has a fast, built-in JSON parser and the grammar is tiny.
- Strictness. There is one way to write each value, so there is little room for ambiguity.
- Machine-generated files, such as lock files and API responses, that people rarely edit by hand.
- Anywhere parser differences would be risky.
Where YAML is the better choice
- Configuration that humans maintain: Kubernetes manifests, GitHub Actions, Docker Compose, Ansible.
- Comments. YAML supports # comments, which are invaluable in config; standard JSON has none.
- Readability of deeply nested data, since there are no braces, brackets, or trailing-comma errors.
- Multi-line strings, which YAML handles cleanly with | and > block scalars.
YAML pitfalls to know about
Indentation is syntax
Structure comes from indentation, and tabs are not allowed for indentation. One misaligned line silently changes the meaning of the document, or breaks it.
Unquoted values get guessed
In YAML 1.1 (still used by many parsers) unquoted yes, no, on, and off can be read as booleans. This is the famous "Norway problem": the country code NO becomes false. Version numbers like 1.10 can become the number 1.1. Quote any value that must stay a string.
A big spec, so parsers vary
YAML has anchors, aliases, tags, and multiple document forms. Different parsers support different subsets, so the same file can behave differently across tools. Loading untrusted YAML with a full-featured loader can also be a security risk; use a safe loader.
A simple rule of thumb
Use JSON when software talks to software
Use YAML when humans maintain the file. If a config file needs comments or is edited often by people, prefer YAML; if it's an API payload or generated data, prefer JSON.
Converting between them safely
Converting JSON to YAML is lossless, but going the other way can drop comments and anchors. Re-validate the result after any conversion. Config files often contain hostnames and secrets, so convert them with a tool that runs locally in your browser.
Frequently asked questions
Is YAML a superset of JSON?
Since YAML 1.2, valid JSON is intended to be valid YAML, so most JSON documents parse as YAML. The reverse is not true.
Why doesn't JSON support comments?
The format was kept deliberately minimal. If you need comments, use JSONC, JSON5, or YAML, or keep documentation outside the file.
Which is faster to parse, JSON or YAML?
JSON is generally much faster and simpler to parse, which is one reason it dominates APIs.
Should I use YAML for API responses?
Almost never. JSON is the standard for APIs because of its strictness, speed, and universal support.
Try it: JSON to YAML Converter — free, runs in your browser, nothing is uploaded.
Originally published at ilovekit.app.
