Convert JSON to YAML

This is the only conversion on this page group where the answer to "what does it cost me" is genuinely nothing. YAML 1.2, published in 2009 and the version the specification has carried since, defines JSON as a subset: every valid JSON document is already valid YAML. The conversion re-serialises the same tree in a different style.

That makes the rest of this page unusual. There is no lossy step to warn about, no flattening, no type that has to be approximated. What there is instead is a set of questions about how the result will be read, and those turn out to matter more than any data loss would.

The writer follows YAML 1.2, under which no, yes, on and off are ordinary strings. So a JSON value of "no" is written as a bare no, unquoted, and reading that document back with a 1.2 parser returns the string it started as. That is correct behaviour and it round-trips perfectly.

YAML 1.1 disagrees. It resolves those same words to booleans, and PyYAML — which is what Ansible, a great deal of Python tooling and countless internal scripts use — is a 1.1 reader. So a two-letter country code, an answer field, a column called consent: the value goes in as the string no and comes out as false. If a Python tool is anywhere downstream, quote those values by hand after converting. It is a small edit and it is the single most likely way this conversion produces a file that is right and behaves wrongly.

Quoting is decided per value, and only where the bare form would be read as something else. The string "1.0" is quoted, because unquoted it is a number. The string "null" is quoted, because unquoted it is the null value. A string beginning with a hash is quoted, because a bare hash starts a comment, and a string with leading or trailing spaces is quoted, because YAML would otherwise strip them.

The rule is consistent and it is a 1.2 rule, which is exactly the point of the section above. Everything the writer quotes would change meaning under YAML 1.2; the words it leaves bare are the ones that only change meaning under 1.1. A date-shaped string like 2024-01-01 is left bare for the same reason, and a 1.1 reader turns it into a timestamp.

A JSON string cannot contain a literal newline, so a shell script, a certificate or an SQL statement embedded in a JSON manifest is one enormous line with backslash-n where the breaks should be. Reviewing a change to it is not really possible.

The YAML writer emits those values as block scalars: a pipe character, then the text on its own indented lines with the newlines where they belong. A twelve-line entrypoint script becomes twelve lines in the file. For anyone whose reason to convert is that the manifest has to be reviewed by a person, this is usually the biggest single improvement in the output, and it is invisible until the file contains one.

A JSON array of objects converts to the dash-prefixed list that every Kubernetes and GitHub Actions example is written in: a hyphen, then the first key on the same line and the rest indented under it. Containers, steps, volumes, jobs — all of them arrive in the shape the documentation shows.

That matters for review rather than for correctness, and review is what the file is for. A reviewer scanning a list of six deployment steps in YAML can see the boundaries between them without counting braces, which is the reason the ecosystem chose the format despite its indentation traps.

JSON carries no comments, which follows from the grammar in RFC 8259 rather than being an accident of parsers — there is no production for one, so a conforming parser has nothing to accept. YAML carries them anywhere a line can start with a hash. Converting a generated manifest into YAML is very often not about the syntax at all — it is about making the file a place where the reason for a value can live next to the value.

Nothing in the output has comments, because the input had none to give. Adding them is the first edit worth making, and the most useful ones are never descriptions of what a field is. Write down why the replica count is three, which other repository the image tag has to match, and what breaks if the timeout is lowered.

YAML has anchors and aliases, which let one block be defined once and referenced in three places, and it has multiple documents in one file separated by three hyphens. Both are widely used — compose files and Kubernetes bundles rely on them — and neither can come out of a JSON source, because JSON has no way to express either.

So the converted file is correct and flat: everything repeated in the JSON is repeated in the YAML. Factoring the repetition out with an anchor is a manual edit, and worth doing only where the repetition is genuine. A bundle of separate manifests concatenated into one JSON array is the other case, and there the right result is several documents in one file, which again is an edit rather than a conversion.

The writer preserves the order the keys arrived in, so apiVersion, kind and metadata stay where they were rather than being sorted. Neither JSON nor YAML defines mapping order as meaningful, and plenty of tools reorder freely, but a manifest whose keys have been alphabetised is harder to read and produces a large diff for no reason.

That is worth knowing when comparing the output against a file already in the repository. If the two differ only in ordering, the difference came from whatever produced the JSON, not from this conversion — reading a resource back out of a cluster, for instance, returns fields in the API server order rather than the order you wrote them.

The check that costs the least is the tool’s own dry run: kubectl apply with --dry-run=client, docker compose config, or the workflow linter for an Actions file. Each parses the document and reports the shape it found, which catches a misplaced key far faster than reading the file does.

The check that catches the quoting problem is different and has to be done deliberately: search the converted file for bare yes, no, on, off and any unquoted date, and decide for each one whether a YAML 1.1 reader is ever going to see it. That takes a minute and it is the only part of this conversion that a parser will not warn you about.

The conversion runs in this tab. The JSON is parsed by the browser’s own parser and the YAML is written by a library loaded on demand, so no request carries the document anywhere, there is no sign-up and no daily limit, and the free tier accepts up to 100 MB — far more than any manifest.

For this reader that is a practical concern rather than an abstract one. A manifest pulled out of a running cluster contains internal hostnames, registry paths, service account names and the shape of the infrastructure, and a fair number of organisations treat pasting that into a public web converter as an incident. Here there is nothing to paste and nothing to send.