JSON vs YAML vs TOML: which config format should you use?

JSON is the default answer for configuration these days, but it's not the only one. YAML and TOML were both created to solve real problems with JSON as a config format. Here's a practical comparison of the three, and how to pick the right one for your project.

The same data, three ways

Take a simple config with a name, a port, and a list of features:

JSON

{
  "name": "my-service",
  "port": 8080,
  "features": ["auth", "logging"]
}

YAML

name: my-service
port: 8080
features:
  - auth
  - logging

TOML

name = "my-service"
port = 8080
features = ["auth", "logging"]

Same data, three different philosophies: JSON optimizes for machines, YAML optimizes for humans, TOML sits in between.

Side by side

When to use which

• JSON — for anything two programs exchange over a network: APIs, messages, data files. It's the only one of the three that's really designed as a data interchange format.
• YAML — for config files humans edit often and read closely, like CI pipelines and Docker Compose. The trade-off is a famously hairy parser.
• TOML — for config that's mostly flat key-value pairs, like Rust's Cargo.toml or Python's pyproject.toml. It gives you comments without YAML's complexity.

Why JSON still wins most of the time

For all its rough edges as a hand-edited format, JSON's killer feature is that everything speaks it. Every language has a parser in its standard library, every API returns it, and it's the only format that doubles as both config and wire format. The friction of YAML or TOML is often not worth it unless comments and readability are a genuine, everyday need.

The other formats are a workaround for JSON's strictness, not a replacement. If your JSON config feels painful to hand-edit, the alternative isn't always switching to YAML — it's often just using a relaxed JSON syntax that keeps the ecosystem compatibility. That's the niche JSON5 fills: comments, trailing commas, and unquoted keys, while staying a strict superset of JSON.

Bottom line

Use YAML when humans are the primary audience, TOML for simple flat config, and JSON everywhere else. And when you do work with JSON — strict, relaxed, or a little broken — the JSONGuy formatter handles it without you having to fix the syntax by hand.