YAML and JSON
YAML is a superset of JSON designed to be written by hand: indentation instead of braces, no quotes needed for most strings, and comments. JSON is stricter and is what most APIs and programs read. Converting YAML to JSON is a quick way to see exactly what a config file means, because every implicit type, anchor and merge is spelled out in the result.
Parsing uses the open-source yaml library with the YAML 1.2 core schema, running in your browser. Merge keys, which YAML 1.2 dropped but Docker Compose and CI files still use, are turned on.
Worked example: anchors, aliases and merge keys
An anchor (&defaults) names a value, an alias (*defaults) repeats it, and a merge key (<<) copies a mapping's keys into another mapping. Keys written next to the merge win:
defaults: &defaults
image: node:20
restart: always
services:
web:
<<: *defaults
ports: ["8080:80"]
worker:
<<: *defaults
restart: "no"
converts to:
{
"defaults": { "image": "node:20", "restart": "always" },
"services": {
"web": { "image": "node:20", "restart": "always", "ports": ["8080:80"] },
"worker": { "image": "node:20", "restart": "no" }
}
}
The tool indents each key on its own line; it is condensed here. Note that "no" is quoted in the YAML. Docker Compose expects the string no for restart, and quoting keeps it a string in every YAML version.
Implicit types and the Norway problem
Unquoted values are typed by how they look, and the rules changed between YAML 1.1 and 1.2. In YAML 1.1, yes, no, on and off are booleans, so a list of country codes turns Norway's NO into false. This converter follows 1.2, but other tools you feed the same file to may not.
| Unquoted YAML | JSON here (YAML 1.2) | Older YAML 1.1 parsers |
|---|---|---|
NO, yes, on | "NO", "yes", "on" | false, true, true |
0755 | 755 | 493 (octal) |
0o755 | 493 | "0o755" |
12:30 | "12:30" | 750 (base 60) |
2024-01-15 | "2024-01-15" | Often a date object |
1.10 | 1.1 | 1.1 |
~ or nothing | null | null |
The safe habit is to quote anything that must stay a string: version numbers, country codes, file modes, times and ZIP codes.
In the other direction, JSON → YAML writes YAML that older parsers read the same way: it puts quotes around strings such as "NO", "yes", "on" and "1.10" that would otherwise change type. Long strings are not wrapped onto several lines.
Things to watch for
- Indentation: YAML uses spaces only; a tab in the indentation is an error.
- Duplicate keys in the same mapping are an error rather than silently keeping the last one.
- Anchors before aliases: an alias must come after its anchor in the file, or you get an "Unresolved alias" error.
- Comments are dropped, because JSON has no comments.
- Several documents separated by
---become a JSON array, and the status line says how many there were. A file containing only comments gives no output. - Block scalars:
|keeps line breaks and>folds them into spaces; both end with a single newline by default. - Special numbers:
.infand.nanhave no JSON equivalent and becomenull; integers beyond 253 lose precision. - Alias bombs: documents that expand aliases thousands of times, the YAML version of a "billion laughs" attack, are stopped with an error instead of freezing the page.
Reading error messages
Errors give the line and column where the parser gave up, which is often just after the real mistake. A common one is "Nested mappings are not allowed in compact mappings", which usually means a key is indented under a line that already has a value, like key: value followed by an indented bad: 1. Another is an unclosed [ or { in a flow collection, reported on the following line.