YAML, TOML, JSON5: When Each Format Wins
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:
- No comments. You cannot explain in the file why a value is set the way it is.
- No trailing commas. Add an element to a list, you forget the comma on the previous line, you get a parse error twenty lines later.
- Quoted keys.
{"databaseHost": "localhost"}is annoying to type.{databaseHost: "localhost"}would be fine but JSON does not allow it. - No multiline strings. A SQL query in JSON has to have its newlines written as
\n.
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:
- Significant indentation reduces visual noise compared to JSON's braces.
- Comments work and look natural.
- Multiline strings via
|(preserve newlines) or>(fold to spaces). - Anchors and aliases for deduplication within a file.
What YAML gets wrong (and why it has a reputation for footguns):
- The Norway problem. In YAML 1.1, the unquoted value
NOparses as booleanfalse, as dono,off, and similar words. Quote strings that look like booleans. - Base-60 numbers. In YAML 1.1, an unquoted
22:22can parse as the sexagesimal integer 1342. Quote times and similar values such as port mappings. - Significant whitespace. Indentation defines structure and YAML forbids tabs for indentation, so one misplaced space can silently move a key to a different level.
- Two specs. YAML 1.2 removed most of the 1.1 coercions, but many libraries still follow 1.1 behavior, PyYAML among them. The same file can parse differently in two tools.
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:
- Comments work naturally.
- Trailing commas are allowed in arrays. Inline tables allow them only from TOML 1.1, released in December 2025, so older parsers will reject them.
- Native datetime types with explicit syntax.
- String types are explicit: basic, literal, multiline basic, multiline literal.
- No significant whitespace gotchas.
What TOML gets wrong:
- Deeply nested structures get awkward, because each level repeats the full table path in its header.
- Fewer tools accept it than JSON or YAML, and parsers differ in how quickly they adopt new spec versions. Python's standard
tomllibcan read TOML but not write it. - The array-of-tables syntax (
[[entries]]) takes getting used to.
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:
- It is a strict superset of JSON. Existing JSON files work as-is.
- Migration is small: the file can stay as it is, though whatever reads it needs a JSON5 parser.
- Trivial to remember if you already know JSON.
What JSON5 gets wrong:
- Fewer libraries and tools support it than YAML and TOML.
- Many tools accept JSON or YAML but not JSON5. Be aware of JSONC, a different format, which is JSON with comments, used by files such as
tsconfig.json. - Multiline strings are limited to a backslash at the end of each line, which keeps the text on one logical line. There is no block syntax like YAML's
|.
Use JSON5 when your config is JSON-shaped but you want comments, and you control the parser that reads it.
The decision matrix
- Cloud-native tool config (Kubernetes, CI/CD, infra-as-code)? YAML. Fighting the ecosystem is not worth it.
- Rust or Python package config, or anything resembling a manifest? TOML. Those ecosystems expect it.
- Existing JSON config you want to annotate, and you control the parser? JSON5.
- Deeply nested data with many references? YAML, using anchors and aliases.
- Brand new project, flat config, want predictable parsing? TOML.
- You need to ship the config to a service that only accepts JSON? Plain JSON and accept the pain, or use JSON5 with a conversion step in your build.
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:
- YAML to JSON: YAML supports keys that are not strings (booleans, numbers). JSON does not. Conversion may need to coerce.
- JSON to YAML: large multiline strings should ideally use YAML's
|block style for readability, not single-line escaped strings. - TOML to JSON: TOML's datetime types become strings; you lose type information unless your JSON consumer uses a schema.
- JSON5 to JSON: comments are stripped, so do not rely on them surviving.
InfinityandNaNneed a decision, since JSON cannot represent them.
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.