YAML vs JSON: When to Use Each Format

Use YAML for configuration files humans write and maintain — it supports comments, requires less punctuation, and is easier to read. Use JSON for APIs and data exchange — it parses faster, has a simpler spec, and is supported natively in every browser and language. YAML 1.2 is a strict superset of JSON, so any valid JSON is also valid YAML.

The answer comes down to who reads the file and how frequently.

Quick comparison

The same data in both formats

JSON:

{
  "server": {
    "host": "api.example.com",
    "port": 8080,
    "tls": true
  },
  "features": ["logging", "metrics", "tracing"]
}

YAML equivalent:

server:
  host: api.example.com
  port: 8080
  tls: true
features:
  - logging
  - metrics
  - tracing

The YAML version is shorter and easier to scan. It has no commas, no curly braces, and no quotation marks. The trade-off is that a single indentation mistake breaks the whole document.

When to use YAML

Configuration files humans maintain

YAML's main strength is readability. When a developer has to open a file, read it, understand it, and edit it — YAML reduces friction. This is why it dominates in:

• Kubernetes manifests — Deployments, Services, ConfigMaps, Ingress rules
• Docker Compose — docker-compose.yml service definitions
• GitHub Actions — .github/workflows/*.yml pipeline definitions
• Ansible playbooks — Task lists and role definitions
• Helm charts — Kubernetes package manager values files
• Application settings — application.yaml in Spring Boot, config.yaml in many tools

When comments matter

JSON has no comment syntax. If you need to explain a configuration choice, disable a block temporarily, or leave a note for future developers, YAML is the only option. This alone makes YAML the right choice for complex config files.

# Production server config
# Do not increase replicas above 10 without checking DB connection pool limits
server:
  replicas: 5  # Scaled up from 3 on 2026-03-01
  timeout: 30

When you have multiline text

YAML block scalars make embedding multiline text natural:

message: |
  Hello,
  This is a multiline
  message without escape sequences.

In JSON, the same value would be "message": "Hello,\nThis is a multiline\nmessage without escape sequences." — much harder to read and edit.

When to use JSON

APIs and data exchange

JSON was designed for data transport. When data moves between a server and a browser, between two services, or in a message queue, JSON is the right format because:

• Every programming language has a native or near-native JSON parser
• Browsers parse JSON natively with JSON.parse()
• JSON parsing is significantly faster than YAML parsing
• JSON's simple spec means fewer edge cases and parser bugs
• JSON is whitespace-insensitive — minified or pretty-printed, it parses the same

When the consumer is a machine, not a human

If no human ever reads the raw format — the data goes straight from one API to another, or is stored in a database — JSON's compactness and parse speed are advantages with no downside.

When you need browser compatibility

Browsers have no built-in YAML parser. If your frontend needs to consume structured data from a fetch() call or a <script> tag, JSON is the only practical choice without adding a library.

Database document storage

MongoDB, CouchDB, PostgreSQL's JSONB, and most NoSQL databases store and query JSON natively. YAML has no equivalent storage support.

The "YAML is just for config, JSON is for APIs" rule

A practical rule that works in most cases:

• Humans write it → YAML. Config files, deployment manifests, CI/CD pipelines.
• Machines write it → JSON. API responses, database records, message queue payloads.

There are exceptions — some tools use JSON for config (package.json, tsconfig.json) and some APIs return YAML — but the rule covers the overwhelming majority of real-world cases.

Which should you use? A decision guide

Is YAML a superset of JSON?

Yes — YAML 1.2 is a strict superset of JSON. Every valid JSON document is also valid YAML 1.2. This means you can feed JSON directly into a YAML parser and it will parse correctly. The reverse is not true: YAML documents that use comments, anchors (&), aliases (*), or implicit type coercion are not valid JSON. The superset relationship makes conversion from JSON to YAML always lossless, but YAML to JSON conversion discards any YAML-only features.

Can YAML replace JSON in REST APIs?

Technically yes — YAML is a superset of JSON, so a server could respond with YAML-formatted data. In practice, YAML should not replace JSON for REST APIs. JSON parsing is significantly faster because the spec is simpler; every browser has a native JSON.parse() function with no YAML equivalent; and JSON's whitespace-insensitivity eliminates a whole class of indentation bugs. YAML is better suited for files humans write and read. If you want a more human-readable API response format, JSON with consistent pretty-printing is a better choice than switching to YAML.

Converting between them

Because YAML 1.2 is a superset of JSON, conversion is straightforward and lossless for standard documents. The main exception is YAML-specific features like comments, anchors, and aliases, which have no JSON equivalent and are discarded during conversion.

Common YAML pitfalls to avoid

YAML’s flexibility comes with sharp edges. These are the bugs most likely to reach production undetected.

The Norway problem — unexpected boolean coercion

In YAML 1.1 (the version Kubernetes uses), bare values like yes, no, on, off, and their capitalized variants all parse as booleans. The ISO 3166-1 country code for Norway (NO) evaluates to false in a YAML 1.1 config — a real-world bug that has broken production pipelines at multiple organizations. YAML 1.2 fixed this (only true and false are booleans), but most parsers still default to 1.1 behavior.

country: NO         # parsed as false (boolean) in YAML 1.1
enabled: yes        # parsed as true (boolean)
mode: on            # parsed as true (boolean)

# Fix: always quote values that could be misinterpreted
country: "NO"
enabled: "yes"
mode: "on"

Tabs are not allowed for indentation

YAML forbids tab characters — only spaces are valid for indentation. Most editors handle this automatically, but copy-pasting YAML from shell scripts, Stack Overflow, or certain IDEs can silently introduce tabs. The resulting parse error is frustrating to debug because tabs are invisible in most editors.

Accidental number coercion

Values that look like numbers are parsed as numbers. A version string version: 1.10 becomes the float 1.1. A leading-zero value like port: 08080 may parse as octal in YAML 1.1. Quote any value that should be treated as a string: version: "1.10".