YAML vs JSON: what is the difference
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.
The same data in both
Here is one small document written both ways, JSON first and then YAML:
{
"name": "web",
"ports": [80, 443],
"debug": false
}
name: web
ports:
- 80
- 443
debug: falseSide by side
| Feature | JSON | YAML |
|---|---|---|
| Structure | Braces, brackets and commas | Indentation and dashes |
| Comments | Not allowed | Start with # |
| Quotes on keys and text | Always double quotes | Usually optional |
| Reusing a value | Not possible | Anchors and aliases |
| Several documents in a file | No | Separated by --- |
| Multi-line text | Written with \n escapes | Block styles with | and > |
When to use which
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.
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
Reusing values
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
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.
What is lost when you convert
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.