YAML and JSON are both used heavily for configuration files and data interchange, and they are more closely related than they appear. In fact, every valid JSON document is also valid YAML — YAML is a superset of JSON. But the two formats have different strengths, and the choice between them usually comes down to the specific use case.

Why YAML feels different from JSON

YAML uses indentation to define structure instead of brackets and braces. This makes YAML feel closer to plain English for configuration files with lots of nesting, but it also introduces a class of errors that JSON cannot have: indentation bugs. A miscounted space in YAML can silently change what a value is nested under.

JSON is unambiguous about structure because the syntax is explicit. Every object is wrapped in {}, every array in [], every key is a quoted string. A JSON parser either accepts the document or tells you exactly what is wrong. YAML parsers tend to be more lenient and have more edge cases to be aware of.

YAML features that JSON does not have

• Comments. YAML supports # comments, which makes it significantly more useful for human-edited config files. JSON has no comment syntax at all — a common frustration when documenting configuration.
• Multi-line strings. YAML has two syntaxes for multi-line strings: the literal block style (|) which preserves newlines, and the folded style (>) which folds newlines into spaces. Both are far more readable than JSON's \n-escaped single-line strings.
• Anchors and aliases. YAML lets you define a value once with an anchor (&name) and reference it elsewhere with an alias (*name). This avoids repeating shared configuration across a large file.
• Unquoted strings. YAML infers the type of unquoted scalar values. This is convenient but also the source of one of YAML's most notorious bugs: the Norway Problem. The value NO was parsed as a boolean false in YAML 1.1 (because no was a boolean alias). YAML 1.2 fixed this, but tooling support for 1.2 is uneven.

Where each format is used

JSON is the standard for REST APIs, npm/package.json, TypeScript configuration, most NoSQL databases, and any context where data is consumed by code rather than edited by humans.

YAML is preferred for human-edited configuration: CI/CD pipelines (GitHub Actions, GitLab CI), Kubernetes manifests, Docker Compose files, Ansible playbooks, Helm charts, and OpenAPI specifications. The common thread is files that developers write and maintain by hand, where comments and readability matter more than parser simplicity.

Converting between YAML and JSON

Because YAML is a superset of JSON, converting JSON to YAML is always safe — you just need to decide how to format the output. Converting YAML to JSON is more nuanced:

• Comments are lost — JSON has no comment syntax.
• Anchors and aliases get expanded — the de-duplicated references become full copies.
• Multi-line strings get collapsed into single-line JSON strings with \n escapes.
• YAML allows keys that are not strings (integer keys, boolean keys). JSON requires string keys, so these must be coerced.

For simple config files without anchors or complex types, the conversion is lossless in practice. For complex YAML with custom types or anchors, review the output carefully.

The short answer

Reach for YAML when humans will edit the file and comments or multi-line strings matter. Reach for JSON when the file is consumed by tooling, APIs, or code, and you want unambiguous syntax with reliable parser support in every language. When you need to move data between the two, the main things to watch for are comments (which get dropped) and anchors (which get expanded).