What is the difference between JSON and YAML?

JSON uses braces, brackets and quotes and has no comments. YAML uses indentation, usually needs fewer quotes, and supports comments, anchors and multi-line text.

Is YAML a superset of JSON?

In practice yes. A JSON document is nearly always valid YAML, so a YAML reader can read it.

Which is better for configuration files, JSON or YAML?

YAML is easier for people to edit and comment, so it is common for configuration. JSON is stricter and faster to parse, so it suits data exchange.

Can YAML comments be kept when converting to JSON?

No. JSON has no comments, so they are lost in the conversion.

JSON vs YAML: Differences, When to Use Each and Common Pitfalls

How the two formats differ, which one fits which job, what goes wrong with YAML, and how to convert between them safely.

Need to convert now? Use the JSON YAML converter.

The short answer

Use JSON when programs exchange data: APIs, browsers and stored data. Use YAML when people write and read the file: configuration, pipelines and infrastructure. YAML is also a superset of JSON in practice, so a JSON file is nearly always valid YAML as well.

The same data in each

// JSON
{
  "service": "web",
  "replicas": 3,
  "env": ["PROD", "EU"],
  "limits": { "cpu": "500m", "memory": "256Mi" }
}

# YAML
service: web
replicas: 3
env: [PROD, EU]
limits:
  cpu: 500m
  memory: 256Mi

Side by side

	JSON	YAML
Structure marked by	Braces, brackets and commas	Indentation and dashes
Comments	Not allowed	Yes, with #
Quotes on strings	Always required	Usually optional
Data types	String, number, boolean, null, object, array	The same, plus timestamps, binary and sets in some readers
Multi-line text	One line with \n	Block scalars with \| and >
Reuse	None	Anchors, aliases and merge keys
Several documents in a file	No (JSON Lines does it)	Yes, separated by ---
Parsing speed	Fast, and built into every language	Slower, needs a library
Grammar	Small and strict	Large and flexible
Easy to get wrong	A missing comma or quote	Indentation and values that look like other types

Where each one is used

JSON: web APIs, package.json, tsconfig.json, browser storage, data files that programs generate.
YAML: Kubernetes manifests, Docker Compose, GitHub Actions and other pipelines, Ansible, OpenAPI descriptions, and many application config files.

When to choose JSON

Machines read and write the data most of the time.
You want strict, predictable parsing with the same result everywhere.
The file travels over a network.

When to choose YAML

People edit the file by hand, and comments help them.
The file has long text, many nested settings or repeated blocks.

YAML traps

The Norway problem. In YAML 1.1, used by some readers such as PyYAML, the unquoted values no, yes, on, off and n are booleans. The country code NO becomes false. Quote such values.
Numbers that are not numbers. A version 1.10 becomes the number 1.1. A value like 0755 can be read as octal. Quote versions and codes.
Dates. 2024-05-01 can become a date object in some readers and text in others.
Indentation. Tabs are not allowed for indentation, and one wrong space changes the structure without an error.
Special characters. A value that contains : or starts with #, *, &, ! or @ must be quoted.
Duplicate keys. Some readers fail, and some keep the last value without saying anything.

Safety

Read YAML from untrusted sources with a safe loader. Some YAML libraries can create arbitrary objects from tags in the file, which can run code. In Python use yaml.safe_load, and in other languages use the loader that supports only plain data. JSON has no such feature.

Converting between them

Going from JSON to YAML is lossless: every JSON value has a YAML form. Going from YAML to JSON can lose things that JSON does not have: comments disappear, anchors are expanded into copies, timestamps become text, and extra documents have to go into an array. The converter tells you about these cases.

# Python
import json, yaml
with open('config.yaml') as f:
    data = yaml.safe_load(f)
print(json.dumps(data, indent=2))
print(yaml.safe_dump(data, sort_keys=False))

// Node.js with the js-yaml package
const yaml = require('js-yaml');
const data = yaml.load(yamlText);
const json = JSON.stringify(data, null, 2);
const back = yaml.dump(JSON.parse(json));

# Command line with yq (mikefarah/yq v4)
yq -o=json config.yaml
yq -P config.json

Tools on this site

JSON YAML converter, JSON to YAML and YAML to JSON.
YAML validator, YAML formatter and the YAML syntax guide.
JSON diff to compare two files, and the JSON vs XML and CSV vs JSON guides.

JSON vs YAML