TOML vs YAML vs JSON: Choosing a Configuration Format

The same settings written three ways

Take a small, realistic config — a server port, a database URL, a list of allowed origins, and a nested logging section — and write it in each format. The shapes converge on the same data; what differs is punctuation, and punctuation turns out to matter a lot once a file is edited by hand every week.

TOML reads like an .ini file that grew real types: [headings] introduce tables, key = value pairs are unambiguous, and there's no meaningful whitespace to get wrong. The YAML rendering of the same config appears in the next section, so each format gets its own code block rather than three squeezed into one.

[server]
port = 8080
allowed_origins = ["https://app.example.com", "https://admin.example.com"]

[database]
url = "postgres://db:5432/shop"

[logging]
level = "warn"
format = "json"

Where YAML diverges: indentation as structure

YAML drops the [headings] and brackets entirely and uses indentation to carry the nesting — the same information, with roughly a third fewer punctuation characters, and comments allowed anywhere. That readability is also YAML's best-known failure mode: two spaces where a list item needed four silently reattaches a key to the wrong parent, and nothing about the file LOOKS wrong until something downstream reads a value that isn't there.

The same JSON rendering (below, in the types section rather than repeated here) is denser than either: braces and quotes around every key, no comments, and a trailing-comma trap that trips up hand edits. That combination — machine-precise, human-hostile — is exactly why JSON rarely gets used as a config format a person edits directly; it's the format a PROGRAM writes.

server:
  port: 8080
  allowed_origins:
    - https://app.example.com
    - https://admin.example.com
database:
  url: postgres://db:5432/shop
logging:
  level: warn
  format: json

Comments — and why JSON lost configuration files

TOML and YAML both support # comments anywhere in the file — the annotation that makes a config file self-documenting ("# staging only, remove before prod") instead of relying on a separate README or a commit message nobody will read again. JSON, per RFC 8259, has no comment syntax at all: a # or // in a .json file is a parse error, full stop, which is the single biggest reason JSON lost the config-file role it briefly held in the mid-2010s (npm's package.json being the enduring exception, kept for historical and tooling-compatibility reasons rather than because JSON is pleasant to hand-edit).

Where JSON-like syntax with comments is genuinely wanted, the answer isn't ad-hoc — it's JSON5 or JSONC (JSON with Comments, the dialect VS Code's own settings.json uses), both supersets of JSON that add comments and a few other conveniences while staying close enough to parse with a relaxed JSON parser. This site's JSON5 Formatter handles exactly that dialect if you're maintaining a JSONC-style file rather than migrating away from JSON entirely.

Types: TOML's first-class dates, YAML's implicit typing, JSON's six values

JSON's type system is the shortest to describe because it's exhaustive: string, number, boolean, null, object, array — six kinds, no more, no native date type, and no integer/float distinction beyond what the value itself looks like. TOML goes the other direction, with the richest built-in type set of the three: strings (four different quoting styles for different escaping needs), 64-bit integers, floats, booleans, and — uniquely — four native date/time types (offset date-time, local date-time, local date, local time), each with its own unambiguous syntax. There is no TOML null; a key either has a value or doesn't exist.

YAML's type system is the one that causes production incidents, because it's IMPLICIT: a bare scalar's type is inferred from its text by a set of resolution rules, and those rules changed between YAML 1.1 and 1.2. The canonical trap — nicknamed the Norway Problem — is a country code of NO: under YAML 1.1's Core Schema (what older parsers like PyYAML's default loader and SnakeYAML implement), the bare word NO resolves to the boolean false, not the string "NO". YAML 1.2 narrowed the set of words that resolve to booleans (only true/false survive unquoted), which fixes the Norway case but means the SAME FILE can parse differently depending on which YAML version reads it — the honest fix, in any version, is to quote a value whenever its bare form could be misread.

Nesting and repetition: tables, indentation, braces

All three represent nested structure and repeated structure, but the ergonomics diverge sharply once a list of objects shows up. TOML's array-of-tables syntax ([[bin]], repeated once per element) reads well for a handful of similarly-shaped records — see the example in the TOML to JSON page — but gets unwieldy past a dozen or so, at which point an inline array of inline tables is usually more compact. YAML's dash-prefixed list items nest naturally under any key at any depth and stay readable even heavily nested, which is exactly why Kubernetes manifests — deeply nested container specs, volume mounts, environment variable lists — are YAML and not TOML. JSON's braces and brackets nest arbitrarily deep with zero ambiguity, at the cost of density; a JSON file five levels deep is a wall of closing braces that YAML's indentation makes visually obvious for free.

YAML alone offers anchors (&name) and aliases (*name) — a way to define a block once and reference it elsewhere without repeating it, which is genuinely useful for Docker Compose service defaults or CI job templates that share most of their configuration. Neither TOML nor JSON has an equivalent; converting FROM YAML to either format always resolves anchors into their full expanded content, because there's nowhere else for the reference to go.

Who standardized on what

The format a tool chose is rarely arbitrary — it usually reflects exactly the trade-offs above: does a human write this file by hand, does it need comments, does it nest deeply, does the ecosystem already have strong tooling in one format.

INI and .properties: the older cousins

Before TOML formalized the idea, plain INI files (section headers in [brackets], flat key=value pairs, no real nesting, no standardized spec) covered similar ground with far less precision — no defined types, no defined nesting, and every parser implementing its own dialect. TOML is best understood as "INI, but with an actual specification, real types, and a defined way to nest." Java's .properties format is the other flat-file cousin: strictly key=value, no sections at all, nesting simulated by convention through dotted keys (server.port=8080), and Spring Boot's own YAML support exists specifically because .properties' flatness becomes painful past a few dozen keys.

Converting between YAML's real nesting and .properties' dotted-key convention is common enough in the Spring Boot world that it's its own pair of tools here: YAML to Properties flattens a nested application.yml into dotted keys, and Properties to YAML reverses it, rebuilding real nesting (and even keeping your # comments, which the TOML and JSON converters below cannot do, since neither format's grammar attaches comments to the parsed value the way this dedicated flattening logic can).

A decision guide

None of these formats is objectively better — each optimizes for a different reader. The table below is the practical version of everything above.

Converting between them without losing meaning

Every conversion between these formats is lossy in a specific, predictable way, and knowing which loss applies to your direction is the difference between a confident migration and a surprised bug report. YAML → anything loses comments (nothing else has them) and resolves anchors/aliases into their full expanded content. Anything → TOML loses null (there's nothing to convert it to, so it's omitted or rejected, your choice — see JSON to TOML). TOML → JSON keeps everything except the format of dates (which become plain ISO strings) and needs a string fallback for 64-bit integers past what a JSON number can hold exactly (see TOML to JSON).

The tools on this site that make these specific conversions: TOML to JSON and JSON to TOML for the TOML/JSON pair, TOML Formatter to validate or normalize a TOML file on its own, and YAML to Properties / Properties to YAML for the Spring Boot–style flattening pair discussed above. For the YAML/JSON pair specifically — not covered by this guide in depth since it's the more established of the three — see JSON to YAML, YAML to JSON, and the general YAML vs JSON comparison.