YAML to TOML

One thing YAML has that TOML simply does not

Most of this conversion is uneventful. Mappings become tables, sequences of mappings become array-of-tables, and the scalar types line up almost exactly. You can move a service config from a YAML world to a Rust or Python one and expect the result to say the same thing.

Except for null. YAML has it, spells it four different ways — null, ~, Null, and an empty value after a colon — and TOML has no null at all. There is no syntax for it, and that is deliberate: the position of the TOML authors is that a key with no value is the same as a key that is not there. Which is fine as a design opinion and awkward when you are holding a file full of them.

That leaves a converter with two options, and most take the quiet one — drop the key and say nothing, so a password: line with no value simply vanishes and you find out when something fails to start. This page drops them too, because there is no alternative, but it names every one of them under the output. A conversion that changes the shape of your document should say which keys it changed.

The other things worth knowing are smaller. Anchors and aliases are expanded, so a block referenced in three places is written out three times — TOML has no way to share a value. A YAML file whose root is a list or a bare scalar cannot be converted at all, because a TOML document is always a table at the top. And a multi-document file, the ----separated kind Kubernetes uses constantly, has no TOML equivalent, so only the first document is converted and you are told that is what happened.

Numbers are handled the way they are everywhere on this site: an integer past 2^53 keeps every digit rather than being rounded by a JavaScript number. Nothing is uploaded — YAML config is where credentials live.

Converting a file

1. Paste or upload the YAML – A service config, a values file, a fragment. Tabs are the one thing that will fail immediately — YAML forbids tabs for indentation and the error says so with a line number.
2. Read the notices before the output – Dropped keys, a multi-document file, or comments that could not come across each get their own note. None of them stop the conversion; all of them change what you are looking at.
3. Check the keys you care about are there – Particularly if a null notice appeared. An empty value in YAML often means "set this later" or "inherit the default", and both of those become "absent" in TOML — which the consuming application may or may not treat the same way.
4. Tidy it if it is going into a repository – The output is machine-shaped. TOML Formatter will lay it out the way a hand-written file looks, and you can add the comments there.

A key with nothing after the colon is null, not an empty string. replica: and replica: "" look almost identical in a config file and convert completely differently — the first disappears and the second becomes replica = "". If a value is meant to be an empty string, quote it in the YAML before converting, or you will lose the key without noticing.

A config with a null in it

The Sample button loads a config that converts cleanly. This is the case that does not. Two keys here have no value: password is explicitly null and replica is empty, which YAML also reads as null. Both are gone from the TOML — and both are named in the notice, which is the part that matters.

database:
  host: pgsql-primary.prod
  port: 5432
  password: null
  replica:

# both of the last two are null.
# the second one just looks empty.

[database]
host = "pgsql-primary.prod"
port = 5432

# password and replica are gone.
# TOML has no null, so there is
# no way to write them at all.
# the page names both of them.

What people use it for

Moving a service config into a Rust or Python project

Cargo and modern Python packaging both read TOML, so a service whose configuration started life as YAML has to change format to move. The values carry over; it is the nulls that need a decision, and this page tells you which keys they are rather than leaving you to diff the two files.

Getting a Kubernetes manifest into a readable shape

A manifest is deeply nested YAML and TOML flattens that into explicit [a.b.c] headers, which some people find far easier to scan. Note that a manifest file usually holds several ----separated documents and TOML has no equivalent, so only the first is converted. YAML to Table is the better tool if you want to look at all of them.

Checking whether two configs agree

Convert both to the same format and compare. TOML makes structural differences obvious because every table announces its full path, so a key that moved shows up as a different header rather than as a change in indentation you have to count.

Finding the nulls in a file you inherited

An unexpected use, and a good one: the dropped-key notice is a list of every key in the document with no value. That is often exactly the list of settings somebody meant to fill in and did not.

What it handles

• Null keys are named, not silently dropped. TOML cannot represent them; you get the full path of every one.
• Integers past 2^53 stay exact. A 19-digit ICCID keeps every digit rather than being rounded.
• Anchors and aliases are expanded, because TOML has no way to reference a value defined elsewhere.
• Multi-document files are recognised. Only the first document converts, and the notice says how many there were.
• A root that is not a mapping is explained rather than producing a confusing error — a TOML document is always a table at the top.
• Nothing is uploaded. The file stays in this tab.

Questions that come up

Why did some of my keys disappear?

They had no value. TOML has no null — there is no syntax for it, by design, on the view that a key with no value and an absent key are the same thing. So a YAML key set to null, ~, or simply left empty after the colon cannot be written at all. Every one of them is listed under the output by its full path, so you can decide what the TOML should say instead: a default, an empty string, or nothing.

My file has several documents and only one converted.

TOML has no concept of multiple documents in one file. YAML separates them with ---, which Kubernetes manifests use constantly, and there is nowhere for the second one to go. The first is converted and the notice tells you how many were found. Split the file and convert each part if you need all of them.

It says the root must be a table.

A TOML document is always a set of key/value pairs at the top level. A YAML file whose root is a sequence — one that starts with - item — or a bare scalar has no legal TOML form, because there is no key to hang it on. Wrap it: put the list under a key such as items: and it converts.

What happened to my anchors?

They were expanded. A block defined once with &name and referenced with *name is written out in full at every place it was used, because TOML has no way to say "the same as that". The output means the same thing; it is longer, and editing it later means editing every copy.

Are my comments carried over?

No, and no converter can do it. The parser produces values and a comment is not one, so there is nothing to carry. The count is reported so the loss is at least visible. If your actual goal was a tidier YAML file rather than TOML, be aware the YAML formatter has the same limitation for the same reason — whereas the TOML formatter does keep comments, because it rewrites text rather than parsing.

Do long ID numbers survive?

Yes. js-yaml resolves an integer straight to a JavaScript number, which is exact only to about 15 digits, so 8901240544102066246 would normally come back as 8901240544102066000. The digits are carried across as text here and written back as a bare TOML integer, which is well within TOML's 64-bit range.

Related tools

Worth reading

• YAML 1.2.2 — the specification – Anchors, aliases, multi-document streams and the indentation rules
• The TOML issue where null was decided against – Years of argument, and the reasoning behind a format having no null at all