JSON Drift
Back to blog
Comparison9 min read

JSON vs YAML vs TOML: Choosing a Config Format

A practical comparison of JSON, YAML, and TOML for configuration: readability, type safety, comments, the YAML gotchas, and a simple rule for picking the right format for your project.

By Saifur Rahman Shochib

Pick a config format and you live with it for years. JSON, YAML, and TOML all describe structured settings as text, but they make very different trade-offs between machine-friendliness, human readability, and safety. This guide compares them on the things that actually bite you in production — types, comments, ambiguity, and tooling — and ends with a one-line rule for choosing.

The three formats in brief

JSON is the universal data interchange format: strict, unambiguous, parsed by every language, and built into browsers — but with no comments and a lot of punctuation. YAML reads almost like prose, uses indentation instead of braces, supports comments, and is the default for Kubernetes, Docker Compose, and most CI systems. TOML (Tom's Obvious, Minimal Language) targets configuration specifically, with a clear flat syntax, explicit types including dates, and no significant whitespace.

JSONjson
{ "title": "App", "port": 8080, "debug": true }
YAMLyaml
title: App
port: 8080
debug: true
TOMLtoml
title = "App"
port = 8080
debug = true

Readability

For a file a human edits often, YAML usually wins on first impression: minimal punctuation, comments, and prose-like flow. TOML is close behind and arguably clearer for flat or moderately nested config because its structure is explicit rather than indentation-based. JSON is the least pleasant to hand-edit — every string is quoted, every block is braced, and a single missing comma breaks the file.

Type safety and ambiguity

JSON and TOML are unambiguous: in both, the string NO is a string, 42 is a number, and true is a boolean, with no guessing. TOML goes further with native dates and a distinct integer/float distinction. YAML's convenience is also its risk — its type inference is famous for surprises, the most notorious being the 'Norway problem', where the country code NO is interpreted as the boolean false unless quoted.

That ambiguity means YAML rewards discipline (quote your strings) in exactly the files where mistakes are most costly. JSON and TOML remove the guesswork by design.

The classic YAML ambiguityyaml
country: NO     # YAML reads this as the boolean false
country: "NO"   # quote it to keep the string

Comments

YAML and TOML both support comments; standard JSON does not. For configuration, comments matter — they explain why a value is set, not just what it is. If you love JSON's strictness but need comments, JSON5 and JSONC add comment support as supersets of JSON, bridging the gap without moving to YAML or TOML.

When to use each

  • Use JSON when machines are the primary audience: APIs, data interchange, and config consumed by many languages where universal parser support outweighs everything else.
  • Use YAML when humans edit deeply nested config and readability is critical: Kubernetes, Docker Compose, GitHub Actions, and CI pipelines.
  • Use TOML when you want explicit, unambiguous application config that is still pleasant to edit: tool configs like Cargo, pyproject, and many CLI tools.

The one-line rule

Compressed to a single pattern: JSON when machines are the main audience, YAML when deeply nested humans are, TOML when flat humans are. Universal interchange leans JSON; richly nested human-edited config leans YAML; explicit, typed application config leans TOML. Match the format to who edits the file most and how nested it is.

Converting between them

Because all three model similar data, you can convert between them — useful when a tool demands one format but your source of truth is another. The YAML to JSON and JSON to YAML tools bridge YAML and JSON, and the TOML to JSON and JSON to TOML tools do the same for TOML. Converting to JSON is also a quick way to validate and inspect a YAML or TOML file with the wider JSON toolchain.

Frequently asked questions

Which is the best config format: JSON, YAML, or TOML?

There is no single winner — it depends on the audience. JSON suits machine interchange, YAML suits human-edited nested config (Kubernetes, CI), and TOML suits explicit, typed application config. Pick based on who edits the file and how nested it is.

What is the YAML Norway problem?

YAML's loose type inference reads the unquoted country code NO as the boolean false. It is the classic example of YAML ambiguity, and the fix is to quote strings that could be misread. JSON and TOML avoid this because their types are explicit.

Does JSON support comments like YAML and TOML?

Standard JSON does not support comments. YAML and TOML do. If you need comments in a JSON-like file, use JSON5 or JSONC, which are supersets of JSON that add comments and trailing commas.

Is TOML better than YAML?

For flat or moderately nested application config, many developers prefer TOML because it is explicit, strongly typed, and avoids YAML's whitespace and ambiguity gotchas. For deeply nested config, YAML's indentation can be more readable. Both beat JSON for hand editing.

Can I convert YAML or TOML to JSON?

Yes. Converters map the shared data model between formats. Converting YAML or TOML to JSON is also a handy way to validate the file and inspect it with the broader JSON toolchain.

Related tools

Try these tools

Keep reading

Related guides