JSON to YAML: When to Convert and How (Without Breaking Indentation)

JSON and YAML describe the same data, so converting between them sounds trivial — until your Kubernetes manifest rejects a perfectly valid-looking file, or a version number silently becomes a float. JSON-to-YAML conversion is mechanical, but YAML has sharp edges that JSON doesn't. Here's when to convert, and how to avoid the gotchas that turn a clean config into a 2 a.m. debugging session.

They're the same data, different ergonomics

YAML is a superset of JSON — literally. The two differ in ergonomics, not capability:

The headline difference is comments. JSON has none, which is why config formats that humans maintain — GitHub Actions, GitLab CI, Kubernetes, Docker Compose, Ansible — overwhelmingly use YAML. The headline risk is that YAML is indentation-sensitive and tries to be clever about types.

When to convert JSON to YAML (and when not to)

• Convert to YAML when a human will read or edit the file: CI/CD pipelines, infrastructure manifests, app config you check into Git. The comments and reduced punctuation pay off.
• Stay in JSON for API requests/responses, log lines, browser-to-server payloads, and anything generated and consumed by machines. JSON's strictness is a feature there.
• Convert YAML back to JSON when you need to feed a human-edited config into a tool that only speaks JSON, or to validate structure unambiguously.

JSON to YAML Converter

Paste JSON, get clean YAML — runs in the browser, so config with secrets never leaves your machine.

YAML to JSON Converter

Go the other way to validate structure or feed a JSON-only tool.

The three gotchas that break converted YAML

1. Tabs are illegal — spaces only

YAML forbids tab characters for indentation. If your editor inserts tabs, a converted file can look perfect and still fail to parse. Configure your editor to use spaces (2 is the community norm) for YAML files, and let the converter emit spaces.

2. The Norway problem: strings that look like other types

YAML's type inference is famously eager. Unquoted, the value no becomes the boolean false, yes becomes true, and a country code list [NO, SE, DK] can turn Norway into false. Version numbers suffer too: 1.20 may parse as the float 1.2, dropping the trailing zero.

3. JSON has no comments to preserve

Converting JSON to YAML can't add the comments YAML is loved for — there were none in the source. Treat conversion as step one, then add explanatory comments to the YAML by hand. Going the other direction (YAML → JSON) silently drops every comment, since JSON can't hold them.

A clean conversion workflow

1. Validate the JSON first

   Convert from a known-good source. Malformed JSON (a trailing comma, a smart quote) produces confusing YAML errors downstream. Run it through a JSON validator first.

2. Convert to YAML

   Use a converter that runs locally so config containing secrets or internal hostnames never touches a third-party server.

3. Quote the ambiguous values

   Scan for booleans-in-disguise, version strings, and leading-zero IDs. Quote them explicitly.

4. Add comments and verify

   Annotate the YAML for the next human, then round-trip it back to JSON to confirm the structure survived unchanged.

Related formats you'll hit

YAML and JSON aren't the only config formats in rotation. If you're wrangling data between tools, these convert the same structure into other shapes:

JSON to XML Converter

For SOAP services and legacy systems that still speak XML.

JSON to CSV Converter

Flatten an array of objects into a spreadsheet-ready CSV.

For formatting, validating, and converting JSON itself, browse the JSON Tools hub.

Related reading

• CSV to JSON: Converting Spreadsheet Data for APIs
• Understanding the Differences Between Sass and SCSS