When you need TOML as YAML
Most TOML-to-YAML conversions happen at the boundary between ecosystems: settings authored for a Rust or Python service need to be injected into a Helm chart, a Kubernetes ConfigMap or an Ansible inventory, all of which speak YAML. Others are documentation jobs, where a team that standardised on YAML wants one consistent config style.
Both formats describe the same kind of data — nested key/value tables, lists, strings, numbers and booleans — so the conversion keeps all values intact. Only dates and comments need attention, as described below.
How tables and arrays are laid out
- The root table becomes a top-level mapping.
- Each
[table]becomes a nested mapping, and[a.b.c]headers become three levels of indentation. [[array]]blocks become a list whose items are mappings; nested[[fruits.varieties]]arrays appear inside the item they belong to.- Arrays of values become block lists with one
-item per line. - Multi-line TOML strings become YAML literal blocks (
|), keeping each line.
Key order follows the TOML document. Output uses two-space indentation and never folds long lines.
Safe quoting for YAML readers
YAML guesses types from unquoted text, and parsers disagree: PyYAML and Ansible use YAML 1.1, where yes, no, on and off are booleans. A TOML string country = "NO" would come out as false if written naively.
The converter therefore quotes every string that a YAML 1.1 or 1.2 reader could read as a boolean, number, null or date — "yes", "0755", "1.10", "null" — while leaving ordinary text unquoted. Keys get the same protection, which is why a key named n or y appears in quotes. See the Norway problem explainer for background.
Dates and special floats
TOML has native date-times; the YAML produced here writes them as quoted ISO 8601 strings, for example dt: "1979-05-27T07:32:00.000Z". That avoids YAML timestamp handling that differs between libraries, but it means a consumer sees text, not a date object. Fractional seconds are kept to milliseconds.
TOML’s inf and nan translate directly to YAML’s .inf and .nan, so these values survive here even though JSON could not hold them.
Comments and options
Comments in the TOML are discarded: the document is parsed into data and printed fresh, and comments are not part of the data. Add them back in YAML with the same # syntax.
There are no options. The parser is strict TOML 1.0, so duplicate keys or tables defined twice stop the conversion with a line number instead of producing ambiguous YAML. Your configuration is processed only in this tab.
Examples
Server and database settings
Two TOML tables become two nested mappings; the IP address string is left unquoted because no YAML reader would mistype it.
[server]
host = "0.0.0.0"
port = 8080
[database]
url = "postgres://localhost/shop"
pool = 10
server:
host: 0.0.0.0
port: 8080
database:
url: postgres://localhost/shop
pool: 10
Nested arrays of tables
The varieties arrays are attached to the apple entry, producing a list of mappings that contains another list.
[[fruits]]
name = "apple"
[[fruits.varieties]]
name = "red delicious"
[[fruits.varieties]]
name = "granny smith"
[[fruits]]
name = "banana"
fruits:
- name: apple
varieties:
- name: red delicious
- name: granny smith
- name: banana
Values that need quotes in YAML
Each string that YAML 1.1 would turn into a boolean or number is quoted, and the TOML date-time becomes a quoted ISO string.
country = "NO"
mode = "0755"
enabled = "on"
version = "1.10"
created = 2024-03-11T09:30:00Z
country: "NO"
mode: "0755"
enabled: "on"
version: "1.10"
created: "2024-03-11T09:30:00.000Z"
Common errors and how to fix them
| Error | Cause | Fix |
|---|---|---|
Invalid value | A TOML value is missing its quotes, such as name = app. | Quote the string: name = “app”. |
Trying to redefine an already defined table or valueExplained | The TOML defines the same key or [table] header twice. | Combine the duplicate definitions into one. |
Expected comma or end of structure | An inline array or table is missing a comma or its closing bracket. | Check the brackets on the reported line, for example a = [1, 2] rather than a = [1, 2. |
Frequently asked questions
Why are some values quoted in the YAML?
They are strings that a YAML parser could otherwise read as booleans, numbers or nulls. Quoting keeps them as text for every YAML version.
Do TOML dates become YAML timestamps?
No, they become quoted ISO 8601 strings, which every YAML library reads the same way. Remove the quotes if you specifically want a YAML timestamp.
Are comments kept?
No. Comments are dropped during parsing; re-add the ones you need using # in the YAML.
Is the output valid for Kubernetes and Ansible?
Yes, it is plain block-style YAML. Ansible in particular benefits from the extra quoting because it reads YAML 1.1.