YamlBox

Guide · 6 min read

YAML vs JSON: when to use which

YAML vs JSON is a choice between two serialisation formats built on the same basic idea: nest key–value pairs and lists. The differences that matter in practice are about who reads the file: humans or machines.

Updated

YAML vs JSON: the short version

JSON is a data interchange format: strict, unambiguous, and every language can parse it natively. YAML is a configuration format: it accepts comments and multi-line strings, and it is designed to be edited by people in pull requests. Use JSON on the wire, YAML in files that humans maintain — and convert between them when a boundary requires it.

What actually differs

Comments

YAML has comments; JSON does not. In configuration files this is decisive — the reason you know why a timeout is set to 3000 is usually the comment above it. When you convert YAML to JSON the comments are dropped, which is why JSON is often treated as a build artifact, not the source of truth.

Syntax and noise

                # YAML
service:
  name: checkout
  replicas: 3
  ports: [8080, 9090]

// JSON — same data
{
  "service": {
    "name": "checkout",
    "replicas": 3,
    "ports": [8080, 9090]
  }
}

YAML removes braces, quotes and commas in exchange for indentation sensitivity. That is the trade every YAML user knows: fewer characters, more ways to get whitespace subtly wrong.

Types and traps

  • JSON has one numeric type; YAML distinguishes ints, floats and more — and YAML 1.1 famously parses the country code NO as the boolean false, and 1.10 as a number that loses its trailing zero unless quoted.
  • YAML supports anchors and aliases (&defaults / *defaults) for reuse; JSON has no equivalent, so shared blocks must be duplicated or generated.
  • YAML supports multi-document files (--- separators); JSON is one document per file. Converters typically turn documents into an array.
  • JSON requires double-quoted keys and strings; YAML quotes only when necessary, which means a careless string can silently become a number or boolean.

Where each format wins

  • APIs and wire formats: JSON. Universal parsers, predictable ambiguity, streaming-friendly (JSON Lines).
  • Kubernetes, CI/CD, Docker Compose, Ansible, Helm: YAML, because these ecosystems standardised on it and support comments.
  • Vendor configuration you generate programmatically: JSON — algorithms produce it without indentation anxiety.
  • Documents a junior teammate will edit by hand: YAML, with comments explaining the why.

Converting safely

  1. Know your multi-document files. A k8s manifest set separated by --- must become a JSON array, not just the first document. Use a converter that reports how many documents it found.
  2. Quote the numbers that are identifiers. "1.10" is a version; 1.10 is a float. Enable force-quotes when converting to YAML if values are strings that look numeric.
  3. Watch comments disappearing. Converting to JSON is lossy by definition; if comments matter, keep YAML as the source and generate JSON only at build time.
  4. Validate with precise errors. Indentation errors produce misleading messages in some tools; make sure yours shows line and column.

Try it: paste any YAML into the YAML to JSON converter — multi-document support and precise error lines are built in, and nothing is uploaded.

Common questions

Is YAML a superset of JSON?

YAML 1.2 is designed as a superset — valid JSON is usually valid YAML. But YAML 1.1 (still out there) differs on some edge cases, and tabs, duplicate keys and certain strings parse differently across engines. Treat "it is technically valid YAML" as a fun fact, not a migration strategy.

Which is faster to parse?

JSON parsers are generally faster and simpler because the grammar is smaller; native JSON parsing exists in every runtime. For config files the difference is irrelevant — you parse once at startup.