glunty

Blog   /   guides   /  

JSON vs YAML: which and when

JSON vs YAML: how the two config formats differ, the YAML gotchas to avoid, and when to pick each for APIs, interchange, or human-edited files.

JSON and YAML describe the same kinds of data, so the choice between them is rarely about what you can express. It is about who reads and writes the file, how strict the parser needs to be, and how much you trust the format to interpret your values the way you meant them. This guide covers the data model both share, where their syntax diverges, the YAML features JSON lacks, and the gotchas that make YAML surprising.

The data model they share

At the core, JSON and YAML represent the same four things: scalars (strings, numbers, booleans, null), sequences (arrays or lists), mappings (objects or key-value pairs), and nesting of those. Any JSON document is, in fact, valid YAML: YAML 1.2 is a strict superset of JSON. That is why converting from JSON to YAML is lossless and mechanical, while going the other direction can lose comments and anchors that JSON has no way to store.

Because the model matches, you can move data between them without reshaping it. A config object with nested arrays looks structurally identical in both. The differences are all in how that structure is spelled on the page.

Syntax: braces versus significant whitespace

JSON marks structure with punctuation. Objects use braces, arrays use brackets, pairs are separated by commas, and keys are always quoted strings:

{
  "service": "api",
  "ports": [80, 443],
  "debug": false
}

YAML marks the same structure with indentation. Nesting is expressed by how far a line is indented, list items start with a hyphen, and quotes on keys and string values are usually optional:

service: api
ports:
  - 80
  - 443
debug: false

The whitespace approach is easier to skim and edit by hand, but it is also fragile: a single misaligned space changes meaning, and the error may not surface until a parser rejects it far from the real mistake.

Comments

This is the practical reason teams reach for YAML in config. JSON has no comment syntax at all. YAML supports them with #:

# staging only, remove before release
debug: true

If you need to annotate a config file for the humans who maintain it, JSON forces awkward workarounds like a dummy "_comment" key. YAML just lets you write the note.

Anchors and references in YAML

YAML can define a node once and reuse it, which JSON cannot. You anchor a value with &name and reference it with *name, and << merges a mapping:

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults
  timeout: 60

Here production inherits retries: 3 and overrides timeout. This keeps repetitive config short, but it also means the same YAML file can expand into much larger data, so treat anchors from untrusted sources with care.

The classic YAML gotchas

YAML’s convenience comes from guessing the type of unquoted values, and its guesses are the source of most bugs.

The best known is the Norway problem. In YAML 1.1, the tokens yes, no, on, off, true, and false all parse as booleans. So a country list written as:

countries:
  - NO
  - SE

turns NO (Norway) into the boolean false. The same trap hits on/off feature flags meant as strings. The fix is to quote any value that could be misread: "NO".

Second, tabs are not allowed for indentation. YAML requires spaces, and a stray tab produces a parse error that often points at the wrong line.

Third, ambiguous unquoted strings. A version like 1.20 may parse as the number 1.2, dropping the trailing zero. A value like 12:30 can be read as a base-60 number. A leading zero such as 0755 may be treated as octal. When a value must stay an exact string, quote it.

JSON has none of these, because it never guesses: every string is quoted, and there is no boolean-ish keyword set.

When to prefer each

Reach for JSON when a machine is the main audience: HTTP APIs, message payloads, data interchange between services, and anything a program generates and consumes. Its strictness is a feature. There is exactly one way to write a value, parsers are fast and universal, and no field silently changes type.

Reach for YAML when a human is the main author: application config, CI pipelines, infrastructure definitions, and Kubernetes manifests. Comments, anchors, and lighter syntax pay off when people edit the file daily.

A common pattern is to author in YAML and convert to JSON at build time, getting readable source and a strict runtime artifact.

Converting safely

The safe move is to convert JSON to YAML rather than the reverse, since JSON carries no comments or anchors to lose. Our JSON to YAML converter does this in your browser. Before converting, validate and clean the JSON with the JSON formatter so structure errors surface first. If you need a different target, the JSON to XML converter handles that case. After any conversion, quote values that could trip the Norway problem, and diff the round trip to confirm no number or boolean shifted.

Closing

JSON and YAML are two spellings of one data model. Pick JSON when strictness and interchange matter, YAML when humans edit the file and want comments and reuse. Learn the type-guessing gotchas once, quote anything ambiguous, and neither format will surprise you.

Embedded tool from glunty.com