QuikTool

YAML vs JSON: what is the difference

Published · Updated

YAML and JSON describe the same kind of data: objects, lists, text, numbers, true and false and null. JSON is strict and made for programs to exchange. YAML is looser and made for people to write, which is why so many configuration files use it. Knowing the differences tells you which to pick and what happens when you convert.

Try it now: YAML to JSON & JSON to YAML, JSON Formatter & Validator.

What does the same data look like in YAML and JSON?

Here is one small document written both ways, JSON first and then YAML: The YAML to JSON converter converts either way.

{
  "name": "web",
  "ports": [80, 443],
  "debug": false
}

name: web
ports:
  - 80
  - 443
debug: false

How do YAML and JSON compare side by side?

FeatureJSONYAML
StructureBraces, brackets and commasIndentation and dashes
CommentsNot allowedStart with #
Quotes on keys and textAlways double quotesUsually optional
Reusing a valueNot possibleAnchors and aliases
Several documents in a fileNoSeparated by ---
Multi-line textWritten with \n escapesBlock styles with | and >

When should I use YAML and when JSON?

Use JSON for data that programs exchange, such as API requests and responses. It is strict, every language reads it, and a parser has very little room to guess. Use YAML for files that people edit by hand, such as deployment and build settings, where comments and a clean layout matter. Many tools accept both, so you can keep data in JSON for your programs and convert it to YAML when a person needs to read or edit it. The JSON guide lists the mistakes that break JSON.

How does YAML handle multi-line text?

In JSON, text with line breaks has to be written on one line with \n escapes, which is hard to read. YAML has block styles: a | keeps the line breaks exactly as written, and a > folds the lines into a single paragraph. A script or a certificate in YAML therefore reads like plain text.

message: |
  first line
  second line

How do I reuse values in YAML?

An anchor, written &name, labels a value, and an alias, written *name, reuses it. The merge key << copies a whole mapping into another. This keeps repeated settings in one place, and it is a feature JSON does not have.

defaults: &defaults
  retries: 3
service:
  <<: *defaults
  name: web

What are the pitfalls of YAML?

YAML’s flexibility is also where it goes wrong. Indentation carries meaning, and only spaces are allowed, never tabs. Unquoted values are guessed to be numbers, booleans or text, and the guess can surprise you. A version written as 1.10 is read as the number 1.1. In the older YAML 1.1, unquoted yes, no and on were read as booleans, which famously turned the country code NO into false. YAML 1.2 fixed that, but many tools still use 1.1, so quote any value that must stay text.

Is JSON valid YAML?

Almost always. YAML 1.2 was designed so that nearly every JSON document is also valid YAML, which is why a YAML parser can read a JSON file. The JSON formatter checks the JSON side.

What is lost when I convert YAML to JSON?

Converting YAML to JSON loses comments and turns anchors and aliases into plain copies. JSON to YAML loses nothing. YAML to JSON can lose information: comments are dropped because JSON has no comments, anchors and aliases are expanded into repeated values, and a file with several documents becomes a JSON array. A good converter tells you when this happens and reports the line and column of any syntax error.

Sources

Frequently asked questions

Is YAML better than JSON?
Neither is better overall. YAML is easier for people to read and edit, and JSON is stricter and simpler for programs. Pick the one that fits who or what reads the file.
Can YAML have comments?
Yes, anything after a # on a line is a comment. This is one of the main reasons people choose it for configuration.
Why did my YAML value change type?
Unquoted values are interpreted. If something must stay text, such as 1.10, a version or a country code, put it in quotes.

Try the tools

See all guides