Config File Formats Compared: Pick a Default

The first question is almost always comments. JSON simply has none, which is disqualifying for many config files, since you cannot explain why a value was chosen. YAML, TOML and INI all support the hash-style # comment, letting you document each setting inline. On raw readability, YAML and TOML are the most pleasant — YAML for its minimal punctuation, TOML for its clearly labelled sections — while deeply nested JSON becomes a wall of braces that is hard to scan.

Readability at scale depends on the punctuation each format demands. A JSON config four levels deep ends in a run of closing braces and brackets that tells you nothing about which block just closed. YAML removes that noise entirely but replaces it with a different cost: at 300 lines you count columns to work out where you are, and a block pasted at the wrong depth is often still valid, just attached to the wrong parent. TOML's bracketed headers act as signposts — you always know which section a line belongs to — and INI has the same property for the shallow files it can express.

The formats diverge sharply on data types. JSON and TOML are explicit: a quoted value is a string, a bare number is a number, full stop. YAML infers types, which is convenient until it guesses wrong. INI, the simplest of the four, treats almost everything as a string and has no standard for nesting at all. For deeply nested structures, YAML and JSON are the most natural; TOML handles nesting through dotted tables but grows awkward past two or three levels; INI is really only suited to flat, section-based settings.

Three type details matter more than they look. YAML's inference is the source of the Norway problem, where an unquoted NO becomes false, and of version strings such as 1.10 that silently turn into numbers. JSON numbers are read as doubles by most parsers, so an identifier above 2^53 loses precision, while TOML guarantees at least 64-bit signed integers and gives you real RFC 3339 dates. And duplicates differ: TOML makes a repeated key a hard error, whereas JSON's specification only says keys should be unique and most parsers — like many YAML and INI ones — quietly keep the last occurrence, which turns a bad merge into a behaviour change nobody notices.

Beyond syntax, ask what checks the file before it runs. JSON Schema is the most widely supported option, and through SchemaStore it powers autocompletion and inline errors for hundreds of well-known filenames in VS Code and JetBrains editors — and because YAML 1.2 is a superset of JSON, the same schemas validate YAML too. TOML has no equally universal schema language, so validation usually lives in the tool that reads the file, such as Cargo or a Python build back end. INI has neither a specification nor a schema: what a quote or a dot means depends on the library, which is exactly why it is a weak choice for anything new. Parser availability matters as well — JSON is everywhere, TOML reading is in Python's standard library from 3.11, and YAML almost always means a third-party dependency.

The defaults around you encode a lot of experience. Node uses package.json because the tooling is JavaScript and JSON parsing is free, and accepts that comments are impossible — which is why tsconfig.json quietly moved to the commented JSONC dialect. Rust's Cargo.toml and Python's pyproject.toml chose TOML for hand-edited metadata with explicit types. Docker Compose files, Kubernetes manifests, Ansible playbooks and GitHub Actions workflows all use YAML because their data is deeply nested and generated as often as it is typed. Git config and systemd units stay INI-shaped because they are flat and old. The pattern is consistent: depth and machine generation pull towards YAML and JSON, hand-editing pulls towards TOML.

For a flat-to-moderate configuration that humans edit often, TOML is a strong default: comments, explicit types and no whitespace traps. For deeply nested infrastructure config — think Kubernetes — YAML is the ecosystem standard and hard to avoid. Reserve JSON for config that is generated or consumed by machines rather than hand-edited, and keep INI for the simplest flat cases or legacy tools that require it. When in doubt, pick the format your ecosystem already expects, because that is where the schemas, the editor support and your colleagues' instincts already are.

Whatever you choose, MarkupSuite converts a config between YAML, TOML and JSON, so migrating a default is a paste and a click rather than a rewrite. Convert to JSON first to see exactly what the current parser produces, then out to the new format — and plan to re-add the comments by hand, because they do not survive the JSON step.