YAML to JSON: A Practical Guide

You wrote a config in YAML because it reads well, and now a tool wants JSON. GitHub Actions, Kubernetes manifests, and Docker Compose files are all YAML, but APIs, linters, and half the tooling ecosystem speak JSON. The conversion looks trivial until YAML turns a country code into a boolean or collapses a version number into the wrong value. This guide covers how the two formats line up and where they quietly do not.

YAML Is a JSON Superset, Mostly

Every valid JSON document is also valid YAML. YAML 1.2 was designed that way, so you can paste JSON into a YAML parser and it just works. The reverse is not true. YAML has features JSON has no room for, and those are exactly the spots where conversion gets interesting.

Here is where the two formats diverge:

Nesting, arrays, and basic key-value pairs map cleanly. Everything below is about the parts that do not.

Type Coercion Is the Real Trap

YAML infers types from unquoted values, and its guesses do not always match what you meant. This is the source of most conversion bugs.

Under the older YAML 1.1 rules that many parsers still use, this becomes:

Every line is a surprise. NO is the Norway problem: the country code for Norway parses as boolean false. 1.10 is read as a float and loses its trailing zero, so version 1.10 becomes 1.1. yes turns into true. The leading zero on 08080 is invalid octal, so it stays a string. And 1_000 uses digit separators that collapse to 1000.

The fix is quoting. Wrap anything that should stay a string:

If your converted JSON has booleans or numbers where you expected strings, this is almost always why. Quote the source YAML and convert again.

Multiline Strings Convert Differently

YAML has two block scalar styles, and they produce different JSON. The literal style (|) keeps newlines. The folded style (>) turns newlines into spaces.

Converts to:

Note the trailing newline on both. If you do not want it, use the strip indicator (|- or >-) in the YAML. This matters for things like embedded scripts or certificates where an extra newline changes behavior.

Anchors Get Expanded, Not Preserved

YAML lets you define a value once and reuse it with anchors (&) and aliases (*). JSON has no such concept, so the converter copies the value everywhere it was referenced.

The merge key (<<) pulls the anchored values in, and the JSON output has them written out in full:

The deduplication YAML gave you is gone. That is fine for machines but worth knowing if you expected the JSON to stay compact.

Multi-Document Files Need a Decision

A single YAML file can hold several documents separated by ---. Kubernetes manifests do this constantly, bundling a Deployment and a Service in one file. JSON has no separator syntax, so one YAML file cannot become one JSON document.

You have two options: wrap the documents in a JSON array, or emit one JSON file per document. Most converters produce an array:

If a downstream tool expects a single object, split the file first. Do not assume the array shape will be accepted.

Converting in Code

In Python, PyYAML handles the parse and the standard library handles the serialize. Use safe_load unless you fully trust the source, because load can execute arbitrary tags:

In Node, the js-yaml package is the standard choice:

For a one-off conversion, skip the setup. Paste your YAML into the YAML to JSON converter and read the result directly. Going the other way for a JSON config you want to hand-edit as YAML, the JSON to YAML converter does the reverse.

Check the Output Before You Trust It

The conversion itself rarely fails loudly. It fails quietly, with a boolean where you wanted a string or a version number that lost a digit. After converting, run the JSON through the formatter to see the structure clearly, then the JSON validator to confirm it parses. Scan the values, not just the shape: the Norway problem does not throw an error, it just hands you false and lets you find out in production. A ten-second look at the converted types is cheaper than that.