Two formats, one data model
YAML is a superset of JSON. Any valid JSON document is already valid YAML, which is why conversion in that direction is lossless and boring. Going the other way is where the interesting parts live, because YAML has several features JSON simply does not: comments, anchors and aliases for reuse, block scalars for multi-line text, and multiple documents in one file separated by---.
None of those survive a round trip. Comments are discarded, because JSON has nowhere to put them. Aliases are expanded inline, since JSON has no reference syntax. A multi-document stream becomes a JSON array. The data is always preserved exactly; the authoring conveniences are not.
The Norway problem
This is the most famous bug in YAML, and it is worth understanding before it costs you an afternoon. Under YAML 1.1, these all resolve to booleans when unquoted:y,n,yes,no,on, andoff. So a list of country codes containing Norway'sNOsilently becomesfalse.
YAML 1.2 fixed this: onlytrueandfalseare booleans in the core schema. This converter follows 1.2, sonostays a string. But plenty of tooling still runs on 1.1 parsers, so the safe habit is to quote any string that could be mistaken for something else. When emitting YAML, this tool quotes those values for you.
Other ways YAML changes your data
Version numbers lose a digit. Unquoted1.20is a float, and floats do not keep insignificant zeros, so it reads back as1.2. The same trap catches ZIP codes with leading zeros and anything that looks like1:30, which older parsers read as a sexagesimal number.
Tabs are illegal. YAML forbids tab characters for indentation outright. An editor configured for tabs will produce files that fail to parse with a message that rarely points at the real cause.
Block scalars are not interchangeable. The literal style|keeps every newline, which is what a shell script needs. The folded style>joins lines into paragraphs, which suits prose. Adding-strips the trailing newline and+keeps all of them.
Doing it in code
# Shell — yq speaks both directions
yq -o json '.' config.yaml
yq -P '.' config.json
# Python
import yaml, json
json.dumps(yaml.safe_load(open("config.yaml")))
# JavaScript
import { parse, stringify } from "yaml";In Python, always useyaml.safe_loadrather thanyaml.load. The unsafe version can instantiate arbitrary Python objects from a crafted document, which makes parsing an untrusted config file a remote code execution risk.
Frequently asked questions
Does this handle anchors and aliases?+
Yes. Anchors, aliases, and merge keys are resolved during conversion, so an aliased block is expanded inline in the JSON output. JSON has no reference syntax, so the expansion is the only faithful representation.
What is the Norway problem?+
In YAML 1.1, the unquoted values yes, no, on, and off resolve to booleans, so a country list containing NO became false. This converter follows the YAML 1.2 core schema, where only true and false are booleans and no stays the string "no".
Why did my version number change?+
Unquoted 1.20 is a number, and the trailing zero is not significant, so it reads back as 1.2. Quote any version, ZIP code, phone number, or identifier that must keep its exact digits.
Are comments preserved when converting?+
No, and they cannot be. JSON has no comment syntax, so comments are dropped on the way in and there is nothing to restore on the way back. Converting YAML to JSON and back is lossy for comments and formatting, though never for data.
Is my configuration uploaded?+
No. Both parsers run in your browser, so production manifests, secrets, and CI configuration never leave the tab.