What the converter does
This JSON to YAML converter turns a JSON document into the equivalent YAML block, entirely in your
browser, with 2 or 4 space indentation. Multi-line strings become block literals, empty objects and
arrays stay inline as {} and [], and any value that YAML would read as something other than a
string comes back wrapped in quotes.
The output is written for a human to read afterwards, which is the only reason to move to YAML at all. If nobody is going to open the file, JSON was already fine.
The Norway problem, and its relatives
The famous one: YAML 1.1 treats no as the boolean false. A list of ISO country codes containing
NO therefore loads with a false in the middle of it, and the failure surfaces somewhere far from
the file. The same rule catches y, n, yes, on, off and ~.
YAML 1.2 removed those aliases, but the parsers most projects actually run — PyYAML, snakeyaml, and anything embedded in an older tool — still implement 1.1. Assume 1.1 and quote.
Numbers are the second family. 8080 written without quotes is an integer, so a port that a schema
expects as a string fails validation. 1.0 is a float and loads as 1. 0755 and 0x1F are read
in other bases. And 12:30 is a sexagesimal number in YAML 1.1, which is how a duration written in a
config file becomes 750.
Then the punctuation: a value containing : starts a nested mapping, a # starts a comment that
eats the rest of the line, and leading or trailing spaces are silently trimmed. Every one of those is
quoted here, and nothing else is — quoting everything would be safe and unreadable, which defeats the
point of the format.
Indentation, tabs and multi-line text
Two spaces is the convention almost everywhere, and it is what Kubernetes manifests, GitHub Actions workflows and Docker Compose files use. Four is easier to follow when structures nest deeply, and the choice above only changes the file, never its meaning.
Tabs are a different matter. YAML forbids the tab character in indentation outright, and a single one
pasted in from another file produces an error that names a line but not the cause, because a tab
looks like spaces on screen. If you edit YAML by hand, set your editor to insert spaces for .yaml
files and never think about it again.
Multi-line strings use the block form, so a shell script or a certificate stays readable instead of
becoming one long line full of \n. The trailing newline decides the indicator: | keeps exactly
one, |- keeps none. Text that could not survive a block — trailing spaces on a line, or more than
one newline at the end — falls back to a double-quoted string, because a block that silently changes
the text is worse than an ugly line.
When YAML is worth it
YAML earns its complexity when a person edits the file: comments, no punctuation noise, and a diff that changes one line when you change one thing. That is why CI pipelines and Kubernetes live in it.
It stops earning that when the file is only ever produced and consumed by machines. Then you are paying for significant whitespace and a scalar system with a decade of edge cases in exchange for nothing. Generated output, API payloads and anything a build step writes belong in JSON — and if you need it readable there, the JSON formatter will indent and sort it. For the timestamps that end up inside those configs, there is the Unix timestamp converter.