Why this exists
Two formats, one argument about editing
TOML is not a competing spelling of the same idea as YAML. It is a reply to a specific complaint about YAML, and the reply is written into the format's own charter. The TOML v1.0.0 specification opens with three sentences, and every clause of this comparison is a consequence of them: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages. Easy to read. Unambiguous. Maps to a hash table. Parseable without a build tool chain. Those are not aesthetic preferences; they are answers to the failure modes described in the YAML guide.
The complaint is documented by the people who adopted TOML rather than by its author alone. PEP 518, which chose the format for Python's pyproject.toml, says the decision out loud: This format was chosen as it is human-usable (unlike JSON), it is flexible enough (unlike configparser), stems from a standard (also unlike configparser), and it is not overly complex (unlike YAML). The same page records that the format was already in use by the Rust community as part of their Cargo package manager and that that community had said it was happy with the choice. "Not overly complex" is a pointed phrase to use about a language whose 1.2.2 specification runs to hundreds of productions, and it is the entire reason two formats exist for the same job.
YAML's own defence is on the record too, and it is honest. The introduction to the YAML 1.2.2 specification states that the 1.2 revision was published in 2009, that its primary focus was making YAML a strict superset of JSON, and that it also removed many of the problematic implicit typing recommendations. In other words, the committee conceded the criticism and fixed it — but only in 2009, and only in a revision that plenty of shipping parsers do not implement. TOML started from the opposite end: instead of removing the ambiguous types from a big language, it built a small language with nothing ambiguous in it.
# deploy.yaml
service:
name: billing
port: 8080
replicas: 3
features:
- retries
- vault
limits:
cpu: "500m"
memory: 128Mi
owner:
team: payments
oncall: ["ana", "tofig"]Four levels of nesting expressed as four indentation steps. Nothing here names the structure; the columns do.
# deploy.toml
[service]
name = "billing"
port = 8080
replicas = 3
features = ["retries", "vault"]
[service.limits]
cpu = "500m"
memory = "128Mi"
[owner]
team = "payments"
oncall = ["ana", "tofig"]Nine lines of header and bracket in exchange for the elimination of one whole class of bug: nothing in this file means anything because of where it starts on a line.
Read the pair again with the question "what happens when a tool edits this?" and the difference stops being cosmetic. The TOML file can have port rewritten by a script that changes one line; every other byte, including the comment, stays where it is. The YAML file can be edited by a script that rebuilds the whole document from the parsed tree, which is a different operation: it loses the comment, may reorder keys, and re-chooses every scalar style. Both formats are text. Only one of them is text whose meaning is local to the line you are changing.
| Question | YAML 1.2.2 | TOML 1.0.0 / 1.1.0 |
|---|---|---|
| Declared purpose | A human-oriented data serialization language, and a strict superset of JSON | A minimal configuration file format, easy to read due to obvious semantics |
| Target model | A representation graph of nodes with tags, which may contain shared nodes | Maps unambiguously to a hash table |
| Type system | Open: tags and a schema decide; three recommended schemas, and implementations may add more | Closed: ten value types, and "unspecified values are invalid" |
| Structure | Indentation and block context | Explicit headers, dotted keys and one key per line |
| Reuse | Anchors, aliases and a 1.1 merge type | None |
| Documents | A stream of zero or more documents per file | Exactly one document per file |
| Versioning posture | 1.2 is a superset aimed at 1.1 compatibility; 1.1 semantics still ship | 1.0.0 froze the language; 1.1.0 added only clarifications and two relaxations |
The last row matters for anyone deciding in 2026: TOML v1.1.0 was published on 18 December 2025 and keeps the same objectives paragraph and the same byline, Tom Preston-Werner, Pradyun Gedam, et al.
The data model
A closed type set against an open resolver
TOML enumerates its value types and stops. The specification lists String, Integer, Float, Boolean, Offset Date-Time, Local Date-Time, Local Date, Local Time, Array and Inline Table, then adds the sentence that decides the whole comparison with JSON and YAML: Unspecified values are invalid. with key = # INVALID as the example. There is no eleventh type. There is no null.
YAML works the other way round. Its data model is three node kinds — scalar, sequence, mapping — and an unbounded set of tags; the core schema recommended by 1.2 resolves plain scalars to !!null, !!bool, !!int and !!float, and any implementation may define more. So YAML has five ways to write nothing — null, Null, NULL, ~, and an empty value — plus the empty string, which is emphatically not nothing. JSON has exactly one null. TOML has none, and that is the single biggest conversion problem between these formats, not the brackets.
# YAML: four distinct states, all legal
explicit_null: null
tilde: ~
empty_value:
empty_string: ""Resolved with a 1.2 core parser, the first three are null and the fourth is the empty string. Converted to JSON, three of them become null and one becomes an empty string.
explicit_null = "null" # the only way to write the word
empty_string = ""
# no way to write null: omit the key instead
# missing_keys_are_the_only_null = # INVALIDIn TOML the absence of a key is the whole story. A loader that needs three states — set, empty, absent — must invent a convention, and every tool that reads the file has to agree on it.
The practical shape of this is a schema question, not a syntax question. If your configuration model has a nullable field — tls_ca: meaning "verify with the system bundle" versus tls_ca: "" meaning "do not verify" versus the key absent meaning "TLS off" — TOML can store two of the three states per key and YAML can store all of them, but only if your reader distinguishes an empty value from an empty string, which plenty of readers do not.
What each format can say at all
| Concept | YAML 1.2 | TOML 1.1.0 | Consequence when converting |
|---|---|---|---|
| null | five spellings plus empty | not representable | YAML to TOML: every null becomes an omitted key, a string, or a silent failure |
| boolean | true/false in 1.2 core; 24 spellings in 1.1 | exactly true and false | TOML to YAML: safe; YAML to TOML: quote the 1.1 spellings first |
| integer | decimal, 0x, 0o, 1_000 in 1.1, sign allowed | decimal, 0x, 0o, 0b, underscores, no leading zeros | Both handle it; the spellings differ |
| float | 0., .5, 1e3, .inf, .nan | requires a dot or exponent; inf, +inf, -inf, nan, +nan, -nan | NaN equality stays broken in both |
| date and time | no timestamp type in the 1.2 schemas; a 1.1 type otherwise | four first-class temporal types | TOML dates leave as strings or as objects depending on the reader |
| ordered sequence | first-class, of any node type | first-class, may mix types | Fine in both directions |
| mapping with non-string keys | legal, including sequence and complex keys | keys are always strings | YAML to TOML needs key stringification; JSON cannot do it either |
| shared nodes (anchors) | first-class; the model is a graph | absent | Any YAML alias must be expanded before conversion |
| multiple documents | one stream, many documents | one document per file | A Kubernetes manifest has no TOML equivalent |
| comments | yes, not part of the data model | yes, explicitly not part of the data | Lost by every JSON-mediated round trip |
| application types via tags | yes, by design | no mechanism exists | The security section is about exactly this line |
Nine of these rows are symmetric. Two of them — null and tags — explain most of the complaints you will read about moving configuration between the formats.
- hash table
- The structure TOML promises to map to unambiguously: string keys, typed values, nested tables.
- closed type set
- A grammar in which every value must match one of a fixed list of shapes; anything else is a syntax error rather than a guess.
- tag resolution
- YAML 1.2 mechanism that matches a plain scalar against a schema table to pick a type; no TOML equivalent.
- local date-time
- A TOML temporal value with no offset, e.g. 1979-05-27T07:32:00; maps to a datetime with no tzinfo in Python.
- offset date-time
- A TOML instant with an explicit offset or Z, e.g. 1979-05-27T07:32:00Z.
- inline table
- TOML single-expression map, features = { retries = 3, vault = true }; in 1.1.0 it may be spread over several lines.
Syntax
Explicit brackets against counted columns
YAML's structural claim is that a human can write a tree quickly. Its mechanism is indentation: a mapping's members are the lines indented under its key, a sequence's members are the dashes at one column, and the parser works out parentage from character positions. The 1.2 specification is emphatic that the amount of indentation is a presentation detail that must not be used to convey content — but only in the sense that two spaces and four spaces must not mean different things. Relative indentation is load-bearing and absolute indentation is not, which is a fine distinction for a human and a terrible one for a text editor that expands tabs differently.
TOML removes the axis. Whitespace is ignored around key names and values, the key, the equals sign and the value must be on the same line — with the exception of values that are themselves multi-line — and there must be a newline or end of file after each key/value pair. The spec even gives the two-line failure as an example: first = "Tom" last = "Preston-Werner" # INVALID. Nesting comes from three constructs and one convention:
| Construct | Example | Produces | Notes |
|---|---|---|---|
| Table header | [service.limits] | a map at service.limits | Every following key belongs to it until the next header; order of definition is free |
| Dotted key | service.limits.cpu = "500m" | the same map, created implicitly | Dotted keys define their parent tables; a bare key may contain dots only as a separator |
| Inline table | limits = { cpu = "500m", memory = "128Mi" } | a map, as one value | Self-contained in 1.0.0; v1.1.0 allows its pairs on different lines |
| Array of tables | [[service.env]] | one appended element of an array of maps | Repeated headers append; the only way to spread a list of objects over several readable lines |
The last row is the construct people fight. A YAML sequence of five mappings becomes five [[header]] blocks, and inserting one in the middle means moving a header, not a line.
# k8s-style: five items, easy to reorder
ports:
- name: http
containerPort: 8080
protocol: TCP
- name: metrics
containerPort: 9090
protocol: TCPEach item is four lines and the block for item two can be cut and pasted anywhere in the sequence.
[[ports]]
name = "http"
containerPort = 8080
protocol = "TCP"
[[ports]]
name = "metrics"
containerPort = 9090
protocol = "TCP"Six lines plus two headers. Moving the second item above the first means moving a header line with it, and forgetting that is how people end up with two [[ports]] blocks and one name key stranded in the wrong table.
TOML can express the same list more compactly as an array of inline tables, which is what most generated files do: ports = [{ name = "http", containerPort = 8080 }, { name = "metrics", containerPort = 9090 }]. That is one line, and it is worse for diffs, which is why Cargo and the Python tools write arrays of scalars inline and arrays of objects as repeated [[table]] headers. YAML has the same tension between flow style and block style, but the block form is the default and the readable one, and its flow form is byte-identical to JSON.
Depth, and what it costs
A nested path in YAML costs one indentation step. The same path in TOML costs either a longer header — [a.b.c.d] — or a longer dotted key — a.b.c.d = 1 — and, crucially, both of those must be consistent with everything else in the file, because a table can be defined only once. Deep structures therefore push TOML toward inline tables and YAML toward indentation, and the two formats hide their pain in different places: YAML hides it in columns that must stay aligned, TOML in headers that must not collide.
The real question
Who is allowed to edit your file without destroying it
Most configuration files are written by a human once and then edited forever by programs: a dependency added by a command, a version bumped by a release bot, a field set by a scaffold generator. The question that decides these two formats is not which reads better but which survives that edit.
TOML is built to be rewritten in place. Because structure is carried by headers and each value lives on its own line, a tool can perform surgical text edits and remain correct without ever modelling the document. That is not hypothetical: the Cargo book documents Cargo's own configuration as TOML — Configuration files are written in the TOML format (like the manifest), with simple key-value pairs inside of sections (tables) — the cargo add command is described in the command reference in the same documentation as "Add dependencies to a Cargo.toml manifest file", and the credentials file is documented as automatically created and updated by cargo login and cargo logout, in a $CARGO_HOME/credentials.toml that Cargo has written by default since version 1.68. Cargo also defines the escape hatch that machine editors need: any key of the form foo.bar can be set by the environment variable CARGO_FOO_BAR, and Environment variables will take precedence over TOML configuration files. A tool that cannot safely edit the file has a documented way to not touch it.
Python tells the same story from the other direction. PEP 518 put pyproject.toml under the same logic — a file tools must read reliably, hence a format that is not overly complex — and the point of the file is that it is read by programs that did not write it. Note what those edits are: an [project] table key, a [build-system] requirement string, a setting inside the [tool.flit] table that PEP 518 itself uses as its example. They are single-line changes in a file whose meaning does not depend on alignment, and a comment written by a human three sections above is untouched by all of them. Notably, PEP 621 lists "Require build back-ends to update pyproject.toml when generating an sdist" among its rejected ideas — the concern being tool edits to a human-owned file, not the format's ability to survive them.
Why YAML round-tripping is a library, not a feature
A YAML editor cannot work on lines. Move one line and you have moved a subtree; delete a line of indentation and you have changed a parent. So any tool that edits YAML responsibly parses, mutates the tree, and re-serialises, and re-serialising a language that has scalar styles, block headers, anchors, comments, key order and folding choices means deciding what to do about all of them. The specification makes that harder on purpose: anchors are discarded once the representation graph is composed, so whether your merge keys and aliases survive an edit is a property of the library, not of the format. That is why YAML round-tripping is a feature you install — libraries that advertise comment, key-order and style preservation — while TOML round-tripping is a feature the grammar gives you.
The asymmetry shows up in what is in the standard library. Python's tomllib parses TOML 1.0.0 from 3.11 and TOML 1.1.0 from 3.15, and its documentation states flatly that This module does not support writing TOML. Read that correctly: the language shipped a reader and declined to ship a writer, because writing TOML responsibly — preserving what the human typed — is a project of its own, which is why separate libraries exist for it. YAML has no reader in any standard library either, but it has an entire sub-industry of round-trip tooling precisely because the naive path destroys so much.
$ cargo add serde_json
Adding serde_json v1.0.145 to dependencies.Cargo appends one line inside the [dependencies] table. The diff is one added line; every comment, blank line and ordering the author chose is untouched. The equivalent operation in YAML, done by a re-serialising tool, typically diffs the whole file because the writer re-picked every style.
| Artifact in the file | TOML with a line-editing tool | YAML with a load-and-dump tool | YAML with a round-trip tool |
|---|---|---|---|
| Comments | Untouched — the tool does not read them | Lost, unless the library models them | Preserved, as non-data nodes |
| Key order | Untouched | Preserved by most loaders, not guaranteed | Preserved deliberately |
| Blank lines and grouping | Untouched | Lost | Partly preserved |
| Scalar style (quotes, block) | Untouched | Re-chosen by the emitter | Preserved if the library tracks style |
| Anchors and aliases | Not applicable — they do not exist | Expanded or dropped depending on the library | Preserved, with anchor names |
| Quirks a human typed by hand | Still there | Normalised away | Still there |
| A stray indentation change | Harmless | Changes the data | Changes the data |
The last row is the point of the whole section: TOML is not easier to edit because it is simpler to look at, it is easier to edit because an error in it costs you a parse failure rather than a different document.
Where YAML eats data
The coercions TOML cannot perform
This is the section that decides arguments, so it is worth being exact about what YAML does and to which version. A plain — that is, unquoted — YAML scalar is matched against the resolver table of the schema in force. The YAML 1.1 boolean type matches y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF. The YAML 1.1 integer type matches decimal, hexadecimal with 0x, binary with 0b, a leading-zero octal form, a base-60 form using colons, and decimals with underscore separators. The float type adds the fixed-point form that rewrites 1.10 as 1.1, exponent forms, sexagesimal floats and .inf and .nan. A timestamp type matches ISO-like dates and turns 2024-01-15 into a date object.
Now look at what TOML does with the same six values. It does not do anything, because none of them are valid TOML except the date and the two-part version. TOML has no implicit-string-to-boolean path: the only boolean spellings are true and false, so enabled = NO is a syntax error. Its integers forbid leading zeros — the specification's own sentence is Leading zeros are not allowed. — so mode = 0755 fails to parse rather than becoming 493. There is no base-60 form, so start = 1:15 fails rather than becoming 75. Bare words on the right of an equals sign are not strings either; there is no type for them to take, so they fail. The defence is not a better resolver. The defence is that the grammar refuses the whole file.
country: NO # 1.1 boolean false / 1.2 string
release: 1.10 # float 1.1 in both versions
file_mode: 0755 # 1.1 octal 493 / not a 1.2 integer form
start: 1:15 # 1.1 sexagesimal 75 / 1.2 string
cutoff: 2024-01-15 # 1.1 timestamp object / 1.2 string
flag: on # 1.1 boolean true / 1.2 stringThis file parses without complaint in every YAML library you have. Ask what it means after resolution and you get two different answers.
country -> bool false
release -> float 1.1
file_mode -> int 493
start -> int 75
cutoff -> date 2024-01-15
flag -> bool trueTwo booleans, one float with a digit missing, one integer that was meant to be a permission mask, one integer that was meant to be a clock time, and one object where the schema expects text. Nothing was reported at parse time.
country -> str "NO"
release -> float 1.1
file_mode -> str "0755" (or rejected: not a valid core integer)
start -> str "1:15"
cutoff -> str "2024-01-15"
flag -> str "on"Five of six values change type between the two resolvers. Only release is the same in both — a float, still missing its trailing zero.
| Intent | YAML 1.1 | YAML 1.2 core | TOML | What TOML forces you to do instead |
|---|---|---|---|---|
| Country code NO | boolean false | string | parse error | country = "NO" — the quotes are the only legal spelling |
| Version 1.10 | float 1.1 | float 1.1 | float 1.1 | version = "1.10"; TOML still types a bare dotted number |
| Mode 0755 | int 493 | string or error | parse error | mode = "0755", or mode = 0o755 if you want the number |
| Time 1:15 | int 75 | string | parse error | start = "1:15"; a colon is not a number in any TOML type |
| Date 2024-01-15 | timestamp object | string | Local Date | Either accept a date type or quote it — TOML decides visibly |
| Flag on | boolean true | string | parse error | flag = true, or flag = "on" if it is a label |
Five of the six rows are the same in TOML: it refuses. The exception is the version string, and it is worth knowing, because a float is what a bare 1.10 is in every format with numeric types. Quote versions everywhere.
The honest counterweight: TOML's date-time types mean it also decides behind your back. updated = 2024-01-15 is a Local Date, delivered to your loader as a date object — Python's tomllib maps Local Date-Time to a datetime.datetime with tzinfo set to None, Local Date to datetime.date and Local Time to datetime.time. If the consumer then serialises that onward to JSON, it either succeeds with a formatter or fails with a "not JSON serializable" error, which is a loud, immediate, debuggable failure. YAML's equivalent produces a string in one library and a date in another and lets you ship the disagreement. That is the difference in one line: both formats type your data; only one of them is consistent about it.
And its own share of pain
Where TOML files fail to parse
A format that refuses is a format that fails. If you are moving from YAML, most of your new errors will be TOML's, and they are worth learning before you meet them in a build log.
Keys
Bare keys may contain only ASCII letters, digits, underscores and dashes, and — this surprises everyone once — a key made only of digits is legal and is always a string: 1234 = "value" defines the key 1234, not the integer 1234, because TOML has no non-string keys at all. Anything wider needs quotes, and quoted keys follow the same rules as basic or literal strings: "127.0.0.1" = "value" and "character encoding" = "value" are both legal, and the specification's advice is to use bare keys except when absolutely necessary. A bare key must be non-empty; an empty quoted key is allowed and discouraged; and you cannot use a multi-line string as a key. So the dotted key a.b.c = 1 is three keys joined by dots, and if you want a literal key containing a dot you must quote the whole thing: "a.b.c" = 1 is one key, not three.
Tables and the double-definition error
The rule is Like keys, you cannot define a table more than once. Doing so is invalid. The way people break it is by mixing the two ways of creating a table, because dotted keys create and define a table for every key part before the last one. The specification shows both failures, and the second one is the surprise:
[fruit]
apple = "red"
[fruit] # INVALID: the table already exists
orange = "orange"
[fruit]
apple.color = "red" # this dotted key defines the table fruit.apple
[fruit.apple] # INVALID: that table is already defined
texture = "smooth"
[fruit.apple.skin] # VALID: a header may define a SUB-table of it
type = "thin"The parser reports the collision at the header line, not at the dotted key several lines earlier, which is why the usual experience is that a file which looked fine becomes unparseable after an edit somewhere else in it.
Two related clauses are worth knowing, because both look like errors and are not. Super-tables do not have to be declared: [x.y.z.w] works with no [x] anywhere, and [x] written afterwards is explicitly allowed — defining a super-table afterward is ok. And out-of-order sub-tables are legal but frowned upon: the specification labels interleaving [fruit.apple], [animal], [fruit.orange] as VALID BUT DISCOURAGED, which is exactly the shape a naive appending tool produces when it writes [tool.newthing] at the bottom of a pyproject.toml. Whitespace inside a header is also tolerated — [ g . h . i ] means [g.h.i] — so a diff that adds padding will not fail, it will just look strange.
Strings
TOML has basic strings, literal strings, and multi-line versions of both. Basic strings use double quotes and interpret escape sequences; literal strings use single quotes and interpret nothing, so 'C:\\Users\\name' is exactly the characters you typed. Multi-line basic strings open and close with triple quotes, and inside them a line ending with a single backslash is not an escape: it deletes the newline and all whitespace up to the next non-whitespace character, which is how you wrap a long value without embedding the line break. The trap is that this only exists in multi-line basic strings — no backslash continuation in literal strings, no continuation in single-line forms — and that a stray trailing backslash inside a literal string is just a backslash.
basic = "tab\tand \"quote\" and \u00e9"
literal = 'tab\t stays literal'
multi_basic = """
First line continues \
onto the next because of the trailing backslash.
"""
multi_literal = '''
no escapes here at all: \t stays \t
'''Four string forms, three different answers to the same backslash. multi_basic resolves to a single sentence with no newline in the middle; multi_literal keeps every line break you typed.
Numbers
Integers take decimal with an optional sign, hexadecimal 0x, octal 0o and binary 0b prefixes, and underscores are permitted between digits for readability — 1_000_000 — but not at the start, not at the end, not around the prefix, and not doubled. Leading zeros are not allowed, which is why file modes must be quoted or written with 0o. Floats require either a fractional part or an exponent, accept inf, +inf, -inf and nan, +nan, -nan — and note that a NaN value never compares equal to itself, in TOML as everywhere else, so nan == nan is false whatever the format says.
- bare key
- A TOML key limited to A-Za-z0-9_- ; "1.2" needs quotes or becomes two keys.
- dotted key
- a.b.c = 1 — one assignment that implicitly creates the tables a and a.b.
- array of tables
- Repeated [[name]] headers that append one mapping to a list each time — the only way TOML spells a list of objects.
- line-ending backslash
- Inside a multi-line basic string only: removes the newline and the whitespace that follows it.
- global table
- The root table, where keys written before any header live.
- heterogeneous array
- Legal in TOML: "Values of different types may be mixed." Most style guides still forbid it.
Say it precisely
Tags, constructors, and what a grammar can refuse
YAML's tag mechanism is the most misunderstood part of the format, and it is the correct dividing line between the two languages on security. A YAML node may carry a tag that tells the processor how to construct a value; the !! handle expands to tag:yaml.org,2002: under the core schema, and a local tag written with a single ! is deliberately left undefined by the language. The specification says plainly that language-specific tags such as !ruby/object:Set do not suffice for interoperable exchange. The consequence is that a YAML parser may be configured — historically, by default — to obey a tag it finds in the input and build the thing it names.
That is the entire class of YAML deserialisation incidents: a document containing !!python/object/apply: followed by a module attribute and arguments is, to a loader that honours Python object tags, a function call rather than data. PyYAML documents the problem in its own terms, recommending safe_load for input you do not trust and comparing the unsafe load to pickle; CVE-2017-18342 covers arbitrary code execution through yaml.load before PyYAML 5.1, and CVE-2020-14343 covers a bypass of the intermediate FullLoader before 5.4 through the object constructor it still permitted. Two fixes, and the second one existed because the first one kept a middle ground.
TOML has no tag mechanism, and it is worth stating exactly why that helps. The grammar admits ten value types, named in the specification, and then declares that unspecified values are invalid. There is no syntactic position in which you can write "and now construct an object of class X", so a conforming parser has nothing to obey. The same closure kills the other two YAML payload tricks: there are no anchors or aliases, so there is no reference-multiplying document to expand — a ten-line YAML bomb that becomes hundreds of millions of nodes has no TOML analogue, because TOML cannot name a node and refer back to it — and there is no merge type to be interpreted differently by two libraries.
The second-order lesson from the YAML history is about surface area, and it applies to the format decision itself. Every feature a configuration language has that lets a file say "interpret me" or "expand me" is a place where a parser implementation can be wrong: merge keys that mean different things in two libraries, custom tags that a linter does not understand, anchors that turn into a memory problem. TOML's minimalism is not only an editing argument; it is the same argument made about attack surface. YAML's power is real and its ecosystems need it. Its power is also exactly the thing that has to be switched off when the file comes from somewhere you do not control.
The section people actually want
Which ecosystem chose which format, and why
The distributions are not random. Each ecosystem made a choice that follows from what its files are for, and once you see the pattern the decision table writes itself.
Rust: TOML all the way down
Cargo's manifest, its configuration file and its credentials file are all TOML, and the Cargo book describes the configuration files as TOML with key-value pairs in tables. The reasons are the ones in the objectives paragraph: a package manifest is edited by the package manager itself — cargo add, cargo remove and the release tooling rewrite dependency tables routinely — and a build tool must not lose a human's comment or reorder a section. Rust also inherits the "no build tools required" property: a bootstrap toolchain can parse its own metadata without a YAML library, which matters more in a language whose dependency graph is compiled from source.
Python: TOML for the handshake, YAML for the rest
Python picked TOML for exactly one file, pyproject.toml, and PEP 518's rationale is the clearest statement of the trade-off available anywhere: human-usable unlike JSON, flexible and standards-based unlike INI, not overly complex unlike YAML. That file is the interface between a project and a build back-end — a contract two unrelated programs must read the same way — which is the definition of a case for a closed grammar. PEP 518 defined the [build-system] table; PEP 517 then extended it, in its own words extending the [build-system] table in that file with one additional key, build-backend, and added a backend-path key for in-tree back-ends. PEP 621 put project metadata in [project], and the same PEP states that For tools wishing to store their own settings in pyproject.toml, they may use the [tool] table — PEP 518's own worked example was that the flit tool would store its configuration in [tool.flit] — which is why one file now carries a project's linter, formatter, type checker and test-runner settings in separate tables. Meanwhile Python's operational configuration — Ansible playbooks, pre-commit hooks, CI pipelines, Kubernetes charts — stayed YAML, because those files are nested, list-heavy, human-written and read by one tool. Note also that Python waited until 3.11 to put a TOML reader in the standard library, and still ships no writer: the format is chosen for reading, and PEP 621 explicitly declined to require back-ends to rewrite the file.
Go: neither, by policy
Go's dependency metadata lives in go.mod, a purpose-built line-oriented format with directives such as module, go and require, documented in the Go module reference on the official site, not in TOML or YAML. Go's standard library contains a JSON codec and neither a YAML nor a TOML parser, so any Go program reading configuration pulls in a third-party module, and in practice that means BurntSushi/toml or pelletier/go-toml for TOML and go-yaml for YAML. The Go tools themselves use a bespoke format for their machine-edited metadata — a third answer to the same question, and evidence that "one format for everything" is not the only way to avoid the YAML round-trip problem.
The YAML-stronghold ecosystems
Kubernetes, GitHub Actions, GitLab CI, Docker Compose and OpenAPI are all YAML, and the reasons are structural rather than cultural. Kubernetes' API is JSON; a manifest is a human spelling of a JSON body, converted by the client before the request, so it needs the same expressive surface as JSON plus comments and multi-document files — one ----separated stream can contain a Deployment, a Service and a ConfigMap, which TOML has no way to express. GitHub Actions needs deeply nested job maps, sequences of mappings, and interpolation expressions in strings. GitLab's reference states that GitLab CI/CD configuration uses YAML formatting, so the order of keywords is not important unless otherwise specified, documents a section on YAML anchors for scripts, and then points readers to a schema-level substitute instead: Use extends to reuse configuration sections. and It is similar to YAML anchors, but simpler and you can use extends with include. That pair is the whole YAML story in miniature, a language feature adopted for reuse, then partly replaced by a feature of the schema because the language version turned out to be harder to reason about. Docker Compose files lean on the same language features for shared service defaults, and OpenAPI documents are written in YAML because a schema document wants references, long descriptions as block scalars, and both JSON and YAML readings of the same file.
| File or system | Format | Why that format |
|---|---|---|
| Cargo.toml, .cargo/config.toml | TOML | The package manager rewrites it; comments and one-line-per-key make that safe |
| pyproject.toml: [build-system], [project], [tool.*] | TOML | A contract between a project and unrelated build tooling; PEP 518 said "not overly complex" |
| .cargo/credentials.toml, written by cargo login | TOML | A file the tool creates and updates itself, so editing safety is the whole requirement |
| Kubernetes manifests, Helm values | YAML | A spelling of a JSON API body, plus multi-document streams and lists of mappings |
| GitHub Actions, GitLab CI, CircleCI, Ansible | YAML | Nesting, sequences of maps, block scalars for scripts, interpolation inside strings |
| Docker Compose | YAML | Anchor-based fragments and merge keys for shared service defaults |
| OpenAPI documents | YAML | Long prose descriptions, references, and identical JSON and YAML readings |
| go.mod | neither | Standard-library minimalism plus a machine-edited file: a bespoke format was cheaper |
Read down the Why column, not the Format column. The property that appears most often for TOML is "the tool edits this"; the property that appears most often for YAML is "the shape is nested and the list has objects in it".
The matrix
Converting between the two, and what breaks
There is no shared syntax to exploit: YAML 1.2 can read JSON, TOML can read nothing. Conversion is therefore re-encoding through a common model, and the model you pick decides the losses. The honest intermediate is JSON, because both formats map onto it more or less, and the more-or-less is where the interesting failures live.
| Feature in the source | YAML to TOML | TOML to YAML | What you must decide by hand |
|---|---|---|---|
| null | cannot be represented | trivially fine, emits null | Omit the key, write an empty string, or invent a sentinel per field |
| Nested maps | fine, as tables or dotted keys | fine, as block mappings | Whether to use [a.b] headers or a.b.c = 1, and stick to one style |
| Sequence of maps | only as repeated [[table]] headers | fine | Table naming for every list element; a list inside a list becomes gymnastics |
| Sequence of sequences | legal but unreadable | fine | Whether to inline it or restructure the data |
| Anchors and aliases | must be expanded first | n/a — nothing to expand | Expansion duplicates content, so the TOML file grows and the DRY property is gone |
| Merge keys | must be expanded, and 1.2 parsers may not resolve them | n/a | Which of the two libraries interpretations to encode |
| Multi-document streams | impossible in one file | one YAML document per TOML file | File naming, and losing --- grouping |
| Comments | lost through JSON | lost through JSON | Whether to keep the original file and hand-move values instead |
| Key order | not preserved by the format, by convention | not guaranteed either | Pick a canonical order and generate, or accept noisy diffs |
| Explicit tags, e.g. !!binary | no equivalent | base64 string at best | Decode and re-encode as a typed value or a string |
| Block scalars, | and > | multi-line basic or literal strings | block scalar, chosen from the content | Chomping: whether the final newline was data |
| Sexagesimal and octal 1.1 values | would arrive as ints 75 and 493 | n/a | Whether the number was ever intended |
| Large integers and float precision | integers are 64-bit in practice | depends on the YAML parser | Stringify anything that must survive exactly |
Six of the thirteen rows are only a problem in the YAML-to-TOML direction. That asymmetry is the format's design, not an implementation gap: TOML is a subset of what YAML can say.
Two of these deserve a worked example because they cause the most silent damage. The first is null. A YAML file with timeout: — an empty value, therefore null — converted to TOML either disappears entirely, in which case the loader must apply the same default the YAML reader applied, or becomes timeout = "", in which case a loader that treats an empty string as zero gets a different number. Neither is a bug in the converter; both are a schema decision the converter made for you.
The second is the deeply nested map. YAML nests to any depth for the cost of a column, and TOML nests for the cost of either a header or a dotted path, and headers are file-global: put a [a.b] header in the middle of a long file and every following key belongs to it until the next header, which is exactly how "why is my key ending up under the wrong table" bugs are born. A five-level configuration tree in YAML is comfortable and in TOML is a chore; that is the price of the visibility you paid for in the coercion section, and it is a real price.
Choose on this
The decision table, and the working rules
Everything above compresses into one question with two answers. If the file is a description of a nested, list-heavy system that a human writes and one tool reads, and the tool mostly generates it, use YAML: Kubernetes manifests, CI pipelines, compose files, playbooks, API documents. If the file is project metadata or tool configuration that several unrelated programs must read identically and at least one of them writes, use TOML: the manifest, the build contract, the per-tool table. If both descriptions fit your file, that is a smell — split it.
| Your situation | Pick | The reason, from the specifications |
|---|---|---|
| Humans write and edit the file, no program rewrites it | YAML | Nesting is cheap, comments are local, and the resolver risk is manageable with quoting |
| A command-line tool edits the file after a human wrote it | TOML | One key per line plus explicit tables mean a line edit cannot change the tree |
| Several unrelated programs must agree on the meaning | TOML | A closed set of ten types and no tag mechanism, so there is one answer |
| The payload needs null, or three states of absence | YAML or JSON | TOML declares unspecified values invalid; there is no null to write |
| The payload is a list of objects, edited by hand | YAML | Sequences of mappings are one indentation step, not one header per element |
| The file may come from outside your trust boundary | TOML or JSON | No constructor syntax; with YAML, only a plain-types loader |
| You need many documents in one file | YAML | Stream markers exist; TOML is one document per file |
| You need a machine-generated, reviewable diff | Either, with a fixed emitter | Neither format promises key order |
| Your repo already has both | Keep both, and draw the line at who writes each file | That is the split the ecosystems above converged on |
If your answer keeps landing in the same row as the file you already have, keep the file. Format arguments are cheap; migration is not.
If the repository uses both
It probably should, and the boundary is easy to state. pyproject.toml or Cargo.toml and the [tool.*] tables that hang off them are TOML, because build tools write into them. Your deployment manifests, CI pipelines and local development overrides are YAML, because they are trees with lists of objects in them. API payloads, fixtures and anything a program both produces and consumes are JSON, because there is no human in the loop and JSON's machine-readability is the point. JSON5 earns its place in exactly one spot: a hand-written file that is really a JavaScript object — a lint configuration, a build script's options — where comments and trailing commas matter more than portability, and where nothing outside that toolchain reads it.
repo/
pyproject.toml # TOML: tools write [project] and [tool.*]
Cargo.toml # TOML: cargo add writes [dependencies]
.github/workflows/ci.yml # YAML: nested, list-heavy, one consumer
docker-compose.yml # YAML: anchors for shared service defaults
k8s/base/deployment.yaml # YAML: a spelling of a JSON API body
openapi.yaml # YAML: long descriptions, references
config/app.yaml # YAML: humans edit this, nothing writes it
fixtures/order.json # JSON: generated and consumed by programs onlyNot a style preference. Every TOML file in this list is one a program is expected to edit, and every YAML file is one a human writes in an editor.
Ten rules that keep both formats honest
| Rule | Format | Because |
|---|---|---|
| Quote every string in generated files | YAML | Removes the resolver from the loop entirely |
| Never write a bare version, mode, time or country code | YAML | 1.1 readers turn 1.10, 0755, 1:15 and NO into numbers and booleans |
| Quote file modes as "0755" or use 0o755 | both | TOML bans leading zeros; YAML 1.1 reads them as octal |
| Dates in one style, always quoted in YAML | both | TOML types them, YAML 1.1 types them, 1.2 core does not |
| One nesting style per subtree | TOML | Dotted keys and table headers collide, and the error points at the wrong line |
| No tabs, ever, in YAML indentation | YAML | The specification forbids it and the parse error does not name the character |
| No anchors in files a tool will rewrite | YAML | Anchor survival is a library property, not a format property |
| Do not rely on key order in either format | both | Neither specification defines ordering semantics for tables or mappings |
| Load untrusted YAML with plain-types loaders only | YAML | Tags can name constructors; CVE-2017-18342 and CVE-2020-14343 |
| Add a schema and validate, in whichever format you chose | both | Neither format defines one; every project layers its own |
The last row is the one neither format answers. YAML has no schema language in the standard and TOML has none either — a TOML file that parses is a valid TOML file, which is a much weaker statement than a valid configuration.
If you are here because a build tool asked you to move a file from one format to the other, the sequence that wastes the least time is: convert the YAML to JSON first and read what came back, because that is the document your consumers see; decide each null and each mistyped scalar explicitly; then write the TOML by hand rather than trusting a generator, and keep the original YAML in the pull request so the reviewer can see the schema decisions. For the wider argument about when a text format should carry types at all, the neighbouring pages cover it: YAML vs JSON on implicit typing and the superset claim, the YAML guide on the resolver tables in full, and the config conversion toolkit for the steps this site can actually run for you.
Answers
Questions about YAML and TOML
Is TOML a subset of YAML, or the other way round?
Neither. YAML 1.2 makes JSON a strict subset of YAML, and its introduction says that was the primary focus of the 1.2 revision. TOML is unrelated to both: a different grammar, a different whitespace model, a closed list of value types. A TOML file is not valid YAML and a YAML file is almost never valid TOML, so conversion between them is a re-encoding, not a re-spelling.
Can TOML express null?
No. The TOML v1.0.0 and v1.1.0 specifications list ten permitted value types — String, Integer, Float, Boolean, Offset Date-Time, Local Date-Time, Local Date, Local Time, Array and Inline Table — and state plainly that unspecified values are invalid, with a bare key = given as an invalid example. To mean nothing in TOML, omit the key, or write an empty string or an explicit sentinel. This single fact is the largest source of loss in YAML-to-TOML conversion.
Why does YAML turn NO into false while TOML does not?
Because the YAML 1.1 boolean type matches y, n, yes, no, on, off and their capitalisations, while TOML has exactly two boolean spellings: true and false. Writing enabled = NO in TOML is not a coercion, it is a parse error, and the parser stops. YAML 1.2 core schema dropped most of the 1.1 spellings, but many deployed parsers still implement 1.1, so the risk follows the library, not the file.
Which format is easier for a program to edit?
TOML, and that was the design intent. A key, its equals sign and its value must sit on one line, whitespace around them is ignored, and structure is carried by [table] headers rather than by indentation columns. A tool such as cargo add can rewrite one dependency line and leave the rest of Cargo.toml byte-identical, including comments. Round-tripping YAML without losing comments, key order, anchors and block styles needs a dedicated library.
Is TOML more secure than YAML?
In one precise sense, yes: TOML has no tag or constructor mechanism, so a conforming parser cannot be induced by file content to build an application object, which is the class of bug behind unsafe YAML loading. That is a property of the grammar, not a general guarantee. A TOML value can still be interpreted dangerously by the program that reads it, and unsafe YAML remains safe if loaded with a plain-types loader.
Does TOML have comments, multi-line strings and reuse?
Comments and multi-line strings, yes. A hash marks the rest of the line as a comment except inside a string, and multi-line basic strings support a line-ending backslash that swallows the newline and following whitespace. Reuse, no: TOML has no anchors, no aliases and no merge keys, so a shared block must be repeated, generated, or lifted by the tool that reads the file.
Should I write Kubernetes manifests or CI pipelines in TOML?
No. Kubernetes, GitHub Actions, GitLab CI and Docker Compose parse YAML, and their schemas depend on features TOML lacks: ordered sequences of mappings, multi-document streams separated by three dashes, and anchors for reuse. TOML is the right choice for the layer above or below that — project metadata, build configuration and tool settings, which is what it was designed for.
Can this site convert YAML to TOML?
It cannot. FmtTools converts between YAML and JSON in the browser, with YAML to JSON and JSON to YAML, and neither accepts or emits TOML. The practical path is two steps: parse the YAML to JSON here, inspect the resolved types, then move the values into TOML by hand, because every automatic route has to invent a rule for null, tags and anchors.
Related
Next up
Sources and further reading
- [1]TOML v1.0.0 specification — The stated objectives, the ten permitted value types, the "unspecified values are invalid" rule that removes null, the one-key-per-line requirement, comment syntax, bare and quoted key rules, the "you cannot define a table more than once" rule, heterogeneous arrays, integer underscores and the ban on leading zeros. (accessed November 12, 2026)
- [2]TOML v1.1.0 specification, published 18 December 2025 — The same byline and objectives, plus the new normative sentence about comments — parsers must not modify keys or values based on the presence or contents of a comment — multi-line inline tables, the stricter UTF-8 well-formedness requirement and the date-time separator rules quoted here. (accessed November 12, 2026)
- [3]YAML 1.2.2 specification (2021-10-01) — The introduction statement that the 1.2 revision was published in 2009 with the primary focus of making YAML a strict superset of JSON and that it removed many of the problematic implicit typing recommendations, plus the core schema resolution tables, tag handles and the document-stream model. (accessed November 12, 2026)
- [4]Boolean type for YAML 1.1 (yaml.org type repository) — The regular expression that resolves y, Y, yes, no, on, off and every capitalisation to a boolean — the mechanism behind the country-code and feature-flag incidents described in the coercion section. (accessed November 12, 2026)
- [5]The Cargo Book: Configuration — That Cargo configuration files are written in the TOML format with key-value pairs inside sections called tables, that environment variables take precedence over the TOML files, that the .toml extension became the preferred form in Cargo 1.39, and that the credentials file is created and updated automatically by cargo login and cargo logout. (accessed November 12, 2026)
- [6]PEP 518 — Minimum requirements for an isolated build environment — The verbatim rationale for choosing TOML — human-usable unlike JSON, flexible and standards-based unlike configparser, not overly complex unlike YAML — plus the build-system table, the note that a pyproject.toml may legitimately hold non-build configuration, and the rejected-alternatives discussion. (accessed November 12, 2026)
- [7]Python documentation: tomllib — That the standard library gained a TOML parser in 3.11 for TOML 1.0.0 and parses TOML 1.1.0 in 3.15, that the module does not support writing TOML, that CPython loads entries in source order as an implementation detail, and the mapping of the three local date-time types onto datetime objects. (accessed November 12, 2026)
- [8]GitLab CI/CD YAML reference — That GitLab CI/CD configuration uses YAML formatting so keyword order is unimportant, that YAML anchors are documented for scripts, and that the extends keyword is described as similar to YAML anchors but simpler and usable with include. (accessed November 12, 2026)

