YAML, TOML, JSON5: When Each Format Wins

By BoltQuickTools team · May 18, 2026 · Updated November 8, 2026 · 6 min read

JSON is the default for API payloads and machine-to-machine messages, but it is awkward as a config file written by people. YAML, TOML, and JSON5 are the common alternatives. They are not interchangeable, and each has failure modes worth knowing before you commit.

Why JSON is awkward for config

JSON is a great data format because it is unambiguous and machine-friendly. Those same properties make it painful to hand-edit:

All three contenders fix some of these. None fix all of them in the same way. The right choice depends on which fixes matter to you.

YAML: expressive, widely used, full of surprises

YAML is the default for much of the infrastructure world: Kubernetes, Docker Compose, GitHub Actions, GitLab CI, and Ansible all use it. If you work on deployment config, you will write YAML.

What YAML gets right:

What YAML gets wrong (and why it has a reputation for footguns):

Use YAML when: you are integrating with the cloud-native ecosystem, you need multiline strings, you have deeply nested configs, or your team is already comfortable with the gotchas.

TOML: simple, explicit, less expressive

TOML was designed as a configuration format. Rust's Cargo uses it, Python packaging uses it in pyproject.toml, and Hugo supports it. Its values have explicit types, so there is much less type guessing than in YAML, although a table can still be written in more than one way (header, dotted keys, or inline).

# Cargo.toml style
[package]
name = "my-crate"
version = "0.1.0"
authors = ["Example Author <[email protected]>"]

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = "1.34"

What TOML gets right:

What TOML gets wrong:

Use TOML when: your config is mostly flat with a few nested sections, you are in the Rust or Python ecosystem, or you value predictability over expressiveness.

JSON5: JSON with the rough edges sanded off

JSON5 is JSON plus a small set of extensions: comments, trailing commas, unquoted keys, single-quoted strings, and extra number forms. It converts to JSON cleanly apart from losing comments, with one exception: JSON has no Infinity or NaN, so values like the one below have no direct JSON equivalent.

{
  // Comments work
  databaseHost: 'localhost',     // unquoted keys, single quotes
  port: 5432,
  maxConnections: 100,           // trailing comma OK
  timeout: +Infinity,            // number syntax extensions
}

What JSON5 gets right:

What JSON5 gets wrong:

Use JSON5 when your config is JSON-shaped but you want comments, and you control the parser that reads it.

The decision matrix

The conversion problem

Projects often need to convert between these: a pipeline reads YAML and emits JSON for downstream tools, or a team writes TOML and ships JSON to a frontend. The JSON/YAML converter and TOML converter do this in your browser; their conversion code makes no network request with your input.

Common conversion gotchas:

How to choose

There is no universally correct answer. Start from what your ecosystem expects, then from the shape of your config. If tools you depend on already require a format, the choice has been made for you.

Related