JSON vs YAML: What Is the Difference?

JSON:

{
  "name": "Ada Lovelace",
  "born": 1815,
  "active": true,
  "languages": ["English", "French"],
  "address": { "city": "London" }
}

YAML:

# the same data, with room to explain itself
name: Ada Lovelace
born: 1815
active: true
languages:
  - English
  - French
address:
  city: London

No braces, no brackets, no commas, no quotes around most strings, and a comment — which JSON has no way to express at all. Structure comes from indentation.

Then the part that catches people: the JSON above, pasted verbatim into a YAML parser, also parses correctly and produces the identical result. YAML's flow style is JSON's syntax. The specification is precise about how this came about — JSON was "almost a complete subset of YAML" by coincidence, and YAML 1.2's stated focus was making YAML a strict superset of it.

So a YAML parser reads your JSON. A JSON parser reads almost none of your YAML.

Kubernetes manifests, Docker Compose files, GitHub Actions workflows, Ansible playbooks, OpenAPI documents. All YAML, and none of that is accidental.

Comments. The single biggest reason. A configuration file is read by humans far more often than it is written, and a config that cannot explain why a value is what it is will accumulate that knowledge somewhere worse — a wiki, or nobody's head. JSON's lack of comments makes it actively unsuitable for anything a person maintains, which is why package.json is full of fields whose purpose you have to look up.

Less punctuation to get wrong. No trailing-comma errors, no unclosed braces, no quotes around every key. For a hand-edited 200-line file, that removes an entire class of mistake.

Multi-line strings that are readable. A script embedded in a CI config, a certificate, a SQL query. In YAML a block scalar keeps the line breaks and the layout:

script: |
  npm install
  npm test

In JSON that is one string with \n escapes throughout, which is unreadable and unmaintainable.

Anchors and aliases. YAML can define a block once and reference it repeatedly, which is why large CI configurations are not entirely copy-paste.

None of those advantages apply to a machine talking to a machine, which is exactly why the split happened the way it did.

The case for JSON in an API is not that it is nicer. It is that it is boring, and that the parse has exactly one outcome.

One reading. JSON's grammar is small enough that every conforming parser agrees on what a document means. YAML's is large enough that implementations vary, and the format has several documented ways to surprise you — see below.

Native everywhere. Every browser parses JSON without a library. YAML in a browser means shipping a parser, which is a real cost on a page.

Speed and simplicity. JSON parsers are among the most optimised code in any runtime. YAML parsing is meaningfully slower, which matters when a service does it a million times an hour rather than once at startup.

Whitespace does not travel well. YAML's structure lives in its indentation, and indentation is exactly what gets damaged by templating, string concatenation, log pipelines and anything that reflows text. A JSON payload survives being pushed through a queue as a single line; a YAML document does not.

Security surface. Some YAML loaders can instantiate arbitrary objects from tagged data, which has produced real remote-code-execution vulnerabilities. Loading untrusted YAML requires a safe loader deliberately; loading untrusted JSON is inert by construction, because the format cannot express behaviour.

YAML's convenience comes from inference — it decides what your unquoted value means — and inference is where it bites. The converter here uses a real YAML parser rather than a pattern match, so it reproduces the standard behaviour faithfully, including the awkward parts.

Unquoted values get typed for you. version: 1.0 is the number 1, not the string "1.0". port: "8080" is a string; port: 8080 is a number. Convert to JSON and the difference is suddenly visible and suddenly matters, because a consumer expecting a string gets a number.

The Norway problem. In YAML 1.1, the unquoted values yes, no, on, off, y and n were booleans. So a country list containing NO for Norway produced false. YAML 1.2 narrowed booleans to true and false, but many parsers still run 1.1 semantics for compatibility, so quoting anything that could be read as a boolean remains the safe habit.

Leading zeros can become octal. A value like 0755 may be interpreted as an octal number, which is deliberate for file permissions and disastrous for a zip code or an account number. Quote them.

Tabs are illegal. YAML forbids tab characters for indentation entirely. An editor configured to insert tabs produces a file that fails to parse, with an error that rarely says "tab".

Duplicate keys behave differently. JSON permits them and parsers usually keep the last; many YAML parsers reject the document outright. A JSON file that has quietly worked for years can fail on conversion for this reason.

The general rule that avoids nearly all of it: quote any string whose content could be mistaken for something else — versions, ports, country codes, zip codes, anything with leading zeros, and anything that looks like a date.

The converter runs both directions with a real parser, in your browser — which matters here more than for most formats, because the YAML you most want to convert is a deployment manifest or a CI config, and those routinely contain hostnames, bucket names and occasionally secrets.

YAML to JSON is the direction that needs care, because inference has already happened by the time you see the output. Check the types in the result: a version that became a number, a port that became a string, a country code that became false. Everything YAML has and JSON does not — comments, anchors, multiple documents, block-scalar layout — is gone in the output, because JSON cannot express any of it. Anchors are expanded before conversion, so a config that referenced one block five times becomes five copies.

JSON to YAML is safe. Every JSON document has a YAML equivalent, and the output indents with two spaces. The conversion is also useful in an unexpected way: it is the fastest way to make a large minified JSON document readable, since YAML has less punctuation to wade through.

A practical workflow for debugging a Kubernetes manifest that is behaving oddly: convert it to JSON, format it, and look at the types. Errors that were invisible in YAML — a quoted number, a null where you meant an empty string, a nesting level you miscounted — are obvious once the braces are explicit.