Config File Formats Compared: JSON vs YAML vs TOML vs .env

Every config format is solving the same basic problem — key/value settings a program reads at startup — with different tradeoffs between how much a human can comfortably hand-edit and how much structure the format can express.

The four in short

JSON is the strictest and most machine-friendly: quoted keys and strings, no comments, unlimited nesting. It shows up as config when a tool generates or consumes it programmatically (package.json, tsconfig.json) rather than when a human is expected to hand-edit it often.

YAML trades strictness for readability: no required quotes, indentation instead of braces, full comment support, and arbitrary nesting. It’s the default for config a person edits directly and reviews in a diff — Kubernetes, GitHub Actions, Docker Compose.

TOML sits between the two: explicit [section] headers instead of YAML’s indentation-based nesting (so no tabs-vs-spaces ambiguity), full comments, but shallower nesting is more awkward to express than in YAML. It’s become the config format of choice for tools that want YAML’s readability without YAML’s implicit-typing footguns — Cargo.toml, pyproject.toml.

.env is the simplest of all — flat KEY=value lines, comments with #, no real nesting at all. It’s not trying to express structured config; it’s specifically for environment variables, which are inherently a flat namespace in every OS.

Picking one

If the config is deeply nested and mostly machine-written, JSON. If a person edits it directly and it needs comments and nesting, YAML (accept the implicit-typing gotcha — see the JSON vs YAML guide). If you want YAML’s comments without its ambiguity and your structure is fairly flat, TOML. If it’s genuinely just environment variables, .env — don’t reach for a nested format to express a flat namespace.

Converting between them? Try JSON to YAML, JSON to .env, or .env to JSON.

Frequently asked questions