Elofyn

Elofyn Tools · About

About the JSON ↔ YAML converter

← Back to the tool

What this tool does

The JSON ↔ YAML converter turns a JSON document into the equivalent YAML document, or a YAML document into the equivalent JSON, entirely inside your browser tab. You paste configuration on the left, the other format appears on the right, and you copy or download the result. There is no upload step, no server round-trip, no account, and no history kept across reloads. The tool exists for the one-minute job you keep doing: your CI accepts YAML but the new service emits JSON, or vice versa, and you want the translation without trusting a random web form with your secrets.

The detection runs automatically. If the input starts with { or [ the tool tries JSON first; otherwise it tries YAML. If both parsers fail you get a precise line · column error from whichever parser made it furthest into the document, with the offending line marked in the input pane. You can force a direction with the toggle if the heuristic is wrong for your input.

A short history of JSON

JSON's lineage starts in the early 2000s with Douglas Crockford. Working at State Software, Crockford needed a compact, JavaScript-native way to send messages between an Internet Explorer client and a server, and he noticed that JavaScript's object literal syntax was already a perfectly serviceable interchange format. He stripped the format down to two structures, four scalar types, and a one-page grammar, and published it at json.org in 2001. The bet was that anything that compiled cleanly to a JavaScript object would be supported anywhere JavaScript ran, and that turned out to be everywhere.

The IETF picked it up in 2006 as RFC 4627, refined it through RFC 7158 and RFC 7159 in 2013–14, and froze the current grammar in RFC 8259, published in December 2017 and promoted to Internet Standard STD 90. RFC 8259 is the document the parser in this tool follows when accepting JSON input — strict double-quoted strings, no trailing commas, no comments, UTF-8 encoding, and the same five value types (object, array, string, number, the literals true, false, null) the original json.org grammar described.[2]

That strictness is JSON's superpower. Because the grammar is so small, every modern programming language ships a tested parser in its standard library, and serialised JSON from a Go service is byte-compatible with a JSON parser in Rust, Python, Elixir, or your browser's built-in JSON.parse. The trade-off is human ergonomics: JSON forbids comments, every key must be a double-quoted string, and indentation is whitespace the parser cheerfully ignores rather than syntax it cares about. That gap is exactly where YAML showed up.

A short history of YAML

YAML was started in 2001 by Clark Evans, Ingy döt Net, and Oren Ben-Kiki. The original initialism stood for “Yet Another Markup Language,” a wry nod to the alphabet soup of the early-2000s XML era; it was later re-backronymed to “YAML Ain't Markup Language” to make the point that the format was data-first, not document-first. The 1.0 specification landed in 2004, 1.1 followed in 2005, and 1.2 — the major rewrite that concerns this tool — was first published in 2009 and revised most recently as YAML 1.2.2 in October 2021.[1]

YAML 1.2's explicit goal in the rewrite was to become a strict superset of JSON. The 1.2 specification carries this in its opening sections: any well-formed JSON document is, by construction, also a valid YAML document, and every YAML 1.2 processor must accept the flow-style productions that JSON uses. That is the property our tool relies on for the JSON-to-YAML direction — we parse the JSON with the browser's built-in JSON.parse, build a JavaScript value, then emit it through a YAML 1.2 serialiser. The YAML-to-JSON direction is the harder one, because YAML has features JSON cannot represent.

The superset claim, in detail

Every JSON document is valid YAML 1.2. The reverse is not true. YAML 1.2 allows comments (lines starting with #), anchors and aliases for sharing sub-trees (&id and *id), multi-document streams separated by ---, non-string keys, custom tags, and explicit type coercion via tag suffixes such as !!binary. None of those have a place in JSON's grammar.

Here is what this tool does when it meets each one:

  • Comments. Stripped silently when converting to JSON, because JSON has no comment grammar. The about-page notes this clearly so you know to keep the YAML copy if your annotations matter.
  • Anchors and aliases. Expanded into repeated values in the JSON output. A caption appears under the result so you know that &refwas inlined rather than preserved. The 1.2 spec's recommended maxAliasCount guard is on, which means a billion-laughs alias bomb fails fast with a parse error instead of locking up your tab.
  • Multi-document streams. Only the first document is converted. A caption tells you “converted document 1 of N” so you can decide whether to split the source and run the others separately.
  • Non-string keys. JSON object keys must be strings. Scalar keys (a YAML integer 1:) are coerced to the string "1". Sequence or mapping keys (legal in YAML, illegal in JSON) raise an error pointing at the line that needs a redesign.
  • Custom tags. Unsupported. Custom tags express semantics the YAML core schema does not define, and rebuilding a Python !!python/object as JSON would always be a guess. The tool errors out and tells you which tag it could not handle.

Common gotchas

The interesting bugs at the JSON/YAML boundary almost all show up when older YAML 1.1 implementations are in play. YAML 1.2's core schema is the right antidote, and it is the schema this tool uses for every parse.

The Norway problem

Country codes that include NO (Norway), IS, or FR used to round-trip through YAML 1.1 as booleans, because the 1.1 type system treated yes, no, on, and off (and their capitalised variants) as boolean literals. A list of countries would silently lose Norway. The 1.2 core schema fixes this — the only boolean literals are true and false — and the tool shows a caption whenever your YAML contains an unquoted yes/no/on/off so you can quote it if you genuinely wanted a boolean.

Significant whitespace

YAML's block style uses indentation to express nesting. A single mis-indented line moves a key into the wrong parent or breaks the document outright. JSON does not care: braces and brackets do the work. When converting JSON to YAML you can pick between 2-space, 4-space, and tab indent — but YAML 1.2 forbids tab characters at indent boundaries, so picking “Tab” for a YAML output keeps two-space indent and surfaces a caption explaining why.

Number precision

JavaScript numbers are IEEE 754 doubles. Integers above 2^53 − 1 (the constant JavaScript exposes as Number.MAX_SAFE_INTEGER) cannot be represented exactly. Your input might say 9007199254740993, and after a round-trip through JSON.parse the value becomes 9007199254740992. The tool spots long integer tokens in the input and shows a caption naming the offending number — that way you know to fall back to a string-encoded representation in the wire format.

The empty-string footgun

In YAML, an unquoted empty value is null, not "". A configuration entry that reads password: with no value is the YAML literal for null. The tool preserves this faithfully when converting to JSON, but it is worth keeping in mind whenever you write YAML by hand.

When to prefer JSON, when to prefer YAML

Use JSON for anything a machine writes and another machine reads: web APIs, browser-to-server payloads, message queues, build-output manifests, structured logging. JSON's strictness is a feature in those contexts — every parser agrees on every byte, and the format is dense enough that gzip handles it well over the wire.

Use YAML for anything humans hand-edit daily: Kubernetes manifests, GitHub Actions or GitLab CI pipelines, Docker Compose stacks, Ansible playbooks, mkdocs configs, dotfiles. Comments matter, anchors save real duplication on big files, and the lack of quoting noise lets your eye scan the structure. YAML's flexibility is the price you pay for that ergonomics, which is why every long-running YAML codebase eventually ships a linter on the side.

If you genuinely need both — comments for humans, strictness for machines — pick a YAML source of truth and generate JSON for the services that need it. That is the workflow this tool is built for.

How this tool works

The implementation is small enough to describe in a paragraph. The page boots as a React server component with the title, the description, and the link to the tool. The interactive panel is a single client component that owns the input string, the direction toggle, the indent / sort-keys / YAML-style options, and runs the conversion on every keystroke under a useDeferredValueguard so the textarea stays smooth at 1 MiB. Auto-detection looks at the first non-whitespace character: if it is { or [ the JSON parser goes first, otherwise the YAML parser does. Errors are formatted as line N, column M with the original parser message after a colon.

The YAML side uses the open-source yaml library by Eemeli Aro, released under the permissive ISC licence. It targets the YAML 1.2 core schema by default, which is what fixes the Norway problem, and exposes structured parse errors with line / column positions that we can render directly. The JSON side uses the browser-native JSON.parse and JSON.stringify, plus a small recursive walker that sorts object keys when the option is on.

Nothing about your input is sent anywhere. There is no server endpoint, no telemetry hook on the input, no analytics beacon that embeds the payload. The only state that survives a reload is a tiny localStoragetally of three event counts (successful conversions, copy clicks, download clicks) — pure integers, no payload, used to measure whether the tool is genuinely useful for you. You can clear it any time from your browser's site-data settings. The page link to the tool sits in the header above, and you can keep both tabs open while you work.

References

  1. Ben-Kiki, O., Evans, C., & döt Net, I. (2021). YAML Ain't Markup Language (YAML™) version 1.2.2. https://yaml.org/spec/1.2.2/ — superset claim, core schema definitions, anchor / alias / tag semantics.
  2. Bray, T. (Ed.). (2017). RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format. Internet Engineering Task Force, STD 90. https://datatracker.ietf.org/doc/html/rfc8259 — JSON grammar, UTF-8 requirement, unique-key recommendation, number-precision footnote.
  3. Crockford, D. (2001). Introducing JSON. https://www.json.org/json-en.html — the original one-page grammar.