Clarify that key comparison is ordinal (closes toml-lang#966)

marzer · Sep 27, 2023 · c3c6ab1 · c3c6ab1
1 parent 23c3fb7
commit c3c6ab1
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@
 - Seconds in Date-Time and Time values are now optional.
 - Allow non-English scripts in unquoted (bare) keys
 - Clarify newline normalization in multi-line literal strings.
+- Clarify that key comparison is ordinal (i.e. does no Unicode normalization)
 
 ## 1.0.0 / 2021-01-11
 

diff --git a/toml.md b/toml.md
@@ -205,6 +205,19 @@ spelling = "favorite"
 "spelling" = "favourite"
 ```
 
+Keys are considered identical if their code point sequences are the same.
+It is possible to create distinct keys that appear visually identical. Doing so is discouraged:
+
+```toml
+# VALID BUT DISCOURAGED
+
+# prénom = "Françoise", using NFC
+"pr\u00e9nom" = "Françoise"
+
+# prénom = "Françoise", using NFD
+"pr\u0065\u0301nom" = "Françoise"
+```
+
 As long as a key hasn't been directly defined, you may still write to it and to
 names within it.