JSON vs YAML: Which Config Format to Use

One Problem, Two Syntaxes

JSON and YAML both represent the same thing: nested structures of objects, arrays, strings, numbers, and booleans. Every valid JSON document is a valid YAML document. The difference is who is meant to read and write the file.

JSON optimises for machines: parsers are simple, the grammar is small, there is exactly one way to write anything. YAML optimises for humans: whitespace replaces brackets, comments are allowed, and multi-line strings read naturally. Picking between them is mostly about which audience you care about more in a given file.

The Same Data in Both

JSON:

{
  "service": "api",
  "replicas": 3,
  "env": {
    "NODE_ENV": "production",
    "LOG_LEVEL": "info"
  },
  "ports": [8080, 8081]
}

YAML:

service: api
replicas: 3
env:
  NODE_ENV: production
  LOG_LEVEL: info
ports:
  - 8080
  - 8081

Both describe the exact same structure. You can convert between them instantly with the JSON ↔ YAML Converter.

When JSON Wins

JSON is the right choice when the file is primarily consumed by code:

• API payloads and request bodies. Every HTTP client and server speaks JSON natively.
• Browser storage. localStorage, IndexedDB, and most data you send to the browser are JSON.
• Log lines and event streams. One JSON object per line (JSONL) parses predictably at volume.
• Data interchange between services. JSON Schema, OpenAPI, JSON-LD all build on top.
• Files generated by tools. package.json, composer.json, tsconfig.json — machines write them, machines read them.

JSON's win is predictability. There is exactly one way to write an empty object ({}), one way to represent a string (double quotes only), and no significant whitespace. You never stare at a JSON file wondering why the parser is unhappy.

When YAML Wins

YAML becomes the obvious choice when humans edit the file regularly:

• CI/CD pipelines. GitHub Actions, GitLab CI, CircleCI all chose YAML for a reason.
• Kubernetes manifests and Helm charts. Complex nested structures are much easier to scan without braces.
• Ansible, Docker Compose, Kustomize. Infrastructure-as-code favours YAML because operators read these files daily.
• Application configuration. Anything with comments explaining "why" wants YAML — JSON has no comments at all.

The two big YAML wins are comments and multi-line strings:

# Rate limit: 100 requests per minute per IP.
# Tuned after the 2025-11 incident — do not raise without ops approval.
rate_limit: 100

welcome_message: |
  Welcome to the service.
  This is a real multi-line string.
  Newlines are preserved as-is.

Representing that same content in JSON is painful: no comments, and multi-line strings become "Line one\nLine two\nLine three" — readable to a parser, unreadable to a human.

YAML's Footguns

YAML is easier to read and harder to write. The ergonomics come at the cost of some genuinely surprising parsing behaviour:

The Norway problem. Unquoted NO parses as the boolean false. So does off, No, N. If your list of country codes contains NO, it silently becomes False. YAML 1.2 fixed this, but many parsers still default to YAML 1.1 behaviour.

Number-looking strings. version: 1.20 becomes the number 1.2 — the trailing zero is gone. ip: 10.0.0.1 becomes a string only because of the extra dots. zip: 01234 parses as the octal number 668. Quote any value that must remain a string: version: "1.20".

Indentation errors. Mix tabs and spaces and the parser usually rejects the file — but not always with a helpful error. Pick one, stick with it, let your editor enforce it.

Anchors and aliases. YAML has a whole feature (&anchor / *alias) for reusing fragments. Handy when you need it, confusing when you don't recognise the symbols.

Mixing Them in One Stack

The common pattern in real systems is YAML at the edges, JSON in the middle. Humans write YAML config, a build step converts it to JSON, services load JSON at runtime. This gives you the editing experience of YAML and the parsing reliability of JSON.

Docker images often ship JSON config built from YAML sources for this reason. Kubernetes manifests are typically written in YAML but the API server serialises them as JSON internally.

Validating and Converting

Whatever format you pick, validate it before committing. A small syntax error in a large manifest is easy to miss and expensive to debug in production.

• Use the JSON Formatter to validate, minify, or prettify JSON. It catches missing commas, unclosed braces, and trailing-comma errors instantly.
• Use the JSON ↔ YAML Converter to swap between formats. Useful for copying config from one system to another, or for spotting accidental type coercions in YAML.

Try It Now

Paste any config file into the JSON ↔ YAML Converter to see it in the other format side by side — a quick way to build intuition for how a YAML tweak looks in JSON, and vice versa.