JSON vs YAML: Differences and When to Use Each

JSON vs YAML at a Glance

Both formats describe the same underlying data model: scalars (strings, numbers, booleans, null), sequences (arrays/lists), and mappings (objects/dictionaries). The difference is almost entirely in how that model is written down and how each format is used in practice.

That last row is the surprising one: YAML 1.2 was deliberately designed as a superset of JSON, so most JSON documents parse cleanly as YAML. The reverse is never guaranteed.

Syntax: Braces vs Indentation

JSON marks structure explicitly with punctuation. Every object is wrapped in braces, every array in brackets, and every key is a double-quoted string followed by a colon. This makes JSON verbose but unambiguous — a parser never has to guess where a block starts or ends.

YAML uses indentation instead. Nesting is expressed by how many spaces a line is indented, list items start with a dash, and keys rarely need quotes. The result reads like an outline, which is why humans tend to prefer it for hand-edited files.

{
  "service": "api",
  "port": 8080,
  "replicas": 3,
  "features": ["auth", "logging"],
  "database": {
    "host": "db.internal",
    "ssl": true
  }
}

service: api
port: 8080
replicas: 3
features:
  - auth
  - logging
database:
  host: db.internal
  ssl: true

Comments, Data Types, and Readability

Comments

This is the feature developers miss most in JSON. The JSON spec has no comment syntax at all, so you cannot annotate a config file to explain why a value was chosen. YAML supports comments with #, which is a major reason it wins for configuration.

# Bumped from 3 after the Black Friday incident
replicas: 6

timeout: 30  # seconds; keep below the LB idle timeout

If you need comments but must ship JSON, consider JSONC or JSON5, covered in JSON5, JSONC, and NDJSON explained.

Data types and implicit typing

JSON's types are explicit and minimal: string, number, boolean, null, array, object. See JSON data types explained for the full list. YAML supports the same types but infers them from unquoted text, which introduces subtle traps. The infamous 'Norway problem' is the classic case: the unquoted value NO is read as the boolean false by YAML 1.1 parsers.

country: NO      # boolean false in YAML 1.1, not the string "NO"
version: 1.20    # the float 1.2 — the trailing zero is lost
mode: 0644       # octal 420 in YAML 1.1, not 644
safe: "NO"       # quotes force a string

Anchors, Aliases, and JSON as Valid YAML

YAML has a feature JSON completely lacks: anchors and aliases, which let you define a block once and reuse it. Combined with merge keys (<<), this removes a lot of repetition from large config files.

defaults: &defaults
  timeout: 30
  retries: 3

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

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

JSON has no equivalent, so shared values must be duplicated or resolved by your application. On the flip side, because YAML 1.2 is a JSON superset, you can paste a JSON document into a YAML file and most parsers will accept it — handy for gradual migration. Just remember the relationship only runs one way: valid JSON is valid YAML, never the reverse.

Tooling, Speed, and Security

JSON parsers are everywhere, extremely fast, and battle-tested — every language ships one in its standard library. YAML parsing is slower because the grammar is far more complex, and library support varies in quality. For high-throughput APIs, that speed gap matters.

Security is the sharper distinction. Some YAML libraries historically deserialize arbitrary language objects via tags like !!python/object, turning an untrusted YAML file into remote code execution. JSON has no such feature by design.

import yaml

# UNSAFE: can instantiate arbitrary objects
data = yaml.load(untrusted, Loader=yaml.Loader)

# SAFE: only plain data types
data = yaml.safe_load(untrusted)

For JSON interchange, validating structure matters more than parsing safety. A quick pass through a JSON validator or a schema check (see the JSON Schema guide) catches malformed payloads before they reach your code.

When to Use Each — and How to Convert

The practical rule is about audience. If a machine is the primary reader, use JSON. If a human is the primary editor, use YAML.

• Use JSON for: REST/GraphQL API payloads, message queues, browser-to-server data, log lines (NDJSON), and anything performance-sensitive or parsed from untrusted sources.
• Use YAML for: application config, CI/CD pipelines, Kubernetes manifests, Docker Compose, and any file a developer edits by hand and wants to comment.
• Consider TOML for simple flat config, or JSON5/JSONC when you want comments but must stay close to JSON.

Many stacks end up needing both — YAML config that your build serializes to JSON, or a JSON API response you want to skim as YAML. Conversion is lossless for plain data, but comments and anchors do not survive the round trip, since JSON cannot represent them.

If your data is more tabular than nested, a different format may fit better — compare the trade-offs in JSON vs CSV and JSON vs XML.