Guide

How to convert JSON to YAML

Converting JSON to YAML changes the notation of a parsed value. Objects become mappings, arrays become sequences, and readable indentation usually replaces JSON punctuation. It is useful for configuration, but it is not a byte-preserving translation of your original file.

This converter first uses JavaScript JSON.parse, then the yaml library to serialize that value. Duplicate JSON members have already collapsed to their last value and numeric precision may already have changed before YAML is written. Check the original JSON before treating the result as a faithful source copy.

Open the JSON to YAML

Use this when

  • A configuration tool accepts YAML and your source is JSON
  • You want to add explanatory comments to a configuration after conversion
  • A nested JSON configuration needs a more readable authoring format
  • You are comparing the same parsed settings in JSON and YAML notation

What actually changes

A JSON object becomes a YAML mapping, commonly displayed as key-value lines. A nested object is indented and an array usually becomes dash-prefixed sequence items. Those changes describe the parsed structure, not new application behavior: converting an arbitrary API response does not make it a valid Kubernetes manifest or workflow.

The emitter chooses a YAML representation for each value. Strings may be plain, quoted or block scalars; numbers, booleans and null use scalar forms. Key enumeration follows JavaScript rules, so array-index-like keys can be reordered even when ordinary string keys retain their source order.

The output has no comments because JSON has none to supply. You can add them afterwards, but keep that YAML file as the authoring source if the comments matter. A later trip through JSON cannot carry those annotations back.

When a string still needs its quotes

A string such as "1.10" must remain distinguishable from the number 1.1. Similarly, a quoted JSON identifier with leading zeros should still be a string after YAML parsing. Let the emitter choose quoting, then test the destination rather than stripping quotes because the file looks cleaner without them.

The yaml library defaults to YAML 1.2 core scalar rules. Bare yes, no, on and off are strings under those rules, unlike the YAML 1.1 boolean convention. The generated YAML may therefore look safe here and be read differently by a destination using YAML 1.1. Quote ambiguous words explicitly when handing the result to such a consumer.

Leading-zero numbers are version-sensitive too. Under YAML 1.2 core rules, 0755 is decimal 755 and 0o755 is octal 493; 08080 is decimal 8080, not an invalid octal value. Under YAML 1.1, 0755 has different meaning. Preserve identifiers as quoted strings instead of using parser-version differences as a data model.

Long strings and multi-line text

The emitter disables automatic line-width wrapping. That is helpful when a long URL, command or value must not acquire layout changes. Existing newline characters may still use YAML block-scalar notation, which is a representation of the string rather than an instruction to wrap an arbitrary line.

A literal block introduced by a pipe preserves line breaks; a folded block introduced by a greater-than sign applies folding rules. Chomping indicators control the end: pipe-minus strips the final newline, a plain pipe clips it to one, and pipe-plus keeps trailing newlines. These distinctions matter for scripts and other whitespace-sensitive values.

Do not choose a block style only for appearance. Convert the edited YAML back and compare the resulting string, including its final newline, with the intended JSON string. A file that looks identical in a text editor can still contain a different terminal newline.

The documents that have no clean YAML form

Unusual JSON property names are legal data, including empty strings, embedded newlines and punctuation. YAML can represent such keys, but the resulting quoting or explicit-key notation may be harder to read than the original JSON. Converting notation does not improve an awkward data model automatically.

Very deep nesting makes indentation hard to follow. If reviewers have to count ten levels of spaces to locate a setting, changing the format is not enough. An editor with indentation guides or a schema-aware configuration view may be a better improvement.

The numerical and duplicate-key limits occur before the emitter runs. A 64-bit identifier written as a JSON number can round; a duplicate member can disappear; a huge exponent can become a non-finite JavaScript number. A YAML round trip cannot recover source information lost by JSON.parse.

Checking the result

Validate the untouched JSON first, especially when duplicate keys are possible. Convert, then parse the YAML using the actual consumer or the YAML-to-JSON tool. Compare parsed values rather than indentation, quotes or numeric spelling.

That comparison checks the value after parsing, not the original text. Comparing against JSON.parse of the original will not detect a large integer already rounded by both paths. Keep exact identifiers and high-precision amounts as strings from the beginning when those digits must survive.

The destination remains the authority for schema and version compatibility. A general converter does not check required Kubernetes fields, supported workflow keys or application-specific tags. Use the target system’s validation or dry-run command before replacing a working configuration.

yaml library documentation — Primary documentation for the parser and emitter, including version, schema and stringification options.

Common problems

Each of these is something that actually happens, with the cause rather than a generic suggestion to check your input.

A version lost its trailing zero

Cause
A string was edited into an unquoted number and parsed before conversion back.
Fix
Keep version numbers as quoted strings and repair the authoring file, not only the output.

NO became false in another application

Cause
The destination uses YAML 1.1 boolean rules rather than the default YAML 1.2 rules used here.
Fix
Quote ambiguous codes and words, then validate with the destination parser.

A leading-zero identifier changed

Cause
An unquoted numeric-looking value was interpreted as a number; the version can also affect its base.
Fix
Use quoted strings for identifiers and verify their type after parsing.

The edited YAML has an indentation error

Cause
Tabs or inconsistent indentation changed the structure. The converter emits spaces.
Fix
Correct indentation without replacing tabs that intentionally belong inside string values.

A multiline value gained a final newline

Cause
The block scalar’s chomping indicator changed the string.
Fix
Review pipe, pipe-minus and pipe-plus behavior by comparing the parsed string.

Questions

Is converting JSON to YAML lossless?
It normally preserves ordinary parsed values, not source bytes. JSON.parse can discard duplicate members and round numbers before conversion; ordering, escape spelling and formatting can also change.
Can I add comments afterwards?
Yes. Keep the annotated YAML as the source if you need those comments: JSON has no comment representation, so converting back drops them.
Which indentation should I use?
Two spaces is the default and a reasonable convention. The emitter clamps its indentation option between one and eight spaces; do not use tabs for YAML indentation.
Is my data uploaded anywhere?
Conversion happens in the browser’s Web Worker: no request carries your input or converted output, because conversion happens locally rather than through an upload endpoint. Still handle sensitive configuration carefully and avoid sharing output containing credentials.

Where to go next