JSON to YAML

Same data, a surface built for editing

JSON and YAML describe the same three things: scalars, ordered sequences and key-value mappings. Converting between them is a change of notation, not of meaning — which is why this direction is the easy one. Every JSON document has a YAML equivalent, with no exceptions and nothing lost.

The reason to do it is that YAML is what configuration tooling expects. Kubernetes manifests, GitHub Actions and GitLab CI pipelines, Docker Compose, Ansible playbooks and OpenAPI specifications are all YAML by convention, and a pasted block of JSON in the middle of one is technically valid and socially wrong.

A real conversion

{
  "name": "checkout-service",
  "replicas": 3,
  "enabled": true,
  "note": null,
  "version": "1.0",
  "country": "no",
  "description": "line one\nline two\n",
  "tags": ["web", "payments"],
  "resources": { "limits": { "cpu": "500m", "memory": "512Mi" } },
  "empty": {},
  "none": [],
  "colon": "key: value",
  "hash": "#1 priority"
}

name: checkout-service
replicas: 3
enabled: true
note: null
version: '1.0'
country: 'no'
description: |
  line one
  line two
tags:
  - web
  - payments
resources:
  limits:
    cpu: 500m
    memory: 512Mi
empty: {}
none: []
colon: 'key: value'
hash: '#1 priority'

Key order is preserved exactly. Braces and brackets disappear in favour of indentation, except for empty collections, which keep the flow form because {} and [] have no block equivalent.

Why some strings get quotes and others do not

This is the only genuinely interesting decision in the conversion, and getting it wrong is how YAML files break. A string is quoted whenever leaving it bare would make a YAML parser read it as something other than a string.

The conversion is conservative in the right direction: it adds quotes when they are needed and leaves them off when they are not, so the output stays readable without being fragile. This is the same set of traps described from the other side on the YAML to JSON page — worth reading if you edit YAML by hand.

Multi-line strings become block scalars

A JSON string containing newlines is written with \n escapes, which is unreadable for anything longer than a sentence. YAML has a better answer, and the converter uses it automatically.

"description": "line one\nline two\n"

description: |
  line one
  line two

The | marker means "everything indented below this is a literal string, newlines included". It is the single biggest readability win of the format, and the reason embedded scripts in CI pipelines are bearable at all.

Indentation and key order

Two spaces is the default and is what essentially every YAML tool and linter expects. Four is available and legal; it makes deeply nested manifests wider without making them clearer. Sequences are indented under their key rather than hung at the parent level — both forms are valid YAML, and the indented one is what kubectl and the major linters emit.

Key order comes straight from the JSON and is never rearranged, which is the right default for configuration — order there is usually deliberate. apiVersion, kind, metadata, spec is the conventional opening of a Kubernetes manifest, and a converter that alphabetised it would be actively unhelpful. If you do want a canonical order for machine comparison, sort the JSON first with the beautifier and convert the result.

What the converter cannot invent

YAML has features JSON has no equivalent for, and nothing in your JSON can tell the converter where to use them.

• Comments. JSON has none to carry over. If you are regenerating a config file that had comments, you will be adding them back by hand — which is a good argument for keeping the YAML as the source of truth and the JSON as a derived artifact.
• Anchors and aliases. Repeated blocks are written out in full rather than collapsed into &defaults and *defaults. The output is correct, just more verbose than something hand-written.
• Multiple documents. One JSON document produces one YAML document. Concatenate with --- separators yourself if you need several.
• Explicit tags. Types are inferred from the values, which is what you want for configuration.

A round trip worth testing

JSON → YAML → JSON returns the same data, so long as the quoting is right — which is exactly what the converter handles for you. It is a genuinely useful sanity check: convert to YAML, paste the result into the YAML to JSON converter, and diff it against the original. Zero differences means the YAML you are about to commit says precisely what you think it says.

That check catches the one class of bug that hand-written YAML produces constantly: a version number, a postal code or a country code that quietly stopped being a string.