Convert INI to JSON

The result is a single JSON object. Each section header becomes a key holding an object of its own, and the key-value pairs under that header become that object properties. Keys written before any section header — the ones a lot of tools call the global block — sit at the top level next to the section objects rather than under a wrapper of their own.

That is the whole structural translation, because there is nothing else in an INI file to translate. What makes this pair worth reading about is not the shape but the values, which do not survive the trip as literally as the shape does.

An INI file has no types. Everything after the equals sign is characters, and every program that reads one decides for itself what those characters mean. This reader decides like this: the exact strings true and false become JSON booleans, anything that parses as a finite number becomes a JSON number, and everything else stays a string.

For most configuration that is the right call and saves you a pass of parseInt on the other side. A port comes out as 8080 rather than "8080", a timeout as 30, and a negative flag like -1 as a number you can compare. The cost is that the reader cannot tell a quantity from an identifier, and that is where the damage happens.

Four cases fail quietly and all four appear in real config files. A zero-padded identifier written 007 becomes the number 7. A Unix file mode written 0755 becomes 755, which is a different mode and will be applied as one. A hexadecimal mask written 0x1F becomes 31, correct in value and wrong in every log line that prints it back. A version pinned as 1.0 becomes 1.

The fourth is subtler: an integer larger than about nine quadrillion loses precision, because JSON numbers are IEEE doubles. A 64-bit identifier written 9223372036854775807 comes out as 9223372036854776000. Nothing warns you. If a key holds a snowflake ID, a serial number or an account reference, quote it in the source INI file — quoted values still get parsed, so the surer fix is to prefix or suffix it with something non-numeric, or to correct the value in the JSON afterwards.

It is worth knowing which keys you do not need to check. Anything with a unit attached is safe, so a memory limit written 128M stays the string 128M. Dotted addresses stay strings, so 127.0.0.1 comes through untouched. Clock times like 08:00 stay strings, as do paths, URLs, and anything containing a letter that is not part of a number.

A value containing an equals sign survives too, because the line is split at the first equals sign only, which keeps a connection string or a query parameter intact. Surrounding quotes are stripped, but only the outermost pair — a value written with padding inside the quotes keeps that padding, while an unquoted value is trimmed at both ends. Inside those quotes, and only there, a backslash starts an escape: a backslash and an n become a line break, and two backslashes become one. That is what lets a multi-line value survive the trip out to INI and back, and it is why an unquoted Windows path such as C:\new is read exactly as written while the same path inside quotes is not.

Windows INI files and php.ini use On and Off far more often than true and false, and the reader does not treat them as booleans. They come out as the strings "On" and "Off", which is defensible — they are, after all, just words — and is nearly always not what the consumer of the JSON expects.

The same applies to yes and no, and to 1 and 0 used as flags, which become the numbers 1 and 0 rather than booleans. Whatever reads the JSON has to decide what counts as truthy, and the safest habit is to normalise those keys explicitly in the consuming code rather than assume the conversion made them consistent. A config with engine set to On and debug set to false now has two different kinds of yes in it.

Key order is preserved almost everywhere, which matters when you are reading a diff rather than a machine. Sections come out in the order they appeared, and keys within a section keep the order they were written in.

The exception is numeric keys. JavaScript objects put integer-like keys first and in ascending numeric order, ahead of every other key, so a section written 10, 2, name comes out as 2, 10, name. INI files that use numbers as keys — server lists, ordered rules, playlist entries — come out reordered. If order is meaning in your file, that section wants to be a JSON array, and turning it into one is a manual edit.

INI has no specification, so implementations disagree about repeated section headers: some merge them, some keep both, some take the last. This reader starts a fresh, empty section every time it meets a header, so a file containing [logging] twice keeps only the keys from the second block. The first block is gone, and the JSON is valid, and nothing reports it.

That pattern shows up whenever configs are assembled by concatenation, which is a common deployment trick — a base file plus an environment overlay, appended. Grep the source for duplicate headers before converting. Duplicate keys inside one section behave the same way, with the last assignment winning.

This is the loss that is structural rather than incidental. INI supports comments and uses them heavily; JSON, as specified in RFC 8259, has no comment syntax at all. Even a converter that wanted to preserve them would have nowhere to put them, short of inventing a convention like a _comment key that no consumer would read.

On a settings file this is often the largest thing you lose. The note recording why a pool size is 12 rather than the default, the commented-out block kept as an example, the line marking a value as tuned for one customer — none of it comes across. Keep the original INI file in version control next to the JSON rather than treating the conversion as a replacement.

The output is ordinary JSON with two-space indentation, so jq, Node, Python and every JSON Schema validator read it without ceremony. A section becomes an object path — .database.host in jq — and a schema can then assert that the port is a number and the host is a string, which is the actual gain over the INI file, since an INI file cannot be validated by anything.

Conversions of files this size are instant and run entirely in the browser, with a 100 MB ceiling on the free tier that no configuration file will ever reach. The practical constraint is not size but review: read the numeric values in the output once, before the JSON becomes the file everything else trusts.