All posts
June 2, 20266 min read

Convert YAML to JSON and back: the rules that trip people up

YAML and JSON describe the same kind of data: scalars, lists, and maps nested inside each other. In fact every valid JSON document is also valid YAML, because YAML 1.2 was designed as a superset of JSON. That sounds like conversion should be trivial, and most of the time it is. The trouble lives in the corners, where YAML's convenience features do not have a JSON equivalent and a converter has to make a decision for you.

Here is what actually happens in each tricky case, and how a sensible converter handles it.

The easy 90 percent

A plain YAML mapping converts to a JSON object with no surprises.

name: toolhq
port: 8080
tags:
  - dev
  - tools

becomes:

{ "name": "toolhq", "port": 8080, "tags": ["dev", "tools"] }

Strings stay strings, the integer stays an integer, and the block list becomes a JSON array. If your YAML only uses obvious scalars and clear structure, you can stop reading and just convert it.

Indentation is structure, not decoration

YAML has no braces or brackets in block style. Indentation alone defines nesting, so a stray space changes meaning. These two snippets are different documents:

server:
  host: localhost
  port: 80

server:
  host: localhost
port: 80

In the second, port is a top level key, not part of server. JSON does not care about whitespace, so this difference vanishes the moment you convert, which is exactly why converting first and reading the JSON is a good way to confirm what your YAML really says. Tabs are forbidden for indentation in YAML; use spaces. A good converter will reject tab indented input rather than guess.

Implicit typing turns words into types

This is the big one. YAML guesses the type of an unquoted scalar. 42 is a number, 3.14 is a float, true is a boolean, and 2026-06-02 may become a date. The guess is helpful until it is wrong.

version: 1.20
zip: 02134

Here 1.20 loses its trailing zero and becomes the number 1.2, and 02134 may be read as an integer, dropping the leading zero. If those are meant to be strings, quote them:

version: "1.20"
zip: "02134"

When in doubt, quote scalars that are really identifiers, codes, or versions.

The Norway problem

The most famous YAML trap. In YAML 1.1, several words are booleans: yes, no, on, off, true, false, and their capitalized forms. So a list of country codes:

countries:
  - NO
  - SE
  - FR

can parse with NO (Norway) becoming the boolean false. After conversion you get [false, "SE", "FR"], which is nonsense. YAML 1.2 narrowed booleans to only true and false, but many parsers still run in 1.1 mode, so the safe fix is the same as above: quote the value. "NO" stays a string. The same applies to on/off used as feature flag names.

Null has several spellings

YAML accepts null, ~, and an empty value as null. All three convert to JSON null.

a: null
b: ~
c:

becomes { "a": null, "b": null, "c": null }. The empty case surprises people: a key with nothing after the colon is null, not an empty string. If you want an empty string, write "".

Anchors and aliases get flattened

YAML can define a node once and reuse it with &anchor and *alias, and merge maps with <<. JSON has no such mechanism, so a converter resolves them: it copies the referenced value into every place it is used.

defaults: &defaults
  retries: 3
  timeout: 30
prod:
  <<: *defaults
  timeout: 60

converts to fully expanded JSON:

{
  "defaults": { "retries": 3, "timeout": 30 },
  "prod": { "retries": 3, "timeout": 60 }
}

The structure is duplicated and the alias is gone. That is expected and correct, but it means a large YAML file built on shared anchors can expand into a much larger JSON file. Converting back from JSON to YAML will not rebuild the anchors; that information is not recoverable.

Multi-document streams

YAML can hold several documents in one file, separated by ---, a pattern common in Kubernetes manifests.

---
kind: Service
---
kind: Deployment

JSON has no multi-document concept. A converter typically emits a JSON array, one element per document: [{ "kind": "Service" }, { "kind": "Deployment" }]. If you feed it a single document, you get a single object. Know which behavior you need before you paste a multi-doc file.

Convert it and check the result

The reliable workflow is to convert and then read the JSON output, because JSON has no implicit typing or hidden structure. What you see is exactly what the data is.

Paste your YAML into the YAML to JSON Converter to see the typed result instantly, then run that JSON through the JSON Formatter to pretty print and validate it. If you need tabular output instead, the JSON to CSV Converter takes it from there.

Everything runs in your browser. Config files often hold secrets, tokens, and internal hostnames, so it matters that nothing is uploaded: the conversion happens locally and your input never leaves the page.