YAML to TOML: Migrate Docker Compose, Kubernetes, and App Configs to TOML
YAML is ubiquitous in DevOps but infamous for subtle bugs — misaligned indentation silently reparents keys, 'NO' parses as false, and anchors make files hard to read in isolation. TOML is explicit, typed, and error-resistant. This converter handles the core YAML constructs: mappings become [sections], sequences of scalars become inline arrays, and sequences of objects become [[array of tables]].
Nested YAML mappings → [section] headers. Scalar sequences → inline arrays. Object sequences → [[array_of_tables]].
YAML vs TOML: Key Differences
YAML uses indentation for structure — one wrong space changes which key a property belongs to. TOML uses explicit [section] headers. YAML's type coercion is aggressive (yes/no → boolean, NO → false). TOML only coerces when the syntax is unambiguous (true/false, unquoted integers). YAML supports anchors and references; TOML has no equivalent — each value must be stated explicitly.
Common Migration Scenarios
Docker Compose uses YAML. Cargo.toml (Rust) uses TOML. If you're wrapping a Docker Compose file in a Rust build system, you need to convert. GitHub Actions uses YAML; some CI tools like Dagger accept TOML. Application configs written in Go often accept either format — migrating from YAML to TOML removes the indentation risk.
What to Review After Conversion
Check that all required sections appear in the TOML output. Verify that sequences of objects became [[array_of_tables]] not inline arrays (this tool handles it, but edge cases exist). Verify that boolean values converted correctly (YAML 'yes'/'no' → TOML true/false). Null values become empty strings in TOML — review and remove or replace as appropriate.
Conversion Rules
- YAML mapping → TOML key = value pair
- Nested YAML mapping → [section] table
- Scalar sequence → inline TOML array
- Object sequence → [[array_of_tables]]
- YAML booleans (yes/no/on/off) → TOML true/false
- null → empty string ""
Frequently Asked Questions
Why convert YAML to TOML?
YAML and TOML are both human-readable configuration formats, but they have different strengths. YAML's whitespace-sensitive syntax can be error-prone and is notorious for gotchas (the Norway problem, indentation bugs). TOML is more explicit and has a clearer type system. Projects migrating to Rust (Cargo), Python packaging (pyproject.toml), or Hugo (config.toml) may need to convert existing YAML configs to TOML.
How are YAML mappings converted?
YAML top-level keys become TOML key-value pairs. Nested YAML mappings (key: with indented sub-keys) become TOML [table] sections. For example, database: with host and port sub-keys becomes a [database] section with host and port keys. Keys at the same level as the section stay at the top level.
How are YAML sequences handled?
YAML sequences of scalar values ([a, b, c] or - item lists) become TOML inline arrays: key = [a, b, c]. YAML sequences of mappings (list of objects) become TOML [[array of tables]]: each object gets its own [[key]] header.
What YAML features are not supported?
Anchors and aliases (&anchor / *alias), merge keys (<<), custom tags (!type), multi-document streams (---), and complex nested array-of-maps structures are not supported. TOML also has no concept of YAML's null value — nulls become empty quoted strings.