YAML vs JSON: picking the right format for config files

YAML and JSON can represent the same data — objects, arrays, strings, numbers, booleans, null — so the choice between them for a config file usually comes down to one question: who's going to read and hand-edit this file, and how often?

YAML optimizes for humans editing by hand

YAML's indentation-based structure, lack of required quotes on simple strings, and support for comments make it noticeably easier to read and edit by hand than JSON. debug: true with a trailing # enable in staging only comment is something JSON simply cannot express — JSON has no comment syntax at all, which is one of the most common frustrations people run into when a JSON config file needs a note explaining a non-obvious value.

JSON optimizes for machines generating and parsing

JSON's strict, minimal grammar is exactly why it's the default for API payloads and generated config: there's essentially one way to write any given piece of data, which makes it trivial to generate programmatically and unambiguous to parse. YAML's flexibility — multiple ways to write the same string, significant whitespace, implicit typing — is a real liability when a file is being generated by code rather than typed by a person, since subtle formatting differences can produce semantically different results.

YAML's implicit typing is the sharpest edge

This is the trap that's caught entire engineering teams: YAML tries to infer types from unquoted values, and its inference rules have surprising edge cases. The bare word no parses as the boolean false in YAML 1.1 (used by many popular YAML parsers), not the string "no" — so a config value like country: NO (Norway's ISO code) can silently become country: false. The fix is simple once you know about it — quote any value that could be misread as a boolean, number, or null ("no", "yes", "null", "NO") — but it's easy to be bitten by once.

A reasonable default

• Config files humans edit directly (Docker Compose, CI pipelines, Kubernetes manifests) — YAML, because the comment support and readability wins outweigh the typing gotchas, provided ambiguous values get quoted.
• Config or data generated/consumed by code (API responses, machine-to-machine payloads, anything round-tripped programmatically) — JSON, because strict unambiguous parsing matters more than human readability.
• Uncertain, or need to hand off between the two — pick one canonical format and convert for display, rather than maintaining the same config in both.

Our YAML formatter and XML to YAML converter run locally in your browser — useful for reformatting or sanity-checking a config file without pasting it into a third-party site.