Skip to content
XUtilHub

JSON vs YAML: Which Should You Use for Config Files?

XUtilHub Team ·

If you work with Docker, Kubernetes, GitHub Actions or most modern tools, you'll edit both JSON and YAML. They can represent the same data, but they feel very different, and YAML has a few traps worth knowing.

The same config in both

JSON:

{
  "name": "web",
  "replicas": 3,
  "ports": [80, 443],
  "env": { "NODE_ENV": "production" }
}

YAML:

name: web
replicas: 3
ports:
  - 80
  - 443
env:
  NODE_ENV: production

Comparison

JSONYAML
StructureBraces and bracketsIndentation
CommentsNot allowed# like this
QuotesRequired around stringsUsually optional
ReadabilityGoodVery good for humans
StrictnessStrict and predictableFlexible, with surprises
Typical useAPIs, data exchange, package filesConfig files, CI pipelines, Kubernetes

Any valid JSON is also valid YAML 1.2, so YAML parsers can usually read JSON directly.

YAML's common traps

Indentation must use spaces. Tabs are not allowed, and one wrong space changes the structure.

Unquoted values get guessed. In older YAML 1.1 parsers, no, yes, on and off become booleans. The famous "Norway problem": a list of country codes where NO turns into false.

Numbers that aren't numbers. A version like 1.10 becomes the number 1.1, and a phone number with a leading zero may lose it. Quote them.

Colons in values. title: Note: important confuses parsers. Quote the value.

When in doubt, quote strings in YAML.

Which to choose?

  • Data sent between programs, APIs: JSON. It's unambiguous and every language parses it.
  • Config files humans edit: YAML, because comments and less punctuation help, or a tool's own format if it has one.
  • Package files such as package.json and composer.json: follow the ecosystem, which means JSON.

Converting and validating

Convert with JSON to YAML or YAML to JSON, and check your files with the YAML validator before deploying. It catches tab characters and indentation mistakes that would otherwise fail your pipeline.

Tools mentioned in this article

← All articles