How JSON to YAML Conversion Works

An API hands you JSON; your CI pipeline wants YAML. Same data, different skins — and the conversion between them is mostly mechanical, except for one class of values where a careless converter will silently change what your data means. This article walks through what a JSON→YAML converter actually does, field by field.

The structural mapping

Every JSON value has a direct YAML counterpart, so conversion is a re-notation, not a translation. Objects become mappings written as key: value, arrays become sequences written as a dash per item, and nesting is expressed with two-space indentation instead of braces:

{"name":"Ada","roles":["admin","dev"],"active":true,"score":91.5}

becomes:

name: Ada
roles:
  - admin
  - dev
active: true
score: 91.5

The quotes around keys and the braces around objects are gone; true stays true and 91.5 stays a number. Empty containers have dedicated spellings too: an empty object renders as {}, an empty array as [], and JSON null becomes a bare key with nothing after the colon.

The quoting rules that keep types honest

Here is where naive converters break data. YAML parses unquoted scalars by guessing their type — so a JSON string "1.0", dumped bare as version: 1.0, would be read back as the float 1.0, not the string. A converter that preserves types has to quote anything ambiguous. Watch what happens to deliberately tricky strings:

version: "1.0"    ← string that looks like a number
enabled: "true"   ← string that looks like a boolean
note: "key: value" ← contains ": ", which would split a mapping
list: []          ← empty array keeps its shape
n:                ← null becomes a bare key

The tool quotes a scalar when it looks like true/false/null/yes/no/on/off, parses as a number, starts with a YAML indicator character (!, &, *, -, #, [, {…), contains ": " or a trailing space, or holds control characters. Each rule exists because breaking it would let the next reader parse your data as a different type than you wrote. This is the same class of pitfall behind YAML's famous country-code anecdotes — YAML vs TOML vs JSON covers the format-comparison side.

Going the other way: YAML → JSON

The reverse mode parses the indentation structure, then re-serializes as pretty JSON with two-space indent — one canonical spelling out, no matter how the YAML was arranged. The two modes compose into a round trip: JSON in, YAML out, YAML back in, and the recovered data matches the original (verified on the example above). Comments, however, do not survive: YAML allows # annotations but JSON has no comment syntax, so anything after a # is dropped on the way to JSON.

One honest edge case

JSON's number grammar has no concept of infinity, but JavaScript's parser happily turns 1e999 into Infinity — which the YAML side then writes as .inf, YAML's native spelling. Coming back the other way, .inf arrives as the string ".inf", because JSON cannot express infinity as a number. If your data rides near numeric extremes, check that boundary rather than assuming the round trip is transparent.

Converting vs choosing

Knowing how to convert does not settle which format a file should use — that is a different question with different answers per project. The short version: YAML shines where humans edit (CI pipelines, Kubernetes manifests), JSON where machines exchange (APIs, logs, storage). What the converter guarantees is that the decision stays reversible: point it at either format, and the data crosses cleanly, ambiguity-quoting included.

Try it yourself

Paste JSON and flip to YAML (or back) with the JSON to YAML Converter — try {"version":"1.0"} first and check the quotes appear. To lint hand-written YAML without converting it, the YAML Validator reports structure problems and re-dumps the file canonically. The JSON Formatter keeps the JSON side tidy, and TOML to JSON Converter covers the third member of the config-format family.