How to Convert JSON to YAML (Mapping, Quoting, and the Gotchas)

JSON and YAML describe the same thing: objects, arrays, and scalar values. YAML was designed as a superset of JSON, which means every valid JSON document is already valid YAML. So converting between them is not a translation that can lose meaning; it is a rewrite of the same data into a different syntax. JSON shows structure with braces and brackets, YAML shows it with indentation and dashes. This guide covers how the mapping works, the one rule that surprises people (why some values come out quoted), the gotcha that bites when you go back the other way, and the fastest way to do it.

The fastest route: a browser converter

For a one-off, paste the JSON into the JSON to YAML converter. It parses the JSON, then re-serializes the same data as YAML, so the output is guaranteed well-formed. You pick 2 or 4 space indentation and, optionally, sort keys. Because it runs entirely in your browser, the JSON never leaves your machine, which matters when a payload carries keys or tokens. For the reverse direction, the YAML to JSON converter does the same in reverse.

If the JSON will not convert, it is almost always invalid rather than genuinely unconvertible. Run it through the JSON parser to find the exact syntax error, or format it so you can see the structure first.

How JSON maps to YAML

A converter makes the same decisions every time. Knowing them tells you what to expect.

Here is the shape of a simple conversion:

{ "name": "web", "ports": [80, 443], "tls": true }

becomes:

name: web
ports:
  - 80
  - 443
tls: true

The object became a mapping, the array became a dashed sequence indented under ports, and the number and boolean carried over untouched.

Why some values come out quoted

This is the one behavior that looks wrong until you understand it. YAML reads an unquoted value by what it looks like, so a bare 3 is the number three and a bare true is a boolean. That creates a problem when your JSON has the string "3" or the string "true". If the converter wrote them bare, re-reading the YAML would turn them into a number and a boolean, changing the type. To prevent that, YAML quotes them:

version: '3'
enabled: 'true'
zip: '01234'

The string "3" becomes '3', "true" becomes 'true', and a leading-zero value like a ZIP code "01234" is quoted so it is not read as an octal-looking number. This quoting is not noise. It is exactly how YAML preserves the type your JSON declared, which is what keeps the conversion lossless. If you see quotes in the output where you did not expect them, it is because the bare form would have meant something else.

The gotcha going the other way

The same implicit typing is a trap when you convert YAML back to JSON, or author YAML by hand. In YAML, a bare yes, on, off, or no is a boolean, and a bare number is a number. So this YAML:

country: NO
answer: yes
version: 3

converts to JSON as "country": false, "answer": true, and "version": 3, which is almost never what someone writing a country code of Norway intended. The fix is to quote any scalar that must stay a string: country: "NO". If you are debugging a value that arrived as the wrong type after a round trip, this is the first thing to check. The YAML to JSON converter shows you immediately what each bare value resolved to.

Comments do not survive the trip

YAML supports comments with #; JSON has none. So converting JSON to YAML never adds comments, and converting YAML to JSON drops every comment line. That is expected, because comments are not part of the data model, only an annotation on the text. If your workflow relies on comments in a config file, keep the YAML as the source of truth and treat the JSON as a derived, generated artifact rather than something you hand-edit.

Round trips are lossless for standard data

Because both formats share one data model, converting JSON to YAML and back returns your original document, value for value. The only things that do not survive are the things that were never data in the first place: comments, and cosmetic choices like indentation width or key order. YAML has a few features with no JSON equivalent, such as anchors and aliases for reusing a block, and custom tags. Standard JSON data uses none of these, so for the payloads you get from an API or store in a config file, the round trip is exact.

Doing it in code

A browser tool is right for a one-off. In a build or a script, use a library.

In every case the pattern is the same: parse one format into a native data structure, then serialize that structure into the other. The data structure in the middle is why the conversion is lossless.

The gotchas that bite

Frequently asked questions

Is JSON already valid YAML?
Yes. YAML is a superset of JSON, so any valid JSON parses as YAML without changes. Converting to YAML block style just makes it more readable by replacing braces and brackets with indentation and dashes.

Does converting JSON to YAML lose any data?
No, not for standard JSON data. The structure and values are preserved exactly, and a round trip back to JSON returns the original. Only comments and cosmetic formatting are not carried, because they are not part of the data.

Why does the YAML output have quotes around numbers like ‘3’?
Because the original JSON value was the string "3", not the number 3. Quoting it in YAML stops it from being re-read as a number, which preserves the type. A bare 3 would convert back to JSON as a number.

How do I convert YAML back to JSON?
Paste it into the YAML to JSON converter. It parses the YAML and serializes it as formatted JSON, resolving bare scalars to their types.

For the format underneath both, see the guide on what JSON is, and for when to pick one format over another read JSON vs XML vs YAML. For the rest of the toolkit, see the roundup of free JSON tools.

Leave a Reply

Your email address will not be published. Required fields are marked *