JSON and YAML can describe the same data, and a surprising amount of software reads both. The choice usually comes down to who writes the file: a machine or a person.
Same data, two syntaxes
{
"name": "docento",
"ports": [80, 443],
"debug": false
}
name: docento
ports:
- 80
- 443
debug: false
The YAML version drops braces, brackets and most quotes, and uses indentation to show nesting. That is easier to read and write by hand, but it also introduces failure modes that JSON avoids.
The relationship between them
YAML 1.2 was designed so that valid JSON is also valid YAML, with a few corner-case exceptions. In practice you can often paste JSON into a YAML parser and get the same data, which is handy when converting.
Comparison
| JSON | YAML | |
|---|---|---|
| Comments | Not allowed | Allowed with # |
| Structure | Braces and brackets | Indentation |
| Quotes | Required for strings and keys | Usually optional |
| Data types | Six types | More implicit types (dates, etc., depending on version) |
| Multiline strings | Escape with \n |
Block scalars with | and > |
| Parsing | Simple and fast | Complex specification |
| Whitespace sensitivity | None | Significant |
Where JSON is the better choice
- Data exchange between programs, such as APIs. It is unambiguous and universally supported.
- Anywhere parsing must be predictable. JSON's six value types leave little room for surprise.
- Browsers and JavaScript, where JSON is built in.
- When files are generated and read by machines and humans rarely open them.
Where YAML is the better choice
- Hand-edited configuration. CI pipelines, container definitions and infrastructure files use YAML in large part because it supports comments and is easy on the eyes.
- Long text values, thanks to multiline block scalars.
- Reuse within a file, using anchors and aliases to avoid repeating a block.
YAML's hazards
Because YAML infers types from unquoted text, surprises appear. A value like no, off or yes can be read as a boolean in YAML 1.1 parsers, which is why a country code of NO can turn into false. A version string such as 1.10 can be read as the number 1.1. See YAML gotchas. Indentation errors, especially tabs, which are not allowed for indentation, are another common cause of failure; see fixing YAML indentation errors.
JSON's hazards
JSON is verbose, has no comments and rejects trailing commas, which makes hand-editing tedious. See how to fix invalid JSON.
Converting between them
Because the data models overlap, conversion is usually direct: parse one and write the other. Comments and anchors are lost in the process, because JSON cannot represent them. Check dates and special values after converting.
A practical rule
Use JSON when machines are the main audience and YAML when people are, and use TOML if you want a config format with comments and fewer surprises than YAML. Whichever you pick, run a syntax check before committing. Docento's Text & Markdown Editor validates both formats as you type.
Takeaway
JSON is strict and predictable and fits data exchange. YAML is readable and supports comments, and fits hand-written configuration, at the cost of whitespace sensitivity and implicit typing. Pick by audience.
