JSON vs YAML: Differences and How to Convert

JSON and YAML can describe the same data: objects, lists, strings, numbers and true/false values. JSON is the standard for APIs. YAML is popular for configuration files such as Docker Compose, Kubernetes and GitHub Actions. Knowing how they differ helps you pick one and convert safely.

The same data in both

// JSON
{
  "name": "nova",
  "ports": [80, 443],
  "debug": false
}

# YAML
name: nova
ports:
  - 80
  - 443
debug: false

Main differences

	JSON	YAML
Structure	Braces, brackets and commas	Indentation and dashes
Comments	Not allowed	Yes, with `#`
Quotes on strings	Always double quotes	Usually optional
Readability	Good for machines, noisy for people	Easier to read and edit by hand
Strictness	Very strict, easy to parse	Flexible, easier to get subtly wrong
Typical use	APIs, data exchange, JS apps	Config files, CI pipelines, Kubernetes

YAML is a superset of JSON in most practical cases, so many parsers read JSON as YAML.

Convert JSON to YAML in your browser, keeping the structure intact.Open JSON to YAML →

YAML gotchas

Indentation is meaning. Use spaces, not tabs, and keep the same width. One extra space can change the structure.
Unquoted values can change type. no, off or yes may be read as booleans by some parsers (the “Norway problem”: the country code NO became false). Quote values like these.
Numbers with leading zeros such as 0123 can be read as octal. Quote them if they are IDs.
Colons and hashes in text. A value containing : or # needs quotes.

JSON gotchas

No trailing commas and no comments. Errors are explained in common JSON errors.
Keys must be double-quoted strings.
Big integers beyond 2⁵³ lose precision in JavaScript.

Which should I use?

API responses and requests: JSON.
Files that people edit and comment: YAML.
Data between programs, where safety and speed matter: JSON, with a format check using the JSON Formatter.

To go back, use YAML to JSON. Comments in YAML cannot be kept in JSON, so they are dropped.

Frequently asked questions

Is YAML better than JSON?

Neither is better overall. YAML is nicer to write by hand and JSON is safer to exchange between systems.

Does converting lose anything?

Comments and YAML anchors are not kept when you convert to JSON. The data values themselves are.

JSON vs YAML: differences, when to use each and how to convert