Does converting TOML to YAML keep comments?

No. ConfigKit rebuilds YAML from parsed values, so comments are dropped. A hash inside a quoted string is data and is kept.

Why does a TOML date become a YAML string?

YAML 1.2 has timestamps in some schemas, but ConfigKit writes the parsed TOML date as text so the calendar digits and offset stay visible after a later JSON conversion.

Can I round-trip YAML through TOML without changing types?

Not always. YAML null, mixed-type arrays, and yes/no strings have no TOML equivalent. Those documents are rejected instead of being rewritten.

TOML vs YAML: what you lose when converting

TOML and YAML can hold the same nested config, but they do not share a type system. A converter that rebuilds one document from the other has to drop comments and pick a string when a date or a null has nowhere to go.

They look close. The models are not.

Both formats are for humans who edit nested maps. TOML uses [tables], dotted keys, and [[arrays of tables]]. YAML uses indentation and - lists. After a parse, you often have a tree of strings, numbers, booleans, arrays, and objects. That overlap is why a TOML to YAML converter can produce a useful file. It is also why people expect a lossless round trip. The rest of this page is the list of things that round trip cannot keep.

Comments

TOML comments start with #. YAML comments do too. Neither JSON nor a rebuilt YAML/TOML document has a place to put those notes. ConfigKit parses, then stringifies the value. The comment tokens never make it into the output. The status line says so when the input contained a comment.

# replica count for prod
replicas = 3

The YAML is replicas: 3. If you convert that YAML back to TOML, you still do not get the comment back. Keep comments in the file you treat as source, and generate the other format in CI.

Dates and times

TOML has offset datetimes, local datetimes, local dates, and local times. JSON has none of those. YAML 1.2 core schema, which ConfigKit uses, also treats a timestamp-looking scalar as a string unless you opt into a schema that parses timestamps. The honest conversion is to write the calendar text:

shipped = 2024-05-01
started = 2024-01-15T10:30:00Z

TOML to JSON online and TOML to YAML both emit strings such as 2024-05-01 and 2024-01-15T10:30:00.000Z. A later YAML to TOML pass will not resurrect a TOML date type: the value is already a string, and it stays a string. That is the right failure mode. Silently turning a local date into midnight UTC would be worse.

Null, mixed arrays, and YAML 1.2 booleans

TOML has no null. YAML region: null cannot become TOML without inventing a sentinel. ConfigKit rejects it. TOML arrays are homogeneous in the 1.0 sense that ConfigKit still enforces when writing TOML: a list of strings and numbers is an error, not a JSON-style mixed array. YAML is fine with mixed lists.

YAML 1.1 readers treated yes, no, on, and off as booleans. YAML 1.2 core schema does not. ConfigKit keeps those words as strings, in YAML and after a conversion to JSON or TOML. true and false are the booleans. If you convert TOML enabled = true to YAML you get enabled: true. If you write enabled: yes in YAML and convert to TOML, you get a string, not a boolean.

Tables versus indentation

A TOML table is a map. Nested tables can be written as [database.replica] or as a dotted key. YAML expresses the same tree with indentation. Converting TOML to YAML folds those tables into nested mappings. Converting YAML to TOML has to pick a table spelling. You lose the original layout: key order around comments, the choice of dotted keys versus [table] headers, and inline tables versus standard tables.

[database]
host = "localhost"
port = 5432

YAML becomes a nested database: mapping. Useful. Not the same file. Arrays of tables ([[products]]) become YAML lists of maps, which is the right shape, and a YAML list of maps can become [[products]] again if every item is a table. A YAML list of scalars cannot.

Numbers the other format cannot hold

TOML allows inf and nan. JSON does not. ConfigKit rejects them instead of writing null. Integers outside ±(2^53 − 1) are also rejected, because a later JSON step would round them. YAML can write .inf; this site will not invent that from TOML, and will not accept it on the way to JSON.

What to do instead of round-tripping

Pick one source format. Convert in one direction when a tool requires the other. Check the notices: comments dropped, dates stringified, keys rejected. If you need JSON for an API, start from TOML or YAML and use YAML to JSON without uploading or the TOML to JSON page. If you need YAML for Kubernetes, convert TOML once and then edit YAML. Do not bounce the same file through both converters as an identity check. The identity is the parsed tree, not the text.

FAQ

Does converting TOML to YAML keep comments?: No. ConfigKit rebuilds YAML from parsed values, so comments are dropped. A hash inside a quoted string is data and is kept.
Why does a TOML date become a YAML string?: YAML 1.2 has timestamps in some schemas, but ConfigKit writes the parsed TOML date as text so the calendar digits and offset stay visible after a later JSON conversion.
Can I round-trip YAML through TOML without changing types?: Not always. YAML null, mixed-type arrays, and yes/no strings have no TOML equivalent. Those documents are rejected instead of being rewritten.