Convert YAML to TOML

Plain values and arrays are written at the top, then each nested mapping appears as its own bracketed table header. Nesting three levels deep produces a single header with dots in it rather than three nested blocks, so a mapping written as tool, then ruff, then a setting, comes out as one [tool.ruff] header with the setting under it.

That flattening of headers is the visible difference between the two formats. YAML expresses depth with whitespace and can nest without limit before it becomes unreadable; TOML expresses depth in the header name and stays readable at four levels because the full path is written out on every block. It is the trade the format was designed around, and for a project config it is usually the right one.

A line written key: with nothing after it is valid YAML and parses to null. TOML has no null value — the specification simply does not define one — so the writer omits the key. No error, no placeholder, no comment: the key was in your YAML and is not in your TOML.

This matters more than it sounds because empty keys are a deliberate YAML idiom. They mark a setting as present but unset, they hold a place for something an operator fills in later, and they document that an option exists. All of that is information, and all of it disappears. Search the source for lines ending in a colon before converting, and decide for each one whether it should carry an explicit value, an empty string, or a comment in the TOML.

The same null inside an array behaves differently: the writer refuses, and the conversion fails with a message saying arrays cannot contain null or undefined values. Nothing is produced.

This is the better of the two behaviours, and the inconsistency is deliberate rather than accidental. Dropping a key from a table leaves the rest of the table meaningful; dropping an element from an array shifts every element after it, which changes an ordered list into a different ordered list. Refusing is the only safe answer, and it means a YAML file with a stray dash and nothing after it tells you so rather than converting into something subtly wrong.

TOML groups by table. Everything belonging to a table has to appear after its header and before the next one, so the writer emits every scalar and array first and then each nested block in turn. A .gitlab-ci.yml converted this way puts its stages array at the top and the job definitions below it as tables, regardless of how they were ordered in the YAML.

The consequence to plan for is the diff. If the YAML file is under review and the TOML replaces it in the same repository, the first commit will look like a rewrite rather than a translation, because it is. Land the conversion as its own commit with nothing else in it, so the next reader can see that only the syntax changed.

A block scalar — the pipe character followed by an indented shell script, which is how every CI file holds its build commands — parses into a string containing newlines, and the writer emits it as an ordinary quoted TOML string with backslash-n escapes in it. A ten-line script becomes one very long line.

TOML has a multi-line string syntax using triple quotes that would hold the script legibly, and the writer does not reach for it. That is a conversion you make by hand: find the values with escaped newlines in them, and rewrite each as a triple-quoted block. It is worth doing for anything a human will edit again, and not worth doing for a value nothing but a program reads.

TOML is the only format in this family with first-class dates: offset datetimes, local datetimes, local dates and local times are all part of the specification and a TOML parser hands them back as dates rather than strings. That is the main reason a project chooses TOML over JSON.

You do not get them from this conversion. YAML 1.2 treats an unquoted 2024-01-02 as a string, so it arrives in the TOML as "2024-01-02" with quotes around it. Unquoting those values afterwards is the whole job and takes seconds; leaving them quoted works too and simply means your TOML holds text where it could hold a date. The same is true of integers written with a decimal point: a YAML value of 1.0 becomes the TOML integer 1, because the parser resolved it to a whole number before the writer saw it.

The construct people worry about turns out to be the one that works best. A YAML list whose items are mappings — a list of authors, a list of binaries, a list of jobs — becomes a TOML array of tables, with the double-bracket header repeated once per item. That is exactly the shape a pyproject.toml or Cargo.toml wants for its authors and its targets.

A list at the very top of the YAML file is the exception. TOML documents are always a table, so a document that is nothing but a list is wrapped in a table with a single key named items and the list underneath it. If your YAML is a sequence at the root, decide on the key name yourself and add it to the source before converting, so the name means something.

TOML bare keys allow letters, digits, underscores and hyphens. Anything else has to be quoted, and the writer quotes it for you: a key containing a dot comes out as "date.timezone" with the quotes included, and so does a key containing a space. Quoted keys are entirely valid TOML.

They are also a signal. A quoted key with a dot in it usually means the YAML was expressing structure in the key name rather than in the nesting, and in TOML that structure would be better written as a real table. Whether to split it is a decision about your config, not about the conversion, but the quotes in the output are a reliable place to start looking.

Both formats support comments and none of yours cross over. The parser discards them while reading and the writer has nothing to write. On a project config that is a real cost — the note explaining why a dependency is pinned, the commented-out alternative, the line saying which environment a block applies to.

The migration is only finished when those are back. Convert, then open the old YAML and the new TOML side by side and reattach the comments where they belong. It is ten minutes on a typical file and it is the difference between a config somebody can maintain and a config that works and nobody dares change.