JSON vs YAML: What's the Difference and How to Convert

Published July 18, 2026

JSON and YAML are two ways to write the same thing: structured data made of objects, lists, strings, numbers and booleans. JSON wraps it in braces and commas; YAML uses indentation and line breaks. Because they model identical structures, you can convert between them losslessly — but there are a few traps worth knowing.

The same data, two styles

JSON:

{ "name": "Yunknow", "tags": ["free", "fast"], "active": true }

YAML:

name: Yunknow
tags:
  - free
  - fast
active: true

Same data, different clothes. YAML drops the punctuation and leans on indentation, which is why config files love it.

When to use which

JSON — APIs, package.json, anything a program reads or writes automatically. Strict, unambiguous, universally supported.
YAML — config you edit by hand: Docker Compose, Kubernetes, GitHub Actions, CI pipelines. Easier to read, supports comments.

A common workflow is to write config in YAML and have tools consume it as JSON.

Gotchas that trip people up

Indentation is significant in YAML. Mixing tabs and spaces, or getting the depth wrong, changes the meaning or breaks the parse. Always indent with spaces.
Comments vanish going to JSON. JSON has no comment syntax, so # note lines are lost when you convert YAML → JSON. That’s expected, not a bug.
The “Norway problem.” In older YAML, unquoted no, yes, on, off become booleans — so the country code NO can turn into false. Quote strings that look like booleans.
Anchors get expanded. YAML’s &anchor/*ref reuse is flattened into plain data when converting to JSON.

Feature comparison

Feature	JSON	YAML
Comments	No	Yes (`#`)
Trailing commas	Not allowed	Not applicable
Human readability	Good	Better for deep nesting
Parsing speed	Faster	Slower
Multi-line strings	Escaped `\n` only	Block scalars
Multiple docs per file	No	Yes (`---` separators)

One underused YAML feature is block scalars for long text — a literal block keeps line breaks, a folded block joins them into one line:

description: |
  Line one stays a line.
  Line two stays a line.
summary: >
  This wraps across
  several source lines
  but becomes one line.

Frequently asked questions

Is YAML a superset of JSON? Effectively yes. As of YAML 1.2, any valid JSON document is also valid YAML, so a YAML parser can read JSON directly. The reverse isn’t true — JSON can’t parse YAML’s indentation syntax.

Which should an API return? JSON, almost always — it’s faster to parse, unambiguous and supported everywhere. Keep YAML for files humans edit by hand.

Where did my comments go after converting? They’re dropped, because JSON has no comment syntax. If you need to keep notes, add a real "_comment" key instead. For a deeper look at the format itself, see what is JSON.

Convert safely, in your browser

The JSON ⇄ YAML converter turns one into the other and checks the syntax as it goes — pointing to the exact error if something is off. It runs entirely in your browser, so even private config never leaves your device.

To beautify, minify or validate JSON, use the JSON formatter.
To move tabular JSON into a spreadsheet, use JSON ⇄ CSV ⇄ Excel.

#dev#json#yaml