YAML vs JSON — Key Differences, When to Use Each

JSON dominates APIs and data interchange. YAML dominates configuration files — Kubernetes manifests, GitHub Actions workflows, Ansible playbooks, Docker Compose. Both represent the same data structures, but they make very different tradeoffs. This guide compares them side by side so you know which to reach for.

Convert JSON ↔ YAML →Format YAML →

Syntax Comparison — Side by Side

The same data structure in JSON and YAML:

JSON

{ "name": "deploy", "version": 3, "enabled": true, "tags": [ "web", "production" ], "database": { "host": "db.example.com", "port": 5432 } }

YAML

# Deployment config name: deploy version: 3 enabled: true tags: - web - production database: host: db.example.com port: 5432

6 Key Differences

1. Comments

YAML supports # line comments. JSON has no comment syntax — comments cause parse errors. If you need comments in JSON, use JSONC (VS Code tsconfig.json, some build tools) but not standard JSON.parse().

2. Quoting

JSON requires double quotes for all string keys and values. YAML allows unquoted strings, single quotes, and double quotes. This makes YAML more readable but adds ambiguity (is 'true' the boolean or the string?).

3. Multiline strings

YAML has dedicated multiline string syntax: | (literal block, preserves newlines) and > (folded block, folds newlines to spaces). In JSON, multiline strings require escaped \n characters embedded in one long line.

4. Anchors and aliases (DRY)

YAML supports anchors (&name) and aliases (*name) to reuse values without repetition. JSON has no equivalent — you must repeat values or preprocess before parsing.

5. Strictness

JSON is strict and unambiguous — there is one way to represent each value. YAML is flexible but has implicit type coercion gotchas: 'yes', 'on', 'y' can parse as boolean true in YAML 1.1 parsers. Always quote strings that look like booleans or numbers.

6. Parsing speed

JSON is faster to parse. It has a simple grammar and native browser support (JSON.parse is implemented in C++ in V8). YAML parsers are more complex due to the richer syntax. For high-throughput data interchange, JSON wins.

YAML Multiline String Syntax

# Literal block (|) — preserves newlines exactly description: | Line one. Line two. Line three. # Parses as: "Line one. Line two. Line three. " # Folded block (>) — folds newlines to spaces description: > This is a very long sentence that spans multiple lines in the YAML file. # Parses as: "This is a very long sentence that spans multiple lines in the YAML file. " # In JSON, you must use escape sequences: {"description": "Line one.\nLine two.\nLine three."}

YAML Anchors for DRY Config

# Define a shared config once defaults: &defaults retries: 3 timeout: 30 env: production # Reuse it in multiple services api: <<: *defaults # merge all defaults port: 8080 worker: <<: *defaults # merge all defaults port: 8081 retries: 5 # override specific value

Use Cases

Use CaseJSONYAML
REST API requests/responsesStandardNot used
package.json, tsconfig.jsonStandardNot used
GitHub Actions workflowsNoStandard
Kubernetes manifestsSupportedStandard
Docker ComposeNoStandard
Ansible playbooksNoStandard
OpenAPI / Swagger specsSupportedPreferred
App config filesCommon (JSONC)Common

Common Mistakes When Switching

  • YAML booleans: yes/no/on/off/true/false are all booleans in YAML 1.1. Quote them if you mean a string: status: "no"
  • YAML indentation: YAML uses spaces only — tabs are not allowed and will cause a parse error.
  • JSON trailing commas: JSON does not allow trailing commas. YAML has no commas in block style.
  • Octal numbers: In YAML 1.1, 0755 parses as octal 493, not the integer 755. This catches many developers writing file permissions.

Related Tools

JSON ↔ YAML Converter →
Convert between JSON and YAML instantly in your browser.
YAML Formatter →
Format and validate YAML files with consistent indentation.
JSON Formatter →
Format, validate, and pretty-print JSON data.

Related Guides

How to Validate JSON →
Validate JSON before converting to YAML — catch syntax errors early.
Cron Expression Examples →
Cron jobs in GitHub Actions and Kubernetes are defined in YAML — 25 examples.
SQL Formatter Guide →
SQL, JSON, and YAML are the three data languages in most stacks — formatting guide.

FAQ

Is YAML a superset of JSON?

Yes — YAML 1.2 is a strict superset of JSON. All valid JSON is valid YAML. However, YAML parsers may handle some edge cases differently, and the YAML 1.1 spec (used by older parsers like PyYAML 5.x) has different rules for implicit type coercion (e.g., 'on', 'yes', 'true' all parse as boolean true).

Can YAML have comments?

Yes. YAML supports # line comments. JSON does not support comments at all — if you need comments in JSON config files, use JSONC (JSON with Comments), which is supported by VS Code and TypeScript's tsconfig.json but not by standard JSON parsers.

Which is better for APIs: JSON or YAML?

JSON is the standard for REST APIs and HTTP responses. It is natively supported by all browsers and HTTP clients, faster to parse, and unambiguous. YAML is not used for API payloads in practice.

Why does YAML parsing sometimes give unexpected types?

YAML 1.1 has implicit type coercion rules that surprise developers. For example, 'yes', 'on', 'true' all parse as boolean true. Country codes like 'NO' (Norway) parse as false. Port numbers without quotes may parse as integers. Always quote strings that could be misinterpreted, or use YAML 1.2 (which only accepts 'true'/'false' for booleans).

How do I convert YAML to JSON?

Use DevKit's JSON/YAML converter — paste YAML and get JSON (or vice versa) in the browser. In code: Python's yaml.safe_load() + json.dumps(), or Node.js with the js-yaml library.