YAML and JSON describe the same shapes — maps, lists and scalars — so converting between them is mostly a change of notation. The direction is detected from what you paste, or you can set it. Indentation is yours to choose for the YAML side, and keys can be sorted alphabetically, which is worth doing when the output is going into version control and you want a readable diff.
The conversion is not always symmetrical, and the tool says so rather than letting you find out later: YAML has types JSON does not, and anything that cannot survive is reported by path. Dates become strings, infinities become null, and anchors and aliases — YAML's way of reusing a block — are expanded into copies unless you keep them, because JSON has no equivalent.
What does not survive the round trip
-
Comments are lost, always:
JSON has no comment syntax, so a YAML file's comments cannot come back. This is the usual reason a config converted and converted back is worse than it started.
-
Anchors and aliases expand:
a block reused in three places becomes three copies. The data is identical and the file is longer and no longer shares a single definition.
-
YAML's unquoted booleans catch people out:
words such as yes, no, on and off are read as booleans by older YAML parsers. Quote them when they are meant as words — the Norway problem, where the country code NO became false.
-
Indentation in YAML is structure:
unlike JSON's braces, the nesting is the whitespace. A converted file with the wrong indent setting is valid and means something different.
Same shapes, different notation, not always symmetric
YAML and JSON both describe maps, lists and scalars, so most of what the [msm_tool slug="yaml-json-converter"] does is a change of notation rather than a change of meaning. The conversion is not perfectly symmetrical in both directions, though, and rather than letting that surface later as a surprise, anything that cannot survive the trip is reported by its path at the time it happens.
Comments never come back
JSON has no comment syntax at all, so a YAML file's comments have nowhere to go once converted — this is the ordinary reason a configuration file converted to JSON and back reads worse than it started, even though the data itself is unchanged.
Anchors and aliases expand into copies
YAML's mechanism for reusing a block in several places has no equivalent in JSON, so a block referenced three times becomes three separate copies in the output. The data itself is identical either way; what is lost is the single shared definition, along with the fact that editing one instance no longer updates the rest.
The Norway problem
Bare words such as `yes`, `no`, `on` and `off` are read as booleans by YAML, which is how a country code of `NO` becomes the boolean `false` rather than the two letters intended — a well-known enough trap to have its own name. Quoting a value that is meant to stay text, rather than leaving it bare, is what avoids it.
Indentation is structure, not decoration
Where JSON uses braces to mark nesting, YAML uses whitespace itself, so a file converted with the wrong indentation setting is still perfectly valid YAML — it simply means something different from what was intended. That makes indentation a semantic choice here, not a cosmetic one.
Choosing a format for configuration
YAML suits configuration that people actually edit by hand, since comments and readability are exactly what it offers over JSON. JSON is the better choice wherever a machine produces and consumes the file, since it has fewer surprises and nothing YAML-specific to trip over — dates becoming strings and infinities becoming null in the conversion are both reported rather than silently applied either way.