DATATRANSFORMER · GUIDE

JSON vs YAML: differences and when to use each

JSON and YAML can describe the same data, but they are optimised for different jobs. This comparison helps you pick the right one and convert safely between them.

The same data in both formats

Here is a small service configuration written in JSON:

{
  "service": "billing",
  "replicas": 3,
  "debug": false,
  "ports": [8080, 9090],
  "database": { "host": "db.internal", "pool": 10 }
}

And the equivalent YAML:

service: billing
replicas: 3
debug: false
ports:
  - 8080
  - 9090
database:
  host: db.internal
  pool: 10

Both describe an object with strings, numbers, a boolean, a list and a nested object. In fact, YAML 1.2 was designed so that every JSON document is also valid YAML. The difference lies in how people and programs work with each format. You can switch between them with the JSON ↔ YAML converter.

Where JSON is the better choice

Data exchange between programs. Every mainstream language has a fast, built-in JSON parser, and the grammar is small enough that different parsers agree on the result. That makes JSON the default for REST APIs, webhooks, message queues and logs.
Generated files. When software writes a file, explicit braces and quotes remove any doubt about structure, and there is no indentation to get wrong.
Predictable types. In JSON, "3" is a string and 3 is a number. There is no type guessing.
Security and simplicity. A JSON parser cannot execute code or construct arbitrary objects. Some YAML libraries historically supported language-specific tags that could create objects, which led to vulnerabilities when untrusted YAML was loaded with unsafe settings.

Where YAML is the better choice

Files people edit by hand. YAML has less punctuation, so configuration is easier to read and review in a pull request.
Comments. YAML supports # comments, which are valuable for explaining why a setting has a particular value. JSON has no comments at all.
Multi-line text. Block scalars (| keeps line breaks, > folds them) make scripts, certificates and long descriptions readable.
Reuse within a file. Anchors (&name) and aliases (*name) let you define a block once and refer to it several times.

This is why CI pipelines, Kubernetes manifests, Docker Compose, Ansible playbooks and OpenAPI specifications are commonly written in YAML.

The costs of YAML's flexibility

YAML's readability comes from inferring structure and types from layout and plain text, which introduces risks JSON does not have:

Indentation is structure. Moving a line two spaces to the left can make it belong to a different parent object without causing a parse error.
Implicit types. An unquoted 1.10 is the number 1.1, and some parsers read no as the boolean false. Values that must remain strings should be quoted.
Tabs are not allowed for indentation, which can cause confusing errors when an editor inserts them.
Larger specification. YAML has many features, and not every library implements them identically, so the same file can occasionally be interpreted differently by two tools.

The guide YAML gotchas explains these cases with examples.

Converting between them safely

Converting JSON to YAML is lossless: you get the same data with YAML syntax. Converting YAML to JSON keeps the data but drops anything that is only presentation. Comments are removed, aliases are expanded into full copies, and block-scalar formatting is replaced by escaped strings. If you convert a commented YAML file to JSON and back again, the comments will not return, so keep the original YAML as the source of truth.

A useful habit when reviewing an unfamiliar YAML file is to convert it to JSON and look at the result. Any surprising type or misplaced indentation becomes obvious when the structure is shown with explicit braces and quotes. You can then format and inspect that output with the JSON formatter.

Quick decision guide

Machines produce and consume it: JSON.
People maintain it and need comments: YAML.
It must be parsed identically by many different tools: JSON.
The ecosystem already standardises on one format, such as Kubernetes or package.json: follow the ecosystem.