YAML vs JSON: Picking a Config Format

YAML and JSON encode the same data model, so the choice between them is rarely about capability. It is about who writes the file and who reads it: hand-edited configuration favors YAML's comments and quiet syntax, while machine-to-machine interchange favors JSON's strictness and universal parsers. This article compares what each format is good at, catalogs the specific places YAML bites, does the same for JSON, and closes with a decision table. To move data between the two without losing a value to a parser quirk, use the YAML to JSON converter.

What each format is good at

JSON is a strict data format: quoted keys, double-quoted strings, no comments, no ambiguity. Every language ships a parser, the spec is small, and there is exactly one way to write any value.

YAML is a superset of JSON with indentation-based structure, comments, and a large set of conveniences: anchors and aliases, multi-line strings, unquoted scalars. It is designed for humans to write and maintain, which is why CI systems, Kubernetes manifests, and Docker Compose files all speak it. The same flexibility that makes it pleasant to write is what makes it hazardous to parse — YAML 1.1 and 1.2 implementations disagree on details, and the convenience rules have sharp edges.

Where YAML bites: indentation, tabs, anchors

Indentation must be spaces; a single tab is a parse error, and editors insert tabs invisibly often enough that this remains a top support question. Keep to two spaces per level.

Implicit typing is the deeper trap. YAML 1.1 interprets unquoted NO, FALSE, and OFF as booleans — the famous Norway problem, where country_code: NO parses as false. Unquoted 1.0 becomes a float, and a version like 08 can fail as invalid octal in some parsers. Quote anything that is semantically a string, especially codes, versions, and IDs.

Anchors and aliases (& and *) let you reuse blocks, which is powerful but means a file's effective content depends on merge keys (<<) that readers frequently misread. And duplicate keys are technically errors, yet several popular parsers accept them silently, with the last value winning.

Where JSON bites: no comments, strict commas

JSON's failure modes are quieter. There are no comments, so JSON config files accumulate sibling README files or "_comment" keys that pollute the schema. Trailing commas are fatal, which is the bane of hand-editing, and strict quoting rules mean single-quoted strings and unquoted keys are invalid. A missing comma between members is the most common hand-editing error of all.

Parsers also differ on duplicate keys — last-wins in most implementations, an error in strict ones — and on numbers. JSON has a single number type, so 1 and 1.0 are distinct tokens that map to the same value in most languages, and large integers silently lose precision past 2^53 in JavaScript. For config, that means snowflake-style IDs beyond 9,007,199,254,740,992 must be strings.

A decision table

The practical rule: if humans will edit it in pull requests, choose YAML; if programs will parse it at runtime, choose JSON. Either way, validate on commit — the YAML to JSON converter and the JSON/YAML validator catch the class of error that turns a config file into a stack trace.