Convert XML to TOML

Every element with children becomes a table, written as a bracketed header naming the full path with dots. An element three levels down produces one header containing three names rather than three nested blocks, because TOML expresses depth in the header rather than in the indentation.

Within each table, plain values come first and nested tables follow, which is the only order TOML permits — everything under a header belongs to it until the next header appears. That means the output does not read in the same order as the XML, and on a config with many small elements the rearrangement is substantial. It is a reordering, not a change: no value moves to a different path.

This is the part of the conversion that needs no repair. Two or more sibling elements with the same tag become a TOML array of tables, with the double-bracket header written once per item in document order. A list of dependencies, a list of servers, a list of rules — all of them land in the shape a TOML config would have used anyway.

The familiar XML caveat still applies underneath it. A single occurrence of a repeatable element is not an array, so it becomes a plain table with a single-bracket header instead. Convert a file with one entry and the same file with two, and the two outputs differ structurally. If the config is generated or checked into a repository, that is a diff you want to understand before it appears.

TOML bare keys allow letters, digits, underscores and hyphens and nothing else. Attributes arrive from the parser as keys beginning with @, an element own text under a key named #text, and a namespace declaration as something like @xmlns:soap. All of them are quoted in the output, which is correct TOML and looks exactly as odd as it sounds.

They are also a to-do list. A quoted key is the converter telling you that this name came from XML machinery rather than from your configuration, and almost every one of them should be renamed: an @value attribute becomes a plain value key, an @xmlns key is deleted, a #text key becomes whatever the element was actually holding. Do that pass once, immediately, while you still remember what the XML meant.

A TOML document is itself a table, and an XML document has exactly one root element, so the entire config appears one level deeper than you want it — under a single header named after the root. A file rooted at configuration produces a configuration table containing everything.

Promoting the contents is a mechanical edit: delete the first header and remove that segment from every other header in the file. It is worth doing rather than living with, because every path in the config gets a level shorter and a TOML file is read by its headers. Doing it by hand also forces one pass over the whole file, which on a migration is time well spent.

TOML has no null value, and converting from formats that do — YAML in particular — means keys quietly disappearing when their value is empty. That cannot happen here, because XML has no null either. An empty element and a self-closing element mean the same thing and both become an empty string, written as two quotes.

So the guarantee for this direction is stronger than for its neighbours: every element that had a value in the XML has a key in the TOML. Empty strings are easy to overlook in a long file, though, so if the migration is also a chance to remove settings nobody uses, searching the output for those empty pairs is the fastest way to find them.

TOML puts date and time in the core specification — offset datetimes, local datetimes, local dates and local times — and a parser hands them back as dates rather than strings. YAML has a timestamp tag too, but it belongs to the 1.1 type library rather than the 1.2 core schema, so what a loader returns is a matter of which loader it is. TOML’s four types are not.

An XML value is text, so a date in the source arrives as a quoted string and stays one. Unquoting those values in the output is what turns them into real TOML dates, and it takes a minute. The reverse case is worth watching too: a value written 1.0 in the XML is parsed as a number and written as the TOML integer 1, so a version has become an integer and lost its form. Quoting it back is the fix.

An element containing several lines — a description, a licence block, an embedded script — becomes a single TOML basic string with backslash-n escapes where the newlines were. It is correct and it is unreadable, and it defeats the purpose of moving to a format people edit by hand.

TOML has a multi-line string syntax with triple quotes that holds such a value legibly, and the writer does not use it. Find the values with escapes in them and rewrite each as a triple-quoted block. On most configs there are one or two; on a config full of embedded text, that is a signal that the content wants to live in its own file rather than inside a settings file at all.

Comments are dropped, though both formats support them, so the explanations in the old file do not appear in the new one. Namespaces stop meaning anything the moment the prefixes become characters in a key. And the schema goes: XML can be validated against an XSD before an application starts, and TOML has no schema language in its specification at all.

That last one is the trade to make consciously. TOML is easier to read, easier to write by hand and unambiguous about types, and it gives up the ability to reject a malformed config mechanically. If the XML was actually being validated in your build, you are removing a check, and replacing it — with a startup-time check in the application — is part of the migration rather than an optional extra.

What the tool gives you is every value from the XML, in the right table, with the right name in the majority of cases and a quoted, obviously-wrong name in the rest. That is a good starting point and not a finished config file.

The work after it is small and non-optional: drop the root table, rename the @ and #text keys, unquote the dates, rewrite the multi-line values, and copy the comments across from the original. An hour on a large file. Skipping it produces a TOML config that works and that nobody who reads it later will believe was written on purpose.