YAML vs JSON

The two-line answer

• Wire format between programs? JSON. It's faster to parse, has no version drift, and every language ships a parser.
• Config file humans edit? YAML (or TOML). Comments, multiline strings, and less syntactic noise.

Decision table (skip ahead if you're picking right now)

Is "yml" the same as "yaml"?

Yes — .yml and .yaml are both valid file extensions for the same YAML format. The official YAML site recommends .yaml, but .yml is more common in practice (GitHub Actions, Docker Compose, GitLab CI all default to it). Some tools accept only one — Kubernetes manifests are usually .yaml, GitHub workflows are .yml. Lock the extension your tool expects; the parser doesn't care.

Side by side

The same data in both formats:

# YAML
name: my-app
version: 1.0.0
ports:
  - 80
  - 443
config:
  debug: false
  timeout: 30
  # Retry logic was added in v1.0
  retries: 3

// JSON
{
  "name": "my-app",
  "version": "1.0.0",
  "ports": [80, 443],
  "config": {
    "debug": false,
    "timeout": 30,
    "retries": 3
  }
}

Same data tree. YAML drops the braces, brackets, quotes, and commas in exchange for caring about indentation. The # comment in YAML has no JSON equivalent.

Quick syntax differences

Where YAML wins

Configuration files

Kubernetes manifests, GitHub Actions, Ansible playbooks, Docker Compose, CircleCI configs — all use YAML, all for the same reason: humans read and edit these by hand. JSON's required quotes and commas make it painful for files larger than ~50 lines.

Multiline content

Embedding a SQL query, a shell script, or a long template in JSON means escaping every newline as \n in a single string. YAML's block scalars (| and >) keep the content readable. Multiline strings have their own guide.

Repetition reduction

YAML's anchors (&name) and aliases (*name) let you define a chunk of config once and reuse it. JSON has no equivalent — you copy-paste or use a templating system. Anchors and aliases guide.

Where JSON wins

Speed

JSON parsers are 5-50× faster than YAML parsers. For a 100KB document, Node's built-in JSON.parse typically finishes in under 1ms; the yaml npm package takes 15-40ms for the same bytes. PyYAML's pure-Python parser is the slowest of the bunch (libyaml-backed yaml.CSafeLoader closes the gap). For a config file loaded once at startup, the difference is invisible. For a wire format processing thousands of messages per second, JSON's lead is decisive.

Predictability

JSON has one canonical interpretation. YAML has at least two common ones (1.1 and 1.2) that disagree about whether off means false, whether 010 is octal, and whether unquoted NO is a country code or a boolean. The YAML parser version matters; JSON parsers don't.

Tooling and security

Every WAF, every API gateway, every framework expects JSON in HTTP bodies. YAML parsers have a long history of CVEs (PyYAML's old load(), snakeyaml deserialization) that JSON parsers don't share — JSON is a strictly smaller attack surface.

The four rules that prevent most YAML bugs

1. Always quote ambiguous strings. Country codes, version numbers, and anything that could be misread as a number, boolean, or null. "on": true not on: true.
2. Use spaces only, never tabs. Most YAML parsers reject tabs. The error message is rarely helpful.
3. Pin the YAML version. Use a parser configured for YAML 1.2 if your data has any of: country codes, boolean- looking strings, leading zeros on numbers.
4. Validate before deploying. Lint the file before checking it in. CI failures two minutes after merge are an avoidable expense.

Conversion

Converting in either direction is straightforward — every YAML construct except anchors maps to a plain JSON shape. Anchors get resolved (and any aliases inlined) during conversion.

Paste your YAML on the home page and toggle to JSON to see the converted output.

Reference

• YAML 1.2.2 spec — the current standard.
• RFC 8259 — JSON, the current standard.

FAQ

Open the YAML linter →