Guide

JSON vs YAML: which to use for config

A practical comparison of JSON and YAML for configuration files — readability, comments, data types, and tooling — with a converter built in.

Try it — JSON to YAML

JSON to YAML — convert JSON to YAML error runs in your browser · nothing uploaded

⌃⏎ run · ⎋ clear · / focus input

JSON ⇅ upload

⇅ drop a file to load it

YAML

send output to

no matches

Handles pastes up to ~5MB smoothly in your browser — bigger files still work, just budget a second or two.

JSON and YAML describe the same shape of data — objects, arrays, strings, numbers, and booleans — but they target different readers. JSON is built for machines and APIs; YAML is built for humans editing config by hand. Choosing between them for a configuration file comes down to a handful of concrete differences. The converter above turns JSON into YAML so you can compare the two side by side.

The same data, two syntaxes

Here is a small configuration in both formats. The JSON version:

{
  "service": "api",
  "port": 8080,
  "debug": false,
  "hosts": ["web-1", "web-2"]
}

The YAML equivalent:

service: api
port: 8080
debug: false
hosts:
  - web-1
  - web-2

YAML drops the braces, brackets, and most quotes, and uses indentation to express nesting. For a file a person edits often, that is less visual noise. JSON's explicit delimiters, by contrast, make it unambiguous to parse and harder to break by accident.

Where the formats actually differ

A few differences decide most real choices:

Comments. JSON has none. YAML supports # comments, which is often the single deciding factor — config files benefit enormously from explaining why a value is set.
Multiline strings. YAML has block scalars (| keeps newlines, > folds them). In JSON you embed \n escapes inside one long string, which is painful to read.
Trailing commas and quoting. JSON forbids trailing commas and requires quoted keys. YAML is forgiving about quoting, which is convenient but introduces type pitfalls (below).
Reuse. YAML anchors (&name) and aliases (*name) let you define a block once and reference it. JSON has no equivalent.

# why we cap connections here
database:
  pool: &default_pool
    min: 2
    max: 10
  replica:
    pool: *default_pool
  notes: |
    This text keeps
    its line breaks.

Data-type pitfalls in YAML

YAML's loose quoting is its biggest footgun. Because unquoted scalars are type-inferred, values that look like one type can become another:

no, off, yes, and on may parse as booleans, not strings. The classic case is a country code NO (Norway) becoming false.
A version like 1.20 can lose its trailing zero by parsing as a number.
A value like 08 can be read as octal or rejected, depending on the parser.

The fix is to quote anything that should stay a string: country: "NO", version: "1.20". JSON sidesteps all of this because every string is quoted by definition.

Tooling and ecosystem

JSON is the native format of web APIs, browser fetch, log pipelines, and most databases' document types. It is supported everywhere with zero dependencies. YAML dominates the configuration world: Kubernetes, GitHub Actions, Docker Compose, Ansible, and most CI systems use it because humans write those files directly.

Which one to use

Use JSON when:

A machine produces or consumes the data (API payloads, logs, message queues).
You want the strictest, least surprising parsing.
The file is generated, not hand-edited.

Use YAML when:

A human edits the file regularly and benefits from comments.
You have repeated blocks or long multiline strings.
You are working in an ecosystem (Kubernetes, CI) that expects it.

A common pattern is to author config in YAML for readability and convert to JSON at build or deploy time for the runtime to consume. The converter above handles that JSON-to-YAML step; because every JSON document is already valid YAML, the data survives the trip intact.

Frequently asked questions

Yes. Any valid JSON document is also valid YAML, so a YAML parser can read JSON directly. The reverse is not true, because YAML has features such as comments and anchors that JSON does not support.

No. The JSON spec has no comment syntax, which is a common reason teams move config files to YAML. If you need comments in JSON, some parsers accept JSON5 or JSONC, but those are not standard JSON.

YAML uses indentation to define structure, so mixing tabs and spaces or misaligning a key changes the meaning of the document. Always use spaces, and keep indentation consistent within a file.

Generally yes. YAML has a richer grammar, so parsing is more work than JSON, which matters for high-volume APIs. For human-edited config files the difference is irrelevant.

Yes for the data itself — keys, values, arrays, and nesting map cleanly. You will lose JSON-only formatting and gain nothing JSON cannot represent, so the round trip is lossless for content.

Tool JSON to YAML Tool JSON Formatter Tool JSON Validator Tool XML Formatter Guide How to format SQL for readability