JSON vs YAML: Which Should You Use for Configuration?

Updated · 5 min read · MetaSol Technologies

YAML 1.2 is (almost) a superset of JSON, so every JSON document is also valid YAML. In practice the two are used very differently: JSON for data exchange between programs, YAML for configuration edited by people.

Side by side

{
  "service": "api",
  "replicas": 3,
  "ports": [8080, 8443],
  "env": { "LOG_LEVEL": "info" }
}
service: api
replicas: 3
ports:
  - 8080
  - 8443
env:
  LOG_LEVEL: info

YAML's advantages

  • Comments with #, the main reason people choose YAML for config.
  • Less punctuation: no braces, fewer quotes, no commas.
  • Multi-line strings with | and > blocks.
  • Anchors and aliases (&default, *default) to reuse sections.

YAML's pitfalls

  • Indentation is syntax. One misplaced space changes the structure, and tabs are not allowed for indentation.
  • Implicit typing. In YAML 1.1 parsers (still common), unquoted yes, no, on, off become booleans, so the country code NO turns into false. This is known as the "Norway problem". Values like 0123 or 1e3 may also become numbers.
  • Complexity. The full YAML specification is long, and parsers differ in edge cases.

JSON's advantages

  • One obvious way to write everything, with no ambiguity.
  • Fast, strict parsers in every language.
  • Safe to generate: escaping rules are simple.

Choosing

Use case Usually best
API requests and responses JSON
Data stored or exchanged between programs JSON
Kubernetes, CI pipelines, Docker Compose YAML (it's the ecosystem standard)
App config edited by people who need comments YAML
App config generated by tools JSON

Converting JSON to YAML safely

A careful converter quotes any string YAML might misread. The JSON to YAML converter quotes values such as "yes", "NO", "0123", "1e3" and strings containing : or #, and writes numbers with their exact original digits. The result therefore means the same thing in YAML 1.1 and 1.2 parsers.