YAML ↔ TOML Converter

1. Where YAML and TOML Decide to Diverge

Both YAML and TOML exist to make configuration authorable for humans. YAML leans on significant indentation like Python: nested keys are indented two spaces and quoted only when ambiguous. TOML leans on section headers in square brackets: each nested level opens a new table header and indentation is purely decorative. Both formats support comments, multi-line strings, native date types, and arrays of tables.

They diverge in a few specific places you should know before converting: YAML supports multiple documents in one file (separated by ---), multi-document anchors and aliases for referencing, and a much looser type system than TOML. TOML has stricter integer and date types, does not allow multiple documents, and forbids mixed-type arrays. Conversions between them are usually simple human-readable key-value hierarchies, which is what most configuration actually is.

2. The Header-Indentation Translation

When converting from YAML to TOML, each nested map becomes a TOML table by adding a header in square brackets with the dotted path of the nesting. The YAML block server:\n port: 8080\n host: local becomes the TOML block [server]\nport = 8080\nhost = local. Arrays of maps become arrays-of-tables with double-square-bracket headers, and the indentation in the original YAML collapses into the dotted header notation in TOML.

The reverse direction is the inverse: TOML's headers collapse into YAML's nested maps. The conversion is structurally lossless for any non-anchor YAML config because TOML can express everything YAML can express at the config-file level.

3. Anchors, Aliases, and Multiple Documents

YAML anchors and aliases (the &anchor and *alias syntax for inline deduplication) have no direct counterpart in TOML. The converter expands every alias into a full copy of the anchored subtree at conversion time, so the output TOML is larger but semantically identical, and round-trips back to a YAML without anchors. Similarly, multi-document YAML files convert to a single TOML document with an index-prefixed root table (document_0, document_1, ...) so no data is lost.

4. The Type Coercions That Round-Trip Cleanly

• Strings: round-trip except where YAML implicitly types unquoted values (yes becomes a boolean, 1.5 becomes a float). Use the strict-mode option to keep every unquoted YAML scalar as a string.
• Dates: ISO-8601 dates in YAML become native TOML datetimes; the reverse restores them as ISO-8601 strings.
• Numbers: YAML accepts arbitrarily large integers; TOML caps at 64-bit signed, so mammoth integers coerce to strings.