Skip to content
FmtTools

Format comparison

YAML and TOML, Compared on the Things That Break

TOML exists because YAML configuration could not be edited safely by tools. Here is the whole argument, checked clause by clause against both specifications.

Updated
November 12, 2026
Reading time
27 min read
Length
5,850 words
Reviewer note
Checked against the published specification
Two configuration files side by side: a YAML document whose nesting is expressed by indentation, and a TOML document whose nesting is expressed by bracketed table headers and one key per line.

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.

the same service, written in each format14 lines
# 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.

the same service, as TOML14 lines
# 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.

The two charters, side by side, in their own words
QuestionYAML 1.2.2TOML 1.0.0 / 1.1.0
Declared purposeA human-oriented data serialization language, and a strict superset of JSONA minimal configuration file format, easy to read due to obvious semantics
Target modelA representation graph of nodes with tags, which may contain shared nodesMaps unambiguously to a hash table
Type systemOpen: tags and a schema decide; three recommended schemas, and implementations may add moreClosed: ten value types, and "unspecified values are invalid"
StructureIndentation and block contextExplicit headers, dotted keys and one key per line
ReuseAnchors, aliases and a 1.1 merge typeNone
DocumentsA stream of zero or more documents per fileExactly one document per file
Versioning posture1.2 is a superset aimed at 1.1 compatibility; 1.1 semantics still ship1.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.

absence, in three vocabularies5 lines
# 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.

the same four states, as TOML4 lines
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 = # INVALID

In 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

Expressiveness, checked against the specifications rather than against taste
ConceptYAML 1.2TOML 1.1.0Consequence when converting
nullfive spellings plus emptynot representableYAML to TOML: every null becomes an omitted key, a string, or a silent failure
booleantrue/false in 1.2 core; 24 spellings in 1.1exactly true and falseTOML to YAML: safe; YAML to TOML: quote the 1.1 spellings first
integerdecimal, 0x, 0o, 1_000 in 1.1, sign alloweddecimal, 0x, 0o, 0b, underscores, no leading zerosBoth handle it; the spellings differ
float0., .5, 1e3, .inf, .nanrequires a dot or exponent; inf, +inf, -inf, nan, +nan, -nanNaN equality stays broken in both
date and timeno timestamp type in the 1.2 schemas; a 1.1 type otherwisefour first-class temporal typesTOML dates leave as strings or as objects depending on the reader
ordered sequencefirst-class, of any node typefirst-class, may mix typesFine in both directions
mapping with non-string keyslegal, including sequence and complex keyskeys are always stringsYAML to TOML needs key stringification; JSON cannot do it either
shared nodes (anchors)first-class; the model is a graphabsentAny YAML alias must be expanded before conversion
multiple documentsone stream, many documentsone document per fileA Kubernetes manifest has no TOML equivalent
commentsyes, not part of the data modelyes, explicitly not part of the dataLost by every JSON-mediated round trip
application types via tagsyes, by designno mechanism existsThe 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:

The four ways to say "nested" in TOML, and what each one is
ConstructExampleProducesNotes
Table header[service.limits]a map at service.limitsEvery following key belongs to it until the next header; order of definition is free
Dotted keyservice.limits.cpu = "500m"the same map, created implicitlyDotted keys define their parent tables; a bare key may contain dots only as a separator
Inline tablelimits = { cpu = "500m", memory = "128Mi" }a map, as one valueSelf-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 mapsRepeated 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.

a list of objects, both ways8 lines
# k8s-style: five items, easy to reorder
ports:
  - name: http
    containerPort: 8080
    protocol: TCP
  - name: metrics
    containerPort: 9090
    protocol: TCP

Each item is four lines and the block for item two can be cut and pasted anywhere in the sequence.

the same list, as an array of tables9 lines
[[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.

the edit, as a diff: cargo add and its YAML equivalent2 lines
$ 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.

What survives an automated edit, format by format
Artifact in the fileTOML with a line-editing toolYAML with a load-and-dump toolYAML with a round-trip tool
CommentsUntouched — the tool does not read themLost, unless the library models themPreserved, as non-data nodes
Key orderUntouchedPreserved by most loaders, not guaranteedPreserved deliberately
Blank lines and groupingUntouchedLostPartly preserved
Scalar style (quotes, block)UntouchedRe-chosen by the emitterPreserved if the library tracks style
Anchors and aliasesNot applicable — they do not existExpanded or dropped depending on the libraryPreserved, with anchor names
Quirks a human typed by handStill thereNormalised awayStill there
A stray indentation changeHarmlessChanges the dataChanges 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.

one file, four traps in it6 lines
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 string

This file parses without complaint in every YAML library you have. Ask what it means after resolution and you get two different answers.

resolved with a YAML 1.1 implementation, e.g. libyaml or PyYAML6 lines
country   -> bool   false
release   -> float  1.1
file_mode -> int    493
start     -> int    75
cutoff    -> date   2024-01-15
flag      -> bool   true

Two 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.

resolved with a YAML 1.2 core implementation6 lines
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.

The same six values as TOML: what you write and what happens
IntentYAML 1.1YAML 1.2 coreTOMLWhat TOML forces you to do instead
Country code NOboolean falsestringparse errorcountry = "NO" — the quotes are the only legal spelling
Version 1.10float 1.1float 1.1float 1.1version = "1.10"; TOML still types a bare dotted number
Mode 0755int 493string or errorparse errormode = "0755", or mode = 0o755 if you want the number
Time 1:15int 75stringparse errorstart = "1:15"; a colon is not a number in any TOML type
Date 2024-01-15timestamp objectstringLocal DateEither accept a date type or quote it — TOML decides visibly
Flag onboolean truestringparse errorflag = 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:

the ordering error almost everyone hits14 lines
[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.

strings, the four ways9 lines
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.

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.

a comment that changes the meaning of what follows6 lines
jobs:
  - name: build
    # runs on the shared runners
    tags: [linux]
  - name: test
tags: [global]        # is this the second job's tag list, or a top-level key?

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.

the same annotation, in TOML10 lines
[[jobs]]
name = "build"
# runs on the shared runners
tags = ["linux"]

[[jobs]]
name = "test"

[global]
tags = ["global"]

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.

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.

Where each format is the default, and the property that earned it
File or systemFormatWhy that format
Cargo.toml, .cargo/config.tomlTOMLThe package manager rewrites it; comments and one-line-per-key make that safe
pyproject.toml: [build-system], [project], [tool.*]TOMLA contract between a project and unrelated build tooling; PEP 518 said "not overly complex"
.cargo/credentials.toml, written by cargo loginTOMLA file the tool creates and updates itself, so editing safety is the whole requirement
Kubernetes manifests, Helm valuesYAMLA spelling of a JSON API body, plus multi-document streams and lists of mappings
GitHub Actions, GitLab CI, CircleCI, AnsibleYAMLNesting, sequences of maps, block scalars for scripts, interpolation inside strings
Docker ComposeYAMLAnchor-based fragments and merge keys for shared service defaults
OpenAPI documentsYAMLLong prose descriptions, references, and identical JSON and YAML readings
go.modneitherStandard-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.

Conversion matrix: what each direction can and cannot do
Feature in the sourceYAML to TOMLTOML to YAMLWhat you must decide by hand
nullcannot be representedtrivially fine, emits nullOmit the key, write an empty string, or invent a sentinel per field
Nested mapsfine, as tables or dotted keysfine, as block mappingsWhether to use [a.b] headers or a.b.c = 1, and stick to one style
Sequence of mapsonly as repeated [[table]] headersfineTable naming for every list element; a list inside a list becomes gymnastics
Sequence of sequenceslegal but unreadablefineWhether to inline it or restructure the data
Anchors and aliasesmust be expanded firstn/a — nothing to expandExpansion duplicates content, so the TOML file grows and the DRY property is gone
Merge keysmust be expanded, and 1.2 parsers may not resolve themn/aWhich of the two libraries interpretations to encode
Multi-document streamsimpossible in one fileone YAML document per TOML fileFile naming, and losing --- grouping
Commentslost through JSONlost through JSONWhether to keep the original file and hand-move values instead
Key ordernot preserved by the format, by conventionnot guaranteed eitherPick a canonical order and generate, or accept noisy diffs
Explicit tags, e.g. !!binaryno equivalentbase64 string at bestDecode and re-encode as a typed value or a string
Block scalars, | and >multi-line basic or literal stringsblock scalar, chosen from the contentChomping: whether the final newline was data
Sexagesimal and octal 1.1 valueswould arrive as ints 75 and 493n/aWhether the number was ever intended
Large integers and float precisionintegers are 64-bit in practicedepends on the YAML parserStringify 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.

Pick by property, not by preference
Your situationPickThe reason, from the specifications
Humans write and edit the file, no program rewrites itYAMLNesting is cheap, comments are local, and the resolver risk is manageable with quoting
A command-line tool edits the file after a human wrote itTOMLOne key per line plus explicit tables mean a line edit cannot change the tree
Several unrelated programs must agree on the meaningTOMLA closed set of ten types and no tag mechanism, so there is one answer
The payload needs null, or three states of absenceYAML or JSONTOML declares unspecified values invalid; there is no null to write
The payload is a list of objects, edited by handYAMLSequences of mappings are one indentation step, not one header per element
The file may come from outside your trust boundaryTOML or JSONNo constructor syntax; with YAML, only a plain-types loader
You need many documents in one fileYAMLStream markers exist; TOML is one document per file
You need a machine-generated, reviewable diffEither, with a fixed emitterNeither format promises key order
Your repo already has bothKeep both, and draw the line at who writes each fileThat 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.

the same project, split along the ownership line9 lines
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 only

Not 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

Working rules, YAML and TOML
RuleFormatBecause
Quote every string in generated filesYAMLRemoves the resolver from the loop entirely
Never write a bare version, mode, time or country codeYAML1.1 readers turn 1.10, 0755, 1:15 and NO into numbers and booleans
Quote file modes as "0755" or use 0o755bothTOML bans leading zeros; YAML 1.1 reads them as octal
Dates in one style, always quoted in YAMLbothTOML types them, YAML 1.1 types them, 1.2 core does not
One nesting style per subtreeTOMLDotted keys and table headers collide, and the error points at the wrong line
No tabs, ever, in YAML indentationYAMLThe specification forbids it and the parse error does not name the character
No anchors in files a tool will rewriteYAMLAnchor survival is a library property, not a format property
Do not rely on key order in either formatbothNeither specification defines ordering semantics for tables or mappings
Load untrusted YAML with plain-types loaders onlyYAMLTags can name constructors; CVE-2017-18342 and CVE-2020-14343
Add a schema and validate, in whichever format you chosebothNeither 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. [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. [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. [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. [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. [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. [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. [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. [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)