Is YAML a superset of JSON?

Yes — since YAML 1.2, every valid JSON document is also valid YAML. YAML parsers can read JSON directly. The reverse is not true: YAML features like comments, anchors, and multi-line strings have no equivalent in JSON.

Can YAML have comments?

Yes. YAML supports single-line comments with #. This is one of the most practical advantages of YAML for configuration files. JSON has no comment syntax. Some parsers accept // or /* */ comments as an extension (JSONC format), but standard JSON does not.

Which is faster to parse — JSON or YAML?

JSON is significantly faster to parse. Its grammar is simple and unambiguous, and native JSON parsers are built into every runtime (browsers, Node.js, Python, etc.). YAML has a much more complex grammar with many edge cases (especially around implicit typing), which makes parsers slower and more prone to subtle bugs.

Which should I use for configuration files?

YAML is generally preferred for human-edited config files (Docker Compose, Kubernetes, GitHub Actions, Ansible) because of its readability and comment support. JSON is better for machine-generated or machine-consumed data (APIs, package.json, tsconfig.json) where tooling support and parse speed matter more than readability.

JSON vs YAML: What's the Difference?

What are JSON and YAML?

JSON (JavaScript Object Notation) is a lightweight text format for data interchange. Introduced in the early 2000s alongside the rise of REST APIs, it became the universal language of web services — simple, strict, and machine-friendly.

YAML (YAML Ain't Markup Language) is a human-readable data serialization format designed for configuration files. It prioritizes readability: less punctuation, support for comments, and a clean indentation-based structure.

Both formats represent the same underlying data model — objects, arrays, strings, numbers, booleans, and null — but they make very different trade-offs.

Syntax comparison

The same data expressed in both formats:

JSON

{
  "name": "Jane Doe",
  "age": 32,
  "active": true,
  "roles": ["admin", "editor"],
  "address": {
    "city": "Paris",
    "country": "France"
  }
}

YAML

name: Jane Doe
age: 32
active: true
roles:
  - admin
  - editor
address:
  city: Paris
  country: France

Both represent exactly the same data. YAML removes the quotes, braces, and commas — indentation does the structural work instead.

Key differences

JSONYAML

SyntaxBraces, quotes, commasIndentation, minimal punctuation

CommentsNot supported# single-line comments

ReadabilityModerateHigh — designed for humans

Parse speedFast (native in all runtimes)Slower (complex grammar)

Data typesExplicit (always quoted strings)Implicit (can cause surprises)

Multi-lineEscape sequences (\n)Literal (|) and folded (>) blocks

AnchorsNot supported& and * for reuse

JSON subset—YAML 1.2 is a superset of JSON

Primary useAPIs, config, data exchangeConfig files, IaC, CI/CD

YAML-only features

Comments

YAML supports comments — JSON does not# Database configuration database: host: localhost # or use an env var port: 5432 name: myapp_prod

Multi-line strings

YAML literal block ( | ) and folded block ( > )description: | This is a multi-line string. Each line is preserved as-is. Great for scripts or SQL queries. summary: > This text will be folded into a single line when parsed.

Anchors and aliases

YAML anchors (&) reuse values — avoids repetitiondefaults: &defaults retries: 3 timeout: 30 production: <<: *defaults # inherits retries and timeout timeout: 60 # overrides just this value

When to use each

Choose JSON when…

Building or consuming an API — JSON is the standard
The data is machine-generated and machine-consumed
You need maximum tooling compatibility (every language has a fast native JSON parser)
Strict structure matters — no implicit type coercion surprises
Examples: package.json, tsconfig.json, REST API responses

Choose YAML when…

Humans will read and edit the file regularly
You need comments to document the config
The structure is deeply nested (YAML is less cluttered)
You're working with tools that expect it: Docker Compose, Kubernetes, GitHub Actions, Ansible
Examples: docker-compose.yml, .github/workflows/*.yml, values.yaml