Document the contract of object keys passed to json_sax::key and key callbacks (#5956)

* Document the contract of object keys passed to json_sax::key and key callbacks

Describe what the name passed to json_sax::key and to a parser callback
for parse_event_t::key holds when parsing JSON text: escapes are decoded
to UTF-8, different spellings of a name yield identical strings, the name
is validated before the call (invalid escapes or UTF-8 give a parse error
and no key event), no normalization or case conversion is applied, the
event precedes the ':' check, and duplicate names are reported once per
occurrence. Also note that sax_parse passes binary-format keys unchanged.

See discussion #5955.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Add a test for the object key contract and correct the BON8 note

Pin the guarantees documented for json_sax::key and the key event of
parser callbacks: decoded names, validation before delivery, delivery
before the colon, one event per repeated name, and the binary formats.
BON8 rejects ill-formed UTF-8 in a name even with sax_parse, so the
note no longer lists it with the formats that pass bytes through.

See discussion #5955.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Fix the GCC build of the object key contract test

GCC 11 in C++11 mode rejects a default argument on a lambda parameter
(-Wc++14-extensions) and ignores a static_cast<void> on the
warn_unused_result of parse(). Pass the input format explicitly and bind
the parse result to a variable.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Add version history for the object key contract

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json/parser_callback_t.md

@@ -63,6 +63,15 @@ called:
 Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
 the latter case, it is skipped completely, or replaced by `null` if it is the top-level value.
 
+## Notes
+
+For a `parse_event_t::key` event, `parsed` holds the decoded object name, with the same guarantees as the `val`
+parameter of [`json_sax::key`](../json_sax/key.md#notes): all escape sequences are decoded and `\uXXXX` escapes are
+stored as UTF-8, so different spellings of the same name yield identical strings; the name is validated completely
+before the callback is called, so a name with an invalid escape sequence or ill-formed UTF-8 causes a parse error and
+no `key` event; no Unicode normalization or case conversion is applied; and a name that occurs several times in the
+same object yields one `key` event per occurrence.
+
 ## Examples
 
 ??? example "Example: skip an object key while parsing"

docs/mkdocs/docs/api/json_sax/key.md

@@ -19,6 +19,23 @@ Whether parsing should proceed.
 
 It is safe to move the passed object key value.
 
+When parsing JSON text, `val` is the decoded object name, not its spelling in the input:
+
+- All escape sequences (`\"`, `\\`, `\/`, `\b`, `\f`, `\n`, `\r`, `\t`, `\uXXXX`, and surrogate pairs) are
+  decoded, and `\uXXXX` escapes are stored as UTF-8. Different spellings of the same name, such as `#!json "/"`
+  and `#!json "\/"`, or `#!json "\u00e9"` and `#!json "\u00E9"`, yield identical strings. An escaped `\u0000` yields
+  an embedded NUL byte.
+- The name is scanned and validated completely before `key` is called. If it contains an invalid escape sequence, an
+  unpaired surrogate, a control character, or ill-formed UTF-8, the parse fails with a
+  [`parse_error`](../../home/exceptions.md#parse-errors), and `key` is not called for it.
+- No Unicode normalization or case conversion is applied: names that differ in any byte are different strings.
+- `key` is called before the following `:` is read, so a parse error may still follow for the same member.
+- A name that occurs several times in the same object is passed once per occurrence.
+
+For the binary formats, object keys contain no escape sequences. For CBOR, MessagePack, UBJSON, and BSON, `val` holds
+the bytes stored in the input, and [`sax_parse`](../basic_json/sax_parse.md) passes them unchanged, without checking them
+for valid UTF-8. BON8 encodes characters itself, so an ill-formed name is a parse error and `key` is not called for it.
+
 ## Examples
 
 ??? example
@@ -45,3 +62,7 @@ It is safe to move the passed object key value.
 ## Version history
 
 - Added in version 3.2.0.
+- The behavior described in the notes above (decoded names, validation before `key` is called, no normalization, `key`
+  before the `:` check, one call per duplicate, bytes of binary formats passed unchanged) is the same in all versions
+  from 3.2.0 on, and for the `key` event of a [parser callback](../basic_json/parser_callback_t.md) from 3.0.0 on. BSON
+  is only supported from version 3.4.0, and BON8 only from version 3.13.0.

docs/mkdocs/docs/features/parsing/sax_interface.md

@@ -64,6 +64,9 @@ bool parse_error(std::size_t position, const std::string& last_token, const json
 
 The return value of each function determines whether parsing should proceed.
 
+Object keys are passed to `key` decoded and validated: escape sequences are already resolved, so different spellings of
+the same name yield the same string. See [`key`](../../api/json_sax/key.md#notes) for the exact guarantees.
+
 ## Stepping through the events
 
 The events for a small input, step by step, and what two different handlers do with them. Press *Play* or step with *Next*: