Skip to main content
DevCodivo

YAML vs JSON: which should you use, and when?

7 min read

JSON and YAML describe the same kind of data in very different styles. Here's a side-by-side comparison and a rule of thumb for choosing.

JSON and YAML both describe structured data, the same objects, arrays, strings and numbers, but in very different styles. The short version: use JSON for data that machines exchange (APIs, message payloads), and use YAML for files that people write and read by hand (configuration). Here’s why.

The same data, side by side

An identical configuration in each format:

# JSON
{
  "service": "api",
  "port": 8080,
  "features": ["auth", "logging"],
  "debug": false
}

# YAML
service: api
port: 8080
features:
  - auth
  - logging
debug: false

JSON marks structure with {}, [], commas and quotes. YAML marks it with indentation and dashes, and drops most of the punctuation. Neither is “better” in the abstract; they optimise for different readers.

The differences that actually matter

  • Comments. YAML has them (#); JSON does not. For a config file people maintain, this alone often decides it.
  • Readability. YAML’s lack of braces and quotes makes long files easier to scan. JSON’s punctuation makes structure unambiguous at the cost of noise.
  • Strictness. JSON has one obvious way to write things. YAML is flexible, sometimes too flexible (see the gotchas below).
  • Whitespace. In JSON, indentation is cosmetic. In YAML it is structural: a wrong indent changes the meaning or breaks the parse.
  • Support. Every language parses JSON out of the box. YAML usually needs a library.
  • Speed. JSON parses faster, which matters for high-volume machine traffic and not at all for a config file loaded once at startup.

YAML’s famous gotchas

YAML’s convenience has sharp edges. The classic is the “Norway problem”: unquoted no can be read as the boolean false, so a list of country codes containing NO can surprise you. Numbers with leading zeros, version strings like 1.10, and times can all be coerced into the wrong type. When in doubt, quote the value.

A rule of thumb

Reach for JSON when a program is producing or consuming the data and no human needs to edit it, such as API responses, tokens and logs. Reach for YAML when a human is the primary author and comments and readability help, such as CI pipelines, Kubernetes manifests and app config. And because valid JSON is also valid YAML, you can always start in one and convert.

Need to move between the two? Our free YAML to JSON converter (and the JSON to YAML direction) translates instantly in your browser, so you can keep the format each job calls for.

Frequently asked questions

What is the main difference between YAML and JSON?
They describe the same kinds of data (objects, arrays, strings, numbers, booleans), but JSON uses braces and brackets while YAML uses indentation and dashes. JSON is stricter and more universal; YAML is easier for people to read and edit, and it supports comments.
Is YAML a superset of JSON?
Effectively yes. Modern YAML parsers accept valid JSON, because JSON's syntax is a subset of what YAML allows. That means you can paste JSON into a YAML file and it will usually parse, though the reverse is not true.
Should I use YAML or JSON for config files?
YAML is usually the friendlier choice for human-edited configuration because of comments and less punctuation. JSON is the better choice for machine-to-machine data such as API responses, where strictness and universal support matter more than readability.
Does JSON support comments?
No. Standard JSON has no comment syntax, which is one reason config files often prefer YAML (which uses # for comments). Some tools accept a non-standard 'JSONC' with comments, but plain JSON parsers will reject them.

Keep reading

← All posts