DOC: config: clarify some known limitations of the json_query() converter

Oula Kivalo reported that different JSON libraries may process duplicate
keys differently and that most JSON libraries usually decode the stream
before extracting keys, while the current mjson implementation decodes the
contents during extraction instead. Let's document this point so that
users are aware of the limitations and do not rely on the current behavior
and do not use it for what it's not made for (e.g. content sanitization).

This is also the case for jwt_header_query(), jwt_payload_query() and
jwt_verify(), which already refer to this converter for specificities.

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 64314d78974ba6f0193c6494ccae04377d039083..5addf6c53ccbda8a10a02a0b592e262184e57a1c 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -20699,6 +20699,12 @@ json_query(<json_path>[,<output_type>])
   <json_path> must be a valid JSON Path string as defined in
   https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/
 
+  Note: depending on the context and the underlying implementation, extraction
+        of duplicate JSON keys is undefined and might return the first, last,
+        or any other occurrence of the same key from the input content, and if
+        key names are passed encoded, they might not always be matched. In
+        short, this converter is not suitable for content sanitization.
+
   Example:
      # get a integer value from the request body
      # "{"integer":4}" => 5