JSON vs TOML for config

JSON and TOML both describe structured data, but they were designed for different jobs. Knowing which fits configuration, and which fits data exchange, saves a lot of friction.

Where JSON struggles as config

JSON is excellent for machines talking to machines: it is everywhere, every language parses it, and its structure is unambiguous. As a human-edited config format, though, it has two real pain points: it has no comments, so you cannot annotate why a setting exists, and its strict syntax (quotes on every key, no trailing commas) makes hand-editing error-prone. Those are exactly the things you want when a person maintains a config file.

What TOML adds

TOML was designed specifically for configuration that humans write. It supports comments, reads more like an INI file, and has first-class syntax for the things configs actually contain: dates, nested tables, and arrays. A TOML file tends to be more readable and more forgiving to edit by hand:

# server settings
[server]
host = "0.0.0.0"
port = 8080

The trade-off is that TOML is less universal than JSON and gets awkward for deeply nested or highly dynamic structures, where JSON's uniformity is an advantage.

Choosing, and converting

A reasonable rule: TOML for files people edit (app config, tool settings), JSON for data that moves between systems (APIs, storage). Many projects use both.

The two map cleanly onto each other for most structures, so converting is straightforward, with one caveat: comments do not survive a round trip to JSON and back, because JSON has nowhere to put them. The JSON ↔ TOML Converter converts in either direction in your browser. If your config lives in YAML instead, see YAML to JSON and back.