YAML vs JSON: Which Should You Use?

YAML and JSON describe the same kinds of data: scalars, lists, and maps. In fact every JSON document is valid YAML. So the choice between them is rarely about capability and almost always about audience, tooling, and failure modes. Here is how to decide.

Readability and human editing

YAML wins decisively for files humans edit by hand. It uses indentation instead of braces, drops most quotes and commas, and reads top to bottom like an outline. A Kubernetes manifest or a CI pipeline in YAML is far easier to scan than the equivalent wall of brackets. JSON, by contrast, is noisy for a person but trivial for a machine.

This is why the rule of thumb holds up: YAML for configuration that people maintain, JSON for data that programs exchange.

Comments

YAML supports comments with the hash symbol. JSON does not, full stop. If you need to annotate a config file, explain why a value was chosen, or temporarily disable a block, JSON forces ugly workarounds while YAML handles it naturally. For long-lived config this alone often decides it.

Data types and the gotchas

JSON has a small, unambiguous type set: string, number, boolean, null, array, object. What you write is what you get. YAML tries to be helpful and infers types, which is where it gets dangerous.

The most infamous case is the Norway problem. The country code for Norway is NO, and YAML interprets the unquoted word no as the boolean false. So a list of country codes silently turns Norway into false. The same happens with words like yes, on, off, and y. Version numbers like 1.20 lose their trailing zero because they are parsed as floats, and a value like 0x10 may become a number. The defense is simple: quote any string that could be mistaken for something else.

Failure modes

JSON fails loudly. A missing brace produces an immediate parse error. YAML fails quietly. A single misplaced space changes the structure without raising an error, so your config is valid YAML but means something you did not intend. Mixing tabs and spaces is forbidden and is a frequent source of confusion. Deeply nested YAML also gets hard to follow because the indentation cues blur.

Tooling and interchange

Every language and every HTTP API speaks JSON natively. It is the lingua franca of web services. YAML needs a library, and parser behavior varies between implementations, especially around type coercion and anchors. For data crossing a network boundary, JSON is the safer, faster, more universal choice.

Practical recommendation

Use YAML for human-authored configuration: CI pipelines, infrastructure manifests, app settings. Use JSON for APIs, logs, caches, and anything serialized by code for code. Many teams keep config in YAML and convert to JSON in their build step to get the best of both.

When you need to move between the two, you do not have to do it by hand. Paste your config into JSON to YAML to make a machine payload readable, or use YAML to JSON to feed a config file into a program that only understands JSON. Both run entirely client-side in your browser, so infrastructure files containing internal hostnames, secrets, or environment details never leave your machine.

Neither format is better in the abstract. Match the format to who or what is reading it, quote your ambiguous YAML strings, and let a converter handle the round trip.