The thing JSON cannot do
Comments, whitespace and the human editor
Start with the shared advantage over JSON: both formats have comments, and comments are why either exists as a configuration language at all. In TOML a hash marks the rest of the line as a comment except when inside a string — so
another = "# This is not a comment"is a string that begins with a hash — and control characters other than tab are not permitted in comments. In YAML a space followed by a hash starts a comment, and a hash at the start of a line or after a token does the same. Neither format puts the comment anywhere in the data model: comments are text-layer artifacts that a parser may read and a serializer must invent a mechanism to keep.TOML is explicit that comments carry no meaning, and as of v1.1.0 it says so normatively: parsers must not modify keys or values based on the presence or contents of a comment. That matters more than it reads. It means a TOML tool may reorder lines within a table, drop a blank line, or regenerate a section, and no semantics move. It also means no tool may use a comment as a directive — which is why ecosystem conventions that look like comments are a thing to check, not assume.
YAML comments are equally outside the data model and equally fragile in practice, for a different reason. A YAML comment line is ignored, so adding one never changes the data — but the lines around it are positioned relative to each other, so the edit that follows the comment can. Every YAML editor has met the same three accidents: a commented-out block that silently merges its children into the parent because the block it annotated was the only thing at that indentation; a re-indent that moves a sequence under a different key; and a trailing comment placed inside a multi-line scalar, where it becomes prose. In TOML, the corresponding mistakes are all parse errors.
Answer: a top-level key, because the sequence item ended when the column dedented. Now delete the indentation on one line and re-read the file.
Removing or re-adding a comment changes nothing here, and there is no column for the second tags key to fall back into — it belongs to whichever header is in force, which is written two lines above it.
The asymmetry to remember when you choose: YAML's structure is invisible and therefore editable by accident; TOML's structure is visible and therefore merely verbose. Human-edited files get edited by humans who do not read the whole document, and that is the failure mode a configuration format is judged on.