YAML, TOML, JSON and INI: Converting Config Without Breaking It

Every tool picks a configuration format and every tool picks a different one. Sooner or later you have settings in YAML and something that only reads TOML, or a JSON blob you want to make readable. The conversion itself is usually trivial. The interesting part is the handful of places where it changes what the file means.

The one thing you always lose#

Comments. YAML, TOML and INI all support them; JSON does not, and no converter can invent a place to keep them. A config file's comments are frequently the only documentation a setting has, so this is not a cosmetic loss.

What each format is good at#

• JSON is unambiguous and universally parsed, and it is genuinely unpleasant to hand-edit. No comments, no trailing commas, and quotes around everything.
• YAML is the most comfortable to read and the easiest to get subtly wrong, because indentation carries meaning and several bare words are interpreted as values rather than text.
• TOML aims to be obvious. Explicit types, explicit tables, few surprises. It is a good destination when a file is edited by people.
• INI is the oldest and the simplest: sections and key-value pairs, no nesting, no types. Everything is a string until something else decides otherwise.

The common moves are YAML to JSON when a program needs to parse it, JSON to TOML when a person needs to edit it, and TOML to JSON when a build step demands it.

The traps that actually bite#

YAML turns some words into values#

In YAML, an unquoted no can be read as a boolean false, and a country code like NO is the classic example. Version numbers such as 1.10 can be read as numbers and lose the trailing zero. When converting out of YAML, look hard at anything that was not quoted.

INI has no nesting and no types#

Converting nested structure into INI either flattens it or fails. Neither is a bug; INI simply has no way to express a map inside a map. Going the other way, every INI value arrives as a string, so a port number becomes text rather than a number until something converts it.

Key order is not meaning#

Most parsers treat a mapping as unordered, so a converted file may list keys in a different order. That is almost always harmless and occasionally matters, so diff the parsed values rather than the raw text when checking a result.

A sane way to check the result#

1. Feed the converted file to the tool that will consume it, in a scratch environment, before anything real depends on it.
2. Compare the values that matter by name rather than scanning the whole file.
3. Look specifically at booleans, version strings and anything that was unquoted in the source.
4. Keep the commented original beside the generated file and note which one is authoritative.

If the data is tabular rather than hierarchical, the CSV, JSON and Excel guide covers that shape instead, and the general checking habit is in verifying conversion results.