About YAML to TOML
YAML and TOML are both configuration formats written for humans, but they pull in different directions. YAML expresses hierarchy through indentation and supports anchor reuse plus multi-document files, which is more expressive and easier to get wrong. TOML uses explicit section headers and key-value pairs with visible structural boundaries, making it easier for people and tools alike to tell which section a line belongs to, which is why newer toolchains favour it. Conversion parses the source into a tree and re-emits it under the target's rules. The thing to watch is not syntax but typing. YAML has a set of implicit rules where unquoted numbers, booleans and even dates are recognized automatically; TOML has its own type conventions, with date and time as first-class types. Round-tripping the same configuration can change types when the source omits quotes. Practical notes: Before converting, quote every field that looks numeric or boolean but is really an identifier, such as version strings, identifiers with leading zeros, and enumerations whose values happen to be yes or no. After converting, compare field count and nesting depth to confirm nothing was lost or shifted, because a YAML sequence becomes a double-bracket array in TOML and that is where automatic conversion most often slips. Limits: Comments are lost in both directions, so explanatory text belongs in a field value or a separate document. YAML anchors and aliases expand into duplicated content in TOML, inflating the file without changing meaning, and multi-document YAML must be split into several files since TOML has no equivalent top-level structure. Empty and default values also differ, with some parsers distinguishing an empty string from "unset", so write the intended value explicitly instead of relying on defaults when migrating. Data and privacy: the configuration being converted usually holds database connection strings, third-party secrets and internal hostnames, material least suited to leaving the machine. This tool parses and serializes in the browser, uploads nothing and needs no network. Afterwards, check the output for plaintext secrets that should have been replaced by environment variables. Two lessons from practice. First, if one configuration must live in both formats long term, designate a single source of truth and generate the other by script, marked do not edit by hand, or independent edits on both sides produce drift that is hard to detect. Second, put the conversion into a pre-commit check: commit both the source and the generated result, regenerate in the pipeline and compare, and any mismatch means someone edited the generated file, which is far cheaper than field-by-field review afterwards. Configuration problems tend to surface only in production, so automating this kind of mechanical verification pays off far more than adding a few comments. Start by running a structurally simple configuration through the whole flow to confirm indentation, arrays and dates behave as expected before touching production config. One habit is worth keeping: store the conversion script and the source configuration in the same repository and commit them together. Then history shows whether source and artifact stayed in sync. During an incident you can also tell quickly whether the configuration was wrong or the conversion introduced the deviation, which beats diagnosing from memory.
How It Works Internally
Conversion parses the source into a tree and emits it under the target format rules. The difference lands in how structure is expressed: YAML implies hierarchy through indentation while TOML declares paths with headers. A scalar array therefore uses single brackets and an array of objects uses double brackets, and getting that wrong yields a file that will not parse, so read the result back with a parser to confirm.
tags:
- a
- b
items:
- {id: 1}tags = ["a", "b"]
[[items]]
id = 1Measured on This Page
| Fixed: dates became table headers | date: 2026-01-01 was parsed to a Date, and the old writer treated a Date as a plain object, emitting a [date] header with no key and no value. Date is now handled before the object branch, and unquoted dates are quoted before parsing, yielding date = "2026-01-01" |
|---|---|
| Fixed: integers lost a digit | 9007199254740993 became …992 through Number. Integers of 16+ digits are quoted before parsing, so the output is id = "9007199254740993" |
| Fixed: dotted keys read as paths | "a.b": 1 used to be emitted as a.b = 1 — in TOML that means key b inside table a, a different structure entirely. Keys now render through tomlKey, producing "a.b" = 1 |
| Fixed: null written as empty string | TOML has no null and the old code emitted "", silently turning 'missing' into 'empty string'. The key is now skipped and the status bar reports how many were omitted |
| Everything else | Nested objects become [a] sections, scalar arrays become list = ["x", "y"], booleans stay true, and multi-line strings collapse to a single double-quoted line |
YAML and TOML each carry their own implicit typing, so a converter's job is to preserve meaning. The 3 measured failures all broke that rule: a date emitted as a table header, an oversized integer losing its last digit, and a dotted key reinterpreted as a nested path. The fourth is a capability gap rather than a bug: TOML has no null, so the key can only be omitted with a notice — if downstream logic depends on 'present but empty', substitute an empty string yourself. The reverse direction is gentler, because YAML can express both null and dates.
How to Use
- Open "YAML to TOML"
- Paste the whole YAML config into the left pane
- TOML is generated as you type
- Watch for the skipped-value notice
- Click the copy icon to export the TOML
Use Cases
- Organize tool config — Consolidate scattered YAML settings into a single TOML file for a Rust/Python project.
- Standardize format — Convert legacy YAML uniformly once a team mandates TOML.
- Learn syntax — Compare YAML and TOML to understand TOML-specific structures like arrays of tables.
- Simplify config — Reorganize overly deep YAML into TOML's flatter table structure.
- Generate examples — Provide both YAML and TOML versions in docs for reference.
- Migrate CI variables — Convert GitHub Actions workflow YAML inputs into TOML to centralize config in a pyproject.toml file.
- Docker Compose to TOML — Translate docker-compose YAML service definitions into TOML for tools that read TOML-based orchestration configs.
FAQ
What happens to YAML null?
TOML has no null. Keys with null values are skipped during conversion — note these fields disappear from the result.
Are YAML anchors preserved?
No. Anchors and references are expanded into actual content before conversion, since TOML has no reference mechanism.
What do object arrays become?
They become TOML arrays of tables [[name]], with each array element as a table block.
Why are some keys quoted?
When key names contain dots, spaces, or special characters, TOML requires quoting — handled automatically.
How are YAML multi-line strings handled?
Long text becomes TOML triple-quoted multi-line strings preserving line breaks; fold lines with a trailing backslash when you want softer wrapping.
Want JSON as an intermediate?
Use YAML to JSON then JSON to TOML — two steps give more control.
Deep nesting becomes many [a.b.c] sections — why?
TOML expresses nesting with dotted headers, so deep structures turn into multiple section headers — more verbose than YAML but semantically identical. For very deep data consider JSON; TOML is designed for configuration, not arbitrary exchange.
Did the order of objects inside arrays change?
[[array]] sections keep document order and are never sorted. If the order looks different, your viewer is sorting keys — check the raw output in a text editor instead of a sorted preview.