JSON to YAML Converter

How JSON to YAML conversion works

Not a find-and-replace. The document is parsed into real data, and that data is written out again in the other notation.

1. Parse. The JSON text is read with JSON.parse, which either produces a JavaScript value or throws with the position of the first syntax error.
2. Validate. If it throws, the byte offset is converted to a line and column and reported. No output is produced — a failed conversion must never leave something copyable in the output pane.
3. Walk. The resulting value is walked once. Objects become YAML mappings, arrays become sequences, and each level adds one step of indentation.
4. Serialise safely. Every scalar is checked before it is written. Anything that YAML would read back as a different type, or that starts with an indicator character, is emitted as a double-quoted string.
5. Emit. The lines are joined into the finished document, which is what you see, copy and download.

The reverse direction runs the same pipeline backwards: a real block parser reads the YAML into a data structure, and JSON.stringify writes it out. Both directions share one data model, so a document can make the round trip without drifting.

JSON to YAML conversion examples

Exactly what this converter produces for each shape.

Basic object

{
  "name": "John",
  "age": 30,
  "active": true
}

name: John
age: 30
active: true

Arrays become sequences

{
  "languages": [
    "JavaScript",
    "Python",
    "PHP"
  ]
}

languages:
  - JavaScript
  - Python
  - PHP

Nested objects become nested mappings

{
  "server": {
    "host": "localhost",
    "port": 8080
  }
}

server:
  host: localhost
  port: 8080

Arrays of objects

{
  "users": [
    { "id": 1, "name": "John" },
    { "id": 2, "name": "Jane" }
  ]
}

users:
  - id: 1
    name: John
  - id: 2
    name: Jane

Values that must be quoted

{
  "version": "123",
  "enabled": "true",
  "released": "2024-01-01",
  "note": "key: value # test"
}

version: "123"
enabled: "true"
released: "2024-01-01"
note: "key: value # test"

JSON vs YAML

Any valid JSON is also valid YAML, because JSON is a subset of YAML 1.2. The reverse is not true: a YAML file using comments, anchors or several documents has no JSON equivalent. That asymmetry is the one thing to keep in mind when moving between them.

Working with JSON and YAML

What is JSON?

JSON — JavaScript Object Notation — is a text format for structured data. It has six value types: object, array, string, number, boolean and null, and that is the entire vocabulary. There are no dates, no comments, no references and no integers distinct from floats.

Its defining quality is strictness. Keys must be double-quoted, commas must separate members and must not trail, and there is exactly one way to write any given document's structure. That rigidity is a feature: a JSON parser needs no configuration, has no dialect to negotiate and cannot interpret the same bytes two ways. It is why JSON became the default for web APIs, log lines and anything machines exchange without a human in the loop.

The same rigidity is what makes JSON tiring to write by hand. Every quote, brace and comma is mandatory, a single trailing comma invalidates the file, and there is nowhere to leave a note explaining why a setting is what it is.

What is YAML?

YAML expresses the same data model but optimises for the person reading it. Structure comes from indentation rather than braces, list items are marked with a dash, quotes are optional wherever the value is unambiguous, and comments are allowed anywhere.

It also goes further than JSON in places. Anchors and aliases let one part of a document refer to another rather than repeating it. Block scalars carry multi-line text without escape sequences. A single file can hold several documents separated by ---. None of those have a JSON equivalent, which is worth remembering before treating the two as interchangeable.

The cost of that flexibility is that YAML has more rules about what an unquoted value means, and indentation errors are easy to make and easy to miss. Tabs are not permitted for indentation at all — a detail that has cost most people at least one confusing afternoon.

What is a JSON to YAML converter?

A converter parses one notation into a data structure and writes that structure out in the other. Nothing is added, removed or reinterpreted; only the surface syntax changes.

That sounds simple enough to do with string manipulation, and that is exactly the trap. A converter built on pattern matching handles a flat object of scalars and falls apart at the first array, because a sequence has to move onto its own lines and be indented relative to the key it belongs to. Getting that wrong produces output that looks approximately right and does not parse.

The harder half of the job is quoting. YAML infers the type of an unquoted scalar, so a JSON string of "123" written plain comes back as a number, and a string of "true" comes back as a boolean. A correct converter checks every scalar against the set of values YAML would reinterpret and quotes the ones that need it — nothing more, so the output stays readable.

JSON objects and YAML mappings

A JSON object becomes a YAML mapping. Each key sits at the current indentation followed by a colon and a space, then its value. Where the value is itself an object or an array, the key line ends after the colon and the child is written on the following lines, indented one step further.

Keys need the same care as values. A key containing a colon and a space would split into two mappings if written plain, so it is quoted. So is a key that is empty, that looks numeric, or that starts with an indicator character. This is a common source of subtly corrupted output in weaker converters, because keys are easy to assume are safe.

JSON arrays and YAML lists

A JSON array becomes a YAML sequence: one item per line, each prefixed with - . Under a key, the sequence is indented one step below that key.

Arrays of objects are where the layout gets interesting. The first key of each object goes on the same line as its dash, and the object's remaining keys align underneath that first key — two columns to the right of the dash, regardless of the indentation setting. Getting that offset wrong is the single most common bug in hand-written emitters, because the dash is always two characters wide even when the indent step is four.

Empty arrays and empty objects are written in flow style on the key line, as [] and {}. There is no block form for an empty collection, and leaving the key with nothing after it would make it null instead.

JSON data types in YAML

Numbers, booleans and null are written unquoted so they stay what they are. Strings are written plain when they are unambiguous and double-quoted when they are not.

