YAML vs JSON: Differences, Pros, Cons, When to Use Each

The Short Answer

Use JSON for data interchange. Use YAML for configuration files humans edit. JSON's strictness, parsing speed, and tooling support make it the right format when programs are talking to programs. YAML's comments, multi-line strings, and reduced syntactic noise make it the right format when humans are talking to programs.

If you find yourself debating it for the same use case, consider that they are functionally equivalent for most data — YAML 1.2 is a strict superset of JSON. You can paste JSON into a YAML file and it parses correctly. The choice is about ergonomics and tooling, not capability.

Side-by-Side Syntax

The same data structure in both formats:

JSON

{
  "name": "janeer",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "wrangler deploy",
    "test": "node test.js"
  },
  "tags": ["devtools", "static", "seo"],
  "author": null
}

YAML

# Project metadata
name: janeer
version: 1.0.0
private: true

scripts:
  build: wrangler deploy
  test: node test.js

tags:
  - devtools
  - static
  - seo

author: null  # not set yet

Both files describe the same object. The YAML version uses indentation instead of braces, drops the quotes around string values that look unambiguous, and adds two comments — none of which JSON allows.

The Real Differences

1. Comments

YAML supports # comments to end of line. JSON does not — by deliberate design. If you need to annotate why a particular value is set, you either write a YAML file, you abuse a _comment field, or you adopt a non-standard JSON variant like JSON5 or JSONC. For configuration that lives in version control and gets reviewed, comments are not optional, which is why Kubernetes manifests, GitHub Actions workflows, Docker Compose, and most CI configs are YAML.

2. Significant Whitespace

YAML uses indentation to express structure. Two spaces instead of three, a tab instead of spaces, or a misaligned dash will produce a confusing parse error or — worse — a valid file with wrong nesting. JSON's braces and brackets are explicit, which is why machine-generated config almost always uses JSON: the format is brittle to whitespace bugs that a generator could introduce.

3. Multi-Line Strings

YAML has rich multi-line string support. The | block scalar preserves newlines; > folds them into spaces:

script: |
  #!/bin/bash
  echo "Hello, world"
  exit 0

description: >
  This is a long description that spans
  several lines but parses as a single
  paragraph with the newlines folded.

JSON has no equivalent — you escape every newline as \n. For embedding shell scripts, SQL queries, or template strings in a config file, the YAML form is dramatically more readable.

4. Anchors and Aliases

YAML lets you define a value once with an anchor (&) and reuse it with an alias (*):

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: api.example.com

staging:
  <<: *defaults
  host: staging.example.com
  retries: 5

JSON has no shared-references mechanism — repetition is the only option. For configs with shared blocks, anchors keep the file DRY without a templating layer.

5. Type Inference

YAML guesses types from the value: true becomes a boolean, 1.0 becomes a float, 2024-01-15 becomes a date in YAML 1.1 (and a string in YAML 1.2). This is the source of the famous Norway Problem — the country code NO was historically parsed as the boolean false by YAML 1.1 because no was a synonym for false. Always quote string values that could be misinterpreted: "NO", "true", "1.0". YAML 1.2's core schema removes most of these traps but the gotcha is real in older parsers.

JSON's types are unambiguous: "true" is always a string, true is always a boolean, and there is no automatic date parsing. This is one reason JSON is preferred for data exchange — there is no surprise coercion.

6. Parsing Speed and File Size

JSON parsers are 5 to 10 times faster than YAML parsers in typical benchmarks. JSON files are also marginally smaller because they omit indentation but compete with the overhead of braces and quotes. For a config file read once at startup, neither matters. For an API serving a million requests per minute, JSON is the only sensible choice.

7. Tooling

Every language ships with a JSON parser in the standard library. Almost every language has a third-party YAML parser, but quality varies, and the API surface is larger. For maximum portability — particularly for languages where you do not control the dependency list — JSON wins by default.

When to Use Each

Use JSON when:

• You are sending data over HTTP — REST APIs, GraphQL responses, message queues, server-sent events.
• The file is generated by a program and consumed by another program with no human in the loop.
• Parsing speed matters — high-volume APIs, log lines, NDJSON streams.
• You want unambiguous types with no automatic coercion.
• You need a parser available in any language without adding a dependency.

Examples: package.json, API responses, browser fetch() bodies, web service contracts, analytics events.

Use YAML when:

• The file is edited by humans in a code editor and reviewed in pull requests.
• You need comments to explain non-obvious values.
• The data contains long string values that benefit from multi-line syntax.
• You want anchors to avoid repeating shared configuration blocks.

Examples: Kubernetes manifests, GitHub Actions and CircleCI workflows, Docker Compose, Helm chart values, Ansible playbooks, OpenAPI specs that are hand-edited (the published machine-readable version is often JSON).

Converting Between Them

Because YAML 1.2 is a superset of JSON, conversion is mechanical. Use the YAML to JSON converter for quick one-off conversions in either direction — it runs entirely in your browser, so even sensitive configs stay local.

Programmatic conversion in code:

# Python
import yaml, json
data = yaml.safe_load(open('config.yaml'))
json.dump(data, open('config.json', 'w'), indent=2)

// Node.js (with js-yaml)
const yaml = require('js-yaml');
const fs = require('fs');
const data = yaml.load(fs.readFileSync('config.yaml', 'utf8'));
fs.writeFileSync('config.json', JSON.stringify(data, null, 2));

# Ruby
require 'yaml'; require 'json'
File.write('config.json', JSON.pretty_generate(YAML.safe_load(File.read('config.yaml'))))

The reverse direction (JSON to YAML) is similarly trivial — every YAML library handles it. One caveat: round-tripping loses comments, ordering of keys (in some parsers), and YAML-specific tags. Treat conversion as a one-way operation when comments matter.

Security Considerations

YAML's tag system was historically a source of remote code execution bugs. PyYAML's default yaml.load() would instantiate arbitrary Python objects from a tagged YAML payload, meaning untrusted YAML could execute arbitrary code. The mitigation is to always use the safe loader:

# Python — always
yaml.safe_load(untrusted_yaml)
# Never
yaml.load(untrusted_yaml)  # CVE bait

// Node.js — js-yaml is safe by default
const data = yaml.load(untrusted)  // uses CORE_SCHEMA, safe
// The unsafe yaml.load() in older versions has been removed

JSON has a smaller attack surface — there is no equivalent class-instantiation vector. Untrusted JSON can still cause problems through prototype pollution if a parser merges parsed data into existing objects without protection, but the format itself is stricter than YAML.

If you accept user-supplied configuration files of either format, validate the parsed data against a schema before using it. Both YAML and JSON Schema validators exist, and they catch type and range errors that the parser alone will not.