--- url: https://findutils.com/blog/config-format-conversion-what-survives title: "Config Formats Compared: What Survives a Conversion" description: "INI, .env, .properties, JSON, YAML and TOML do not hold the same things. Read which values, types, comments and structures survive when you convert between them." category: developer content_type: blog cluster: configuration locale: en read_time: 8 status: published author: "olgunozoktas" published_at: 2026-09-16T20:00:00Z og_image: "/images/content/blog/config-format-conversion-20260916.webp" image_alt: "Four containers in a row on an oak table - a glass jar, a ceramic dish, a compartment box and a brass tray - each holding the same blank cream cards, with two cards left over beside the fullest one." updated_at: "2026-09-16T20:00:00Z" excerpt: "A config converter can produce a valid file that means something different. Comments vanish, a null has nowhere to go, and a port number quietly becomes an integer. Read what each format can and cannot carry." tag_ids: ["configuration", "data-conversion", "yaml", "developer-tools"] tags: ["Configuration", "Data Conversion", "YAML", "Developer Tools"] primary_keyword: "config format conversion" secondary_keywords: ["ini vs toml", "yaml vs toml", "dotenv to yaml", "config file formats compared", "convert config file", "configuration format differences"] tool_tag: "ini-json-converter" related_tool: "ini-json-converter" related_tools: ["ini-json-converter", "yaml-toml-converter", "env-yaml-converter", "json-yaml-converter", "properties-json-converter"] --- Every configuration format is a different bet about what configuration is. Converting between them is not a formatting change: it is moving data into a container that may not have a place for part of it. A converted file can parse cleanly and still mean something different from the one you started with. This post covers what each common format can actually hold, which conversions are lossless, where the losses are, and how to check a converted file before you trust it. ## What Can Each Format Actually Hold? The differences that matter are types, nesting, and whether the format has a specification at all. | Format | Spec | Types | Nesting | Comments | Null | |---|---|---|---|---|---| | INI / .cfg | None | Strings only | One level of `[section]` | `;` and `#` | No | | .env (dotenv) | None | Strings only | Flat | `#` | No | | .properties | Java docs | Strings only | Flat, dotted keys by convention | `#` and `!` | No | | JSON | RFC 8259 | String, number, bool, null | Unlimited | **None** | Yes | | YAML | YAML 1.2 | Plus dates, anchors | Unlimited | `#` | Yes | | TOML | TOML 1.0 | Plus dates, times | Tables, arrays of tables | `#` | **No** | Two rows explain most conversion surprises. **INI, .env and .properties have no specification** — every reader invented its own rules, so a converter has to state which dialect it implements rather than claim to read "INI". And **TOML has no null**, which means a JSON or YAML document containing one cannot round-trip without a decision. ## Which Conversions Are Actually Lossless? Lossless means you can convert back and get the same data. Not the same file — the same data. - **Flat string map to flat string map** is lossless. `.env` to a flat YAML map, or `.properties` to flat JSON, loses nothing but comments. - **JSON to YAML and back** is lossless for data. Both have the same type model. - **YAML to TOML** is lossless *only* if the document has no nulls, no top-level list, and no anchors you wanted preserved. - **INI to JSON and back** is lossless for structure, because sections map to one level of objects. It is not lossless for comments. - **Anything to INI** is lossy the moment your data has an array or two levels of nesting. Comments never survive any of these, because JSON has nowhere to put them and every converter reads data rather than documentation. If the comments in a config carry meaning — and in a production config they usually do — keep the original file. ## Why Does a Port Number Come Back as a String? Because the reader that fed it to your program returned a string. `PORT=3000` in a `.env` is the string `"3000"` to `process.env`. `port = 8080` in an INI file is text to every INI reader. Writing them as JSON numbers would be describing a different file. This is why a careful converter keeps values as strings by default and makes type inference an explicit choice. Turn it on when a schema or a typed config library expects real types. Leave it off when the consumer reads environment variables, because everything it receives will be a string regardless. One value should stay text even with inference on: anything with a leading zero. `007` is an identifier. `7` is a different value. ## What Happens to a Null? TOML has no null, so a converter has exactly two honest options and should tell you which one it took: - **Drop the key.** The consumer falls back to its default. - **Write an empty string.** The consumer receives a value that overrides its default. Those are different outcomes, which is why "the converter handled it" is not good enough. FindUtils [YAML TOML Converter](/developers/yaml-toml-converter/) makes this a visible setting and lists every path it changed under the panels, so a dropped key is something you read rather than discover later. ## Why Do Merge Keys Expand? YAML lets you define a block once and reuse it with an anchor and a `<<` merge key. Compose files and CI pipelines lean on this heavily. TOML has no way to reference another table, so a converted file spells every reuse out in full. That means the TOML output is longer than the YAML input, and the shared block is no longer shared: editing it later will not change the places that used it. This is a real change in the document's meaning, not just its size, and it is worth knowing before you replace the original. ## How Do You Check a Converted File? Convert back and compare the data, not the text. 1. **Round-trip it.** Convert A to B, then B back to A, and compare against the original with a diff tool. Formatting will differ; values should not. 2. **Read the warnings.** Duplicate keys, dropped nulls and nesting conflicts are reported by a good converter and silently resolved by a bad one. 3. **Count the keys.** A key count that shrank is the fastest signal something was dropped. 4. **Check the types.** Look specifically at ports, versions, zero-padded identifiers and anything that looks like a date. 5. **Re-read the comments you lost.** Open the original and check whether any comment recorded a decision that now lives nowhere. ## Where the Conversion Should Happen A configuration file is one of the worst things to paste into an upload form. `php.ini`, a database `.conf`, a `.env` — these routinely carry hostnames, usernames and passwords, and an upload-based converter means those values reached someone else's server. Every converter referenced here runs in the browser. The file is read locally, converted locally, and never transmitted. The page itself loads analytics and advertising scripts like the rest of the site, but your configuration is not part of that traffic. ## Tools Used in This Post - **[INI JSON Converter](/developers/ini-json-converter/)** — `.ini`, `.cfg` and `.conf` sections to nested JSON and back - **[YAML TOML Converter](/developers/yaml-toml-converter/)** — YAML to TOML 1.0 with an explicit nulls policy - **[Env YAML Converter](/developers/env-yaml-converter/)** — `.env` to a flat YAML map or a Compose/Actions snippet - **[Properties JSON Converter](/developers/properties-json-converter/)** — Java `.properties` with continuations and escapes - **[JSON YAML Converter](/developers/json-yaml-converter/)** — the lossless pair ## FAQ **Q: Which config format should I choose for a new project?** A: TOML when you want types and a specification without YAML's complexity, YAML when you need deep nesting or the ecosystem expects it, and `.env` for per-environment secrets that never belong in a committed file. INI only when something you cannot change already reads it. **Q: Is converting a config file safe?** A: The conversion is safe when it runs locally. The risk is not the conversion but the transport: a browser-based converter never sends the file anywhere, while an upload-based one does. **Q: Why did my converter refuse an array?** A: Because INI has no array syntax every parser accepts. Repeated keys, comma-separated values and `key[]` are all in use. A converter that picks one produces a file that works in one program and silently loses data in another. **Q: Do comments ever survive a conversion?** A: Not through JSON, which has no comment syntax, and not through most YAML and TOML writers either. Treat conversion as a data operation and keep the original file for its documentation. **Q: What is the safest conversion to automate?** A: A flat string map between two flat formats — `.env` to a YAML map, or `.properties` to flat JSON. There are no types to infer, no nesting to flatten and no nulls to place. ## Next Steps - Converting a legacy config? Start with the [INI JSON Converter](/developers/ini-json-converter/). - Moving a project onto TOML? The [YAML TOML Converter](/developers/yaml-toml-converter/) reports every null it drops. - Promoting a `.env` into CI? The [Env YAML Converter](/developers/env-yaml-converter/) writes the snippet shapes.