Same data, two very different-looking formats
YAML and JSON both represent structured data — objects, arrays, strings, numbers, booleans — but they look almost nothing alike. JSON is brackets and quotes; YAML is indentation and bare words. Most tools that consume one can consume the other, since both map cleanly onto the same underlying data structures. The choice between them usually comes down to who's reading the file and how it's being used.
Here's an identical configuration expressed in both formats. JSON:
{
"name": "api-service",
"port": 8080,
"features": ["auth", "logging", "metrics"],
"database": {
"host": "localhost",
"pool_size": 10
}
}
The same thing in YAML:
name: api-service port: 8080 features: - auth - logging - metrics database: host: localhost pool_size: 10
No braces, no brackets, no trailing commas, no quotes around keys or most string values. Structure comes entirely from indentation and line breaks.
YAML ("YAML Ain't Markup Language") was designed specifically to be easier for humans to read and write by hand. Config files that people edit directly — Docker Compose files, Kubernetes manifests, CI/CD pipeline definitions (GitHub Actions, GitLab CI), Ansible playbooks — are almost universally YAML, because the format reduces visual noise for content a person is going to type and edit repeatedly.
JSON, by contrast, was designed as a data interchange format — something machines generate and parse — and its explicit, unambiguous syntax (every string quoted, every structure bracketed) makes it easier to parse reliably and harder to mis-indent by accident.
# starts a comment anywhere in a YAML file; JSON has no comment syntax at all&name defines a reusable block and *name references it elsewhere, avoiding repetition in large config files--- separates multiple YAML documents within a single file, common in Kubernetes manifests that define several resources at once| and > block scalar indicators let you write multi-line text blocks cleanly, useful for embedded scripts or long descriptionsYAML's flexibility comes at a cost. Indentation-based structure means a single misplaced space silently changes what a file means rather than throwing an obvious syntax error. Some notorious YAML gotchas:
version: 1.0 may not parse the way you expect depending on the parser, and famously, country: NO can be interpreted as the boolean false in some YAML 1.1 parsers rather than the string "NO" (Norway's ISO code) — this is widely known as the "Norway problem"JSON's verbosity is, in a sense, a feature: because everything must be explicit, there's less room for a file to mean something other than what it looks like it means.
When editing YAML by hand, configure your editor to show whitespace characters and convert tabs to spaces automatically — this alone prevents the most common class of YAML bugs. When converting YAML to JSON for validation purposes, remember that YAML's type inference (unquoted "true", "yes", numbers, dates) can produce a JSON value of a different type than you intended; quoting ambiguous scalars in the source YAML avoids surprises after conversion.
Is YAML a superset of JSON? Almost — valid JSON is (with minor exceptions) also valid YAML, since YAML 1.2 was designed to be JSON-compatible. The reverse isn't true: most YAML files aren't valid JSON.
Which is better for API responses? JSON, almost always — it's more compact for machine transfer, has near-universal parser support, and its lack of ambiguity matters more for data flowing between systems than for files a person edits.
Can comments survive a YAML-to-JSON conversion? No — JSON has no comment syntax, so any comments in the source YAML are necessarily dropped during conversion.
Use the DataBench YAML ⇄ JSON converter to convert either direction instantly, right in your browser — no server, no upload, no account. It preserves nested structures, arrays, and key order in both directions, and flags invalid indentation before it silently produces the wrong structure.