Skip to main content
ToolsByUs

JSON vs YAML

JSON is the interchange format: strict, comment-free, and understood by every API and parser. YAML is the human-config format: indentation-scoped, comment-friendly and typable by hand. Pick JSON for programs talking to programs and YAML for people writing to programs — and convert losslessly either way.

Local-only

JSON vs YAML explained

The two formats are often introduced as rivals, which obscures the useful truth: they solve different problems, and most real projects use both. JSON won data interchange because its grammar fits on an index card and because a payload that one service emits, another can consume with no shared configuration. YAML won configuration because the people editing it are humans in a text editor, and humans want comments, readable lists, and the freedom to skip quote marks.

The cost of that human-friendliness is a spec YAML's own authors describe as complicated: indentation carries meaning, the type of a bare scalar is inferred (and the classic failure is a value like `no` silently becoming boolean false), and a file can parse while meaning something its author never intended. JSON's strictness is exactly what makes it boring — a number is a number, a string is a string, and no editor can reformat your file into a different document.

The comparison below stays at the level where the trade-offs actually bite: syntax rules, typing behaviour, comments, size, and the tooling each format assumes. When you need to cross between them, both directions have honest converters on this site — and like everything here, they run entirely in your browser.

Tabulating config for a spreadsheet review is a common step, and the YAML to CSV converter does it without leaving the tab.

Need the exact conversion this page compares? The YAML to JSON converter runs the parse-and-emit cycle in your browser, nothing uploaded.

Syntax: punctuation versus indentation

JSON's grammar uses six structural characters — brackets, braces, colon and comma — so a document's nesting is visible in its punctuation and a linter can point at the exact character that is wrong. YAML spends its punctuation budget on readability instead: nesting is indentation, lists are dashes, and key/value pairs need no separator beyond a colon and a space. The result is that a five-line JSON document becomes two lines of YAML, and a deeply nested one becomes dramatically shorter — at the price of an entire error class JSON does not have, the wrong-number-of-spaces failure that some parsers report on a line nowhere near your mistake.

AspectJSONYAML
Scope markerBraces and bracketsIndentation (spaces only)
CommentsNone — stripped by design# to end of line
QuotingRequired on every stringOptional for most scalars
Multi-line strings\n escapes onlyBlock scalars (| and >)
Anchors / reuseNoneAnchors & and aliases *
Grammar sizeFits on one page (RFC 8259)Multi-stage, famously complex

Types: strict versus inferred

Every JSON value declares itself: strings wear quotes, numbers are bare, booleans are exactly true and false. YAML infers. A bare yes, no, on, off, true or false is a boolean; a bare 2026-09-19 is a date; and a value like 1.20 can silently become the number 1.2 depending on the reader. The failure has a name in the community — the Norway problem, after country codes like NO becoming boolean false — and it is the single strongest argument for quoting defensively in YAML even when the parser does not demand it.

The flip side is deliberate: YAML wants configuration files where 8080 reads as a port number without ceremony. JSON wants interchange, where the emitter and the consumer must agree on every byte, and inference is a bug. Each format optimises for the reader it expects.

Size, performance and tooling

YAML is usually the shorter file and the slower parse: indentation scanning, multi-line block scalars and anchor resolution all cost more than JSON's single-pass grammar. For configuration read once at startup this is irrelevant; for a wire format streamed millions of times a day it is exactly why YAML never displaced JSON on the wire. Tooling is the other asymmetry — every language ships a JSON parser in its standard library, while YAML parsers are third-party with real differences in what they accept, which is why this converter documents its supported subset instead of promising the full spec.

  • Payload size: YAML wins on hand-written files; JSON with minification often wins on the wire, because its quoting rules compress predictably.
  • Error messages: JSON parsers point at the offending character; YAML parsers point at the line the indentation stopped matching.
  • Interoperability: JSON is the default everywhere — log pipelines, HTTP APIs, browser storage. YAML is the default in Kubernetes, CI pipelines and Ansible.
  • Round-tripping: JSON→YAML→JSON is lossless with a compliant pair. YAML→JSON can be lossy the moment the file used features JSON lacks — anchors, multiple documents or non-string keys.

When to pick which

The decision is rarely about preference and usually about the reader. Pick JSON when a program produces the document and another program consumes it: API payloads, structured logs, stored state, anything that crosses a trust boundary. Pick YAML when a human writes and maintains the document: CI pipelines, Kubernetes manifests, docker-compose files, any config where a reviewer needs to read a diff and understand it without decoding punctuation.

And the guidance reverses cleanly: if you catch yourself hand-formatting JSON with fifteen levels of nesting, that file probably wants to be YAML. If you find yourself parsing YAML at runtime inside a service, that file probably wants to be JSON. The converters linked below make the crossing a one-click step rather than a migration project.

Frequently asked questions

Is YAML a superset of JSON?

YAML 1.2 explicitly made most JSON documents valid YAML — a JSON file with its braces intact usually parses as YAML unchanged. The reverse is never true: comments, anchors, bare keys and multi-line strings have no JSON representation. So the migration path is one-directional by design, and tools that claim full YAML→JSON fidelity are quietly choosing a subset.

Which format is faster to parse?

JSON, by a wide and consistent margin. Its grammar is single-pass with no indentation state; YAML scanners track column context, resolve block scalars and expand anchors. For startup-time configuration the difference is milliseconds and irrelevant; for high-volume machine-to-machine traffic it is one of the two reasons JSON owns the wire (the other being universal standard-library support).

Why do CI systems and Kubernetes use YAML instead of JSON?

Because their documents are written and reviewed by humans. YAML's comments let a manifest explain itself inline, indentation keeps deep resource specs readable, and diffs show intent clearly. The same properties that make YAML risky for interchange — inference, indentation sensitivity — are strengths for hand-maintained config.

What is the Norway problem in YAML?

Several YAML parsers type bare scalars by inference, so a country code like NO (Norway) parses as boolean false, and off or on become booleans too. The fix is quoting any value that should stay a string. JSON is immune by construction — unquoted means number or boolean, quoted means string, with no inference step to get wrong.

Can converting YAML to JSON lose data?

It can, in three documented cases: multiple documents in one file (only the last survives a single-document converter), anchors and aliases (they must be expanded, which duplicates content), and non-string keys. This site's converters reject or clearly report those cases rather than silently reshaping the document.

Should I indent YAML with 2 or 4 spaces?

Both are valid — YAML forbids tabs, not a space count — but 2 spaces is the overwhelming convention in Kubernetes, CI and Docker ecosystems, and mixing widths inside one file is how indentation errors are born. Pick 2, enforce it with your editor, and every diff will stay readable.

ToolsByUs team · How we check our tools