JSON vs YAML: when to use which

JSON and YAML both represent structured data as plain text, and in most cases you could use either. In practice, the choice usually comes down to what's reading and writing the file.

JSON is the format of the web. It's what APIs speak, what JSON.parse() expects, and what every language has a fast, built-in parser for. Its strictness is a feature: no ambiguity about whitespace, no implicit type coercion surprises. The tradeoff is verbosity — every key and string needs quotes, every nested object needs braces, and there's no way to add a comment explaining why a value is set the way it is.

YAML trades some of that strictness for readability. Indentation replaces braces, quotes are often optional, and comments are allowed. That makes it a common choice for files humans edit directly and read often — CI pipelines, Kubernetes manifests, application config. The cost is that YAML's flexibility introduces genuine footguns: unquoted no or yes can be parsed as booleans instead of strings, and indentation errors fail silently in confusing ways.

A reasonable default: use JSON for anything machine-to-machine — API payloads, data interchange, anything a program writes and another program reads. Use YAML for anything a human is going to hand-edit regularly and where comments genuinely help — CI config, infrastructure-as-code, app settings a team tweaks by hand.

If you're going back and forth between the two, running a file through a formatter first (like the JSON formatter) makes it much easier to spot structural mistakes before they cause a parsing error somewhere downstream.