The list of values YAML would reinterpret is longer than most people expect. Beyond the obvious true, false and null, YAML 1.1 also reads yes, no, on, off, y and n as booleans; ~ as null; hexadecimal, octal and binary literals as numbers; 1:30 as a sexagesimal number; and anything shaped like 2024-01-01 as a timestamp. A string equal to any of those is quoted here.

One limit is worth stating plainly because no browser-based tool can avoid it. JSON.parse reads every number as a double-precision float, so an integer beyond 9,007,199,254,740,991 has already lost precision before any converter sees it. If your data contains large identifiers, keep them as strings in the JSON.

Nested JSON to YAML

Nesting depth is not a special case — each level simply adds one indentation step. Objects inside arrays inside objects convert correctly to any depth the browser's stack allows.

What changes with depth is readability, and this is where YAML earns its place. A five-level JSON document ends in a wall of closing braces that tells you nothing about which level you are looking at. The same document in YAML shows its shape at a glance, which is precisely why deployment configuration is written this way.

JSON to YAML for Kubernetes

Kubernetes accepts both JSON and YAML manifests — the API server treats them as the same thing — but almost everything written by hand or checked into a repository is YAML, because manifests are long, nested and benefit from comments.

It is worth being precise about what conversion does and does not give you. Converting a JSON document to YAML changes the notation only. It does not make the result a valid manifest. A Kubernetes resource still needs apiVersion, kind and metadata, plus a spec whose shape matches that particular resource's schema. If those fields are absent or wrong, the manifest is rejected regardless of how it is formatted.

Where conversion genuinely helps is turning something you already have into something readable: the JSON that kubectl get -o json printed, a manifest generated by a tool, or a Helm-rendered resource you want to inspect and edit. Convert it, remove the runtime fields the cluster added, and you have a starting point for a manifest you can maintain.

JSON to YAML for DevOps

Most of the configuration surface of a modern deployment pipeline is YAML. CI systems describe jobs and steps in it, container orchestration describes services and volumes in it, and infrastructure tooling frequently reads it. Working in that world means moving between the JSON that tools emit and the YAML that people maintain.

The common flows are the same everywhere. An API returns JSON that needs to become a config file. A tool exports its state as JSON and you want to read it. You are translating a configuration from one system to another and the two speak different notations. In each case what you need is a faithful structural conversion followed by human editing — not an automatic translation, because the field names and required shape belong to the target system, not to the notation.

One habit is worth forming: keep the JSON as the source of truth when a machine generates it, and keep the YAML as the source of truth when a person maintains it. Converting in both directions repeatedly, with hand edits at both ends, is how configuration quietly diverges.

JSON to YAML for configuration files

Configuration is where YAML's readability pays for its looser rules. Comments alone justify it: a setting whose value is not obvious can carry the reason next to it, which a JSON config physically cannot.

Two cautions apply when a converted document becomes a config file. First, unquoted values are inferred, so a version string such as 1.20 becomes the number 1.2 and loses its trailing zero — this converter quotes such values, but a hand edit afterwards can reintroduce the problem. Second, country codes are the classic trap: NO for Norway is read as the boolean false by YAML 1.1 parsers unless quoted.

How to validate JSON before conversion

Validation here is not a separate step you can forget — the document is parsed on every change, and conversion only happens when the parse succeeds. When it fails, the reason is reported with the line and column, and the offending line is shown with a caret under the exact position.

The errors worth knowing by sight are few. A trailing comma before a closing brace or bracket is the most common and is legal in JavaScript, which is why it slips through. Single quotes are not valid JSON — only double quotes are. Unquoted keys are equally invalid, however familiar they look from JavaScript object literals. And an unclosed brace or bracket usually reports at the very end of the document rather than where the problem started, so when the position looks wrong, count your brackets.

Notably, the output pane is not cleared when validation fails. Replacing a good result with an error message invites copying the error as if it were data, which is what the previous version of this page did.

Common JSON to YAML conversion problems

• Sequences inlined after their key. items: - one on one line is not valid YAML; the list has to start on the next line, indented.
• Array members misaligned. In an array of objects the keys after the first must align with the first, two columns right of the dash — not at the parent's indentation.
• Type-lookalike strings left unquoted. The single most damaging error, because the output parses cleanly and simply contains different data.
• Keys written raw. A key containing : silently becomes a nested mapping.
• Empty collections given a block. A key with nothing after it is null, not an empty object.
• Tabs used for indentation. Illegal in YAML, and the resulting error message rarely says so clearly.
• Very large integers. Already imprecise after JSON.parse; keep them as strings.

YAML formatting and indentation

Two spaces per level is the near-universal convention and the default here; four is available and equally valid. What matters is that the file is internally consistent, because indentation is structure and a mixed file is ambiguous to read even when it parses.

The dash of a sequence item is itself part of the indentation. Whether the sequence is indented under its key or kept at the same level as it are both legal, and parsers accept either; this converter always indents, which reads more clearly at depth.

Online versus local conversion tools

The real question about an online converter is where the data goes. Many send the document to a server to process it, which for a config file containing an endpoint, a token or an internal hostname is a genuine disclosure — the sort that happens without anyone deciding to do it.

This tool does everything in the page. The parse, the conversion and the download all run in JavaScript on your machine, and no request carries your data anywhere. Once the page has loaded you can disconnect entirely and it keeps working.

A local CLI is still the right answer for scripting, for files too large for a browser tab, and for anything that must run in CI. A browser tool is the right answer for the far more common case: you have a document in front of you, you want to see it in the other notation, and you want it now.

Frequently asked questions

Related developer tools

Other ToolAdda converters and formatters that run entirely in your browser.