How to Convert JSON to YAML (and YAML to JSON)

How to Convert JSON to YAML (and YAML to JSON)

JSON and YAML are two ways of writing the same thing. APIs speak JSON; Kubernetes, GitHub Actions, Docker Compose, and Ansible speak YAML. Sooner or later you have a config in one format and need it in the other.

The conversion is usually mechanical — both formats describe the same tree of maps, lists, strings, numbers, and booleans. But a few edge cases silently corrupt data on the way across. This guide covers the conversion in both directions and the gotchas worth knowing.

The Mental Model

Every JSON document maps cleanly onto a YAML document because YAML is a superset of JSON. Anything valid as JSON is also valid YAML. The four building blocks line up exactly:

JSON uses braces, brackets, and commas. YAML uses indentation and dashes. That's the core of the transformation.

Side-by-Side Example

The same configuration in both formats:

JSON:

{
  "service": "api",
  "replicas": 3,
  "ports": [8080, 8443],
  "env": {
    "LOG_LEVEL": "info",
    "DEBUG": false
  },
  "tags": ["backend", "public"]
}

YAML:

service: api
replicas: 3
ports:
  - 8080
  - 8443
env:
  LOG_LEVEL: info
  DEBUG: false
tags:
  - backend
  - public

Notice what disappeared: braces, the commas, and most of the quotes. What appeared: meaningful indentation (two spaces per level) and dashes for list items. The data is identical.

Converting in the Browser

For a one-off, paste your JSON into the JSON to YAML Converter — it parses the JSON, validates it, and emits clean YAML with proper indentation. Going the other way, the YAML to JSON Converter parses YAML (validating syntax as it goes) and pretty-prints the JSON. Both run entirely in your browser, so config files containing secrets never leave your machine.

If your JSON won't convert, it's almost always a syntax error — run it through the JSON Validator first to find the bad comma or unquoted key.

Converting in Code

Python (the PyYAML library):

import json, yaml

# JSON string → YAML
data = json.loads(json_string)
yaml_string = yaml.dump(data, default_flow_style=False, sort_keys=False)

# YAML string → JSON
data = yaml.safe_load(yaml_string)
json_string = json.dumps(data, indent=2)

Use yaml.safe_load, never yaml.load — the unsafe loader can execute arbitrary Python objects embedded in the YAML.

Node.js (the js-yaml package):

const yaml = require("js-yaml");

// JSON → YAML
const yamlString = yaml.dump(JSON.parse(jsonString));

// YAML → JSON
const jsonString = JSON.stringify(yaml.load(yamlString), null, 2);

Command line (with yq):

# JSON → YAML
yq -P '.' config.json > config.yaml

# YAML → JSON
yq -o=json '.' config.yaml > config.json

The Gotchas That Break Round-Trips

YAML is more permissive than JSON, which is exactly where conversions go wrong.

1. The Norway problem. YAML 1.1 interprets unquoted yes, no, on, off, true, false, and the country code NO as booleans. A list of country codes [NO, SE, DK] round-trips through some parsers as [false, SE, DK]. Always quote strings that could be read as booleans.

2. Numbers that look like strings. A ZIP code "02134" is a string in JSON. Unquoted in YAML, a parser may read it as the integer 2134, dropping the leading zero. Version strings like 1.10 can become the float 1.1.

3. Comments don't survive. YAML supports # comments; JSON does not. Convert YAML → JSON → YAML and every comment is gone. See YAML Comments & Multiline Strings for what you lose.

4. Key order. JSON objects are technically unordered. Most converters preserve insertion order, but if you rely on key order, pass sort_keys=False (Python) and verify your tooling doesn't re-alphabetize.

5. Duplicate keys. Both formats technically forbid duplicate keys, but YAML parsers often silently keep the last one. JSON parsers vary. Converting can mask a bug where you had two name: keys.

Which Should You Use?

Use JSON for APIs, data interchange, and anywhere a machine is the only reader — it's stricter and faster to parse. Use YAML for human-edited configuration where comments and readability matter (CI pipelines, Kubernetes manifests, app config). For a deeper comparison including XML, see YAML vs JSON vs XML.

Quick Reference

• YAML is a superset of JSON — every JSON document is already valid YAML.
• JSON → YAML drops braces/commas/quotes and adds indentation + dashes.
• Convert instantly with the JSON to YAML and YAML to JSON tools.
• In code: PyYAML (use safe_load), js-yaml, or yq on the CLI.
• Watch for the Norway problem, leading-zero numbers, and lost comments on round-trips — quote ambiguous strings.