From 8a384632e1e9e94fe59af345198ac3d0fd4fefcb Mon Sep 17 00:00:00 2001 From: Martin Tournoij Date: Mon, 29 Jun 2026 16:15:32 +0100 Subject: [PATCH] Clarify the reason empty keys are allowed TOML allows empty (quoted) keys: "" = 123 Over the years I've seen a number of people express surprise that it's allowed. The reason it's allowed is because TOML tables are intended to map to hash tables/dictionaries in programming languages, and they allow empty keys. So TOML does too. You can still argue that it's a mistake to allow it in TOML, but we can't change that now and this at least clarifies the thinking behind why it's allowed. --- CHANGELOG.md | 5 ++++- toml.md | 7 +++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 45079849..36ad4d54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,12 @@ ## unreleased -- Clarify that tables typically cannot be nested infinitely [#1087]). +- Clarify that tables typically cannot be nested infinitely ([#1087]). + +- Clarify the reason for allowing empty keys ([#1095]). [#1087]: https://github.com/toml-lang/toml/pull/1087 +[#1095]: https://github.com/toml-lang/toml/pull/1095 ## 1.1.0 / 2025-12-18 diff --git a/toml.md b/toml.md index e4119dcb..d772df7d 100644 --- a/toml.md +++ b/toml.md @@ -129,8 +129,11 @@ to use bare keys except when absolutely necessary. 'quoted "value"' = "value" ``` -A bare key must be non-empty, but an empty quoted key is allowed (though -discouraged). You cannot use multi-line strings to define quoted keys. +You cannot use multi-line strings to define quoted keys. + +TOML tables correspond to hash tables (also known as dictionaries) which usually +permit any string value. For that reason empty quoted keys are allowed, though +discouraged. A bare key must be non-empty. ```toml = "no key name" # INVALID