Clarify url.query usage to specify full query string format (#2488)

* Clarify url.query usage to specify full query string format

This update removes ambiguity around the url.query field by explicitly stating that it should contain the full query string, including compound parameters.

An example with multiple query parameters is added to reinforce this guidance. This helps prevent misinterpretation—such as splitting the query into an array of keywords—and promotes consistent, ECS-compliant implementations across ingestion pipelines and tools.

* Update CHANGELOG.next.md

* generated files from changes

* Trim trailing whitespace

* update to description and regenerated

* fixing changelog

* regenerated experimental fields as well

* tweaked definition one last time

* cleanup per review

---------

Co-authored-by: Michael Wolf <michael.wolf@elastic.co>
Co-authored-by: Kylie Meli <kylie.geller@elastic.co>

Author: 3 people

CHANGELOG.next.md

@@ -30,6 +30,8 @@ Thanks, you're awesome :-) -->
 
 #### Improvements
 
+* Added details for implementation of url.query to avoid ambiguity #2488
+
 #### Deprecated
 
 <!-- All empty sections:

docs/reference/ecs-url.md

@@ -23,7 +23,7 @@ URL fields provide support for complete or partial URLs, and supports the breaki
 | $$$field-url-password$$$ [url.password](#field-url-password) | Password of the request.<br><br>type: keyword | extended |
 | $$$field-url-path$$$ [url.path](#field-url-path) | Path of the request, such as "/search".<br><br>type: wildcard<br><br>![OTel Badge](https://img.shields.io/badge/OpenTelemetry-4a5ca6?style=flat&logo=opentelemetry) [![match](https://img.shields.io/badge/match-93c93e?style=flat)](/reference/ecs-opentelemetry.md#ecs-opentelemetry-relation) [url.path](https://opentelemetry.io/docs/specs/semconv/attributes-registry/url/#url-path) | extended |
 | $$$field-url-port$$$ [url.port](#field-url-port) | Port of the request, such as 443.<br><br>type: long<br><br>example: `443`<br><br>![OTel Badge](https://img.shields.io/badge/OpenTelemetry-4a5ca6?style=flat&logo=opentelemetry) [![match](https://img.shields.io/badge/match-93c93e?style=flat)](/reference/ecs-opentelemetry.md#ecs-opentelemetry-relation) [url.port](https://opentelemetry.io/docs/specs/semconv/attributes-registry/url/#url-port) | extended |
-| $$$field-url-query$$$ [url.query](#field-url-query) | The query field describes the query string of the request, such as "q=elasticsearch".<br><br>The `?` is excluded from the query string. If a URL contains no `?`, there is no query field. If there is a `?` but no query, the query field exists with an empty string. The `exists` query can be used to differentiate between the two cases.<br><br>type: keyword<br><br>![OTel Badge](https://img.shields.io/badge/OpenTelemetry-4a5ca6?style=flat&logo=opentelemetry) [![match](https://img.shields.io/badge/match-93c93e?style=flat)](/reference/ecs-opentelemetry.md#ecs-opentelemetry-relation) [url.query](https://opentelemetry.io/docs/specs/semconv/attributes-registry/url/#url-query) | extended |
+| $$$field-url-query$$$ [url.query](#field-url-query) | The field contains the entire query string, excluding the leading `?` character, such as "q=elasticsearch".<br><br>If a URL contains no `?`, there is no query field. If there is a `?` but no query, the query field exists with an empty string. The `exists` query can be used to differentiate between the two cases.<br><br>type: keyword<br><br>example: `q=elasticsearch&sort=desc`<br><br>![OTel Badge](https://img.shields.io/badge/OpenTelemetry-4a5ca6?style=flat&logo=opentelemetry) [![match](https://img.shields.io/badge/match-93c93e?style=flat)](/reference/ecs-opentelemetry.md#ecs-opentelemetry-relation) [url.query](https://opentelemetry.io/docs/specs/semconv/attributes-registry/url/#url-query) | extended |
 | $$$field-url-registered-domain$$$ [url.registered_domain](#field-url-registered-domain) | The highest registered url domain, stripped of the subdomain.<br><br>For example, the registered domain for "foo.example.com" is "example.com".<br><br>This value can be determined precisely with a list like the public suffix list (https://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk".<br><br>type: keyword<br><br>example: `example.com`<br><br>![OTel Badge](https://img.shields.io/badge/OpenTelemetry-4a5ca6?style=flat&logo=opentelemetry) [![match](https://img.shields.io/badge/match-93c93e?style=flat)](/reference/ecs-opentelemetry.md#ecs-opentelemetry-relation) [url.registered_domain](https://opentelemetry.io/docs/specs/semconv/attributes-registry/url/#url-registered-domain) | extended |
 | $$$field-url-scheme$$$ [url.scheme](#field-url-scheme) | Scheme of the request, such as "https".<br><br>Note: The `:` is not part of the scheme.<br><br>type: keyword<br><br>example: `https`<br><br>![OTel Badge](https://img.shields.io/badge/OpenTelemetry-4a5ca6?style=flat&logo=opentelemetry) [![match](https://img.shields.io/badge/match-93c93e?style=flat)](/reference/ecs-opentelemetry.md#ecs-opentelemetry-relation) [url.scheme](https://opentelemetry.io/docs/specs/semconv/attributes-registry/url/#url-scheme) | extended |
 | $$$field-url-subdomain$$$ [url.subdomain](#field-url-subdomain) | The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain.  In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain.<br><br>For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period.<br><br>type: keyword<br><br>example: `east`<br><br>![OTel Badge](https://img.shields.io/badge/OpenTelemetry-4a5ca6?style=flat&logo=opentelemetry) [![match](https://img.shields.io/badge/match-93c93e?style=flat)](/reference/ecs-opentelemetry.md#ecs-opentelemetry-relation) [url.subdomain](https://opentelemetry.io/docs/specs/semconv/attributes-registry/url/#url-subdomain) | extended |

experimental/generated/beats/fields.ecs.yml

@@ -12385,13 +12385,13 @@
       level: extended
       type: keyword
       ignore_above: 2083
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: enrichments.indicator.url.registered_domain
       level: extended
@@ -14045,13 +14045,13 @@
       level: extended
       type: keyword
       ignore_above: 2083
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: indicator.url.registered_domain
       level: extended
@@ -15114,13 +15114,13 @@
       level: extended
       type: keyword
       ignore_above: 2083
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
     - name: registered_domain
       level: extended
       type: keyword

experimental/generated/csv/fields.csv

@@ -1575,7 +1575,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.password,keyword,extended,,,Password of the request.
 9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.path,wildcard,extended,,,"Path of the request, such as ""/search""."
 9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.port,long,extended,,443,"Port of the request, such as 443."
-9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.query,keyword,extended,,,Query string of the request.
+9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.query,keyword,extended,,q=elasticsearch&sort=desc,Query string of the request.
 9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.registered_domain,keyword,extended,,example.com,"The highest registered url domain, stripped of the subdomain."
 9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.scheme,keyword,extended,,https,Scheme of the url.
 9.3.0-dev+exp,true,threat,threat.enrichments.indicator.url.subdomain,keyword,extended,,east,The subdomain of the domain.
@@ -1798,7 +1798,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 9.3.0-dev+exp,true,threat,threat.indicator.url.password,keyword,extended,,,Password of the request.
 9.3.0-dev+exp,true,threat,threat.indicator.url.path,wildcard,extended,,,"Path of the request, such as ""/search""."
 9.3.0-dev+exp,true,threat,threat.indicator.url.port,long,extended,,443,"Port of the request, such as 443."
-9.3.0-dev+exp,true,threat,threat.indicator.url.query,keyword,extended,,,Query string of the request.
+9.3.0-dev+exp,true,threat,threat.indicator.url.query,keyword,extended,,q=elasticsearch&sort=desc,Query string of the request.
 9.3.0-dev+exp,true,threat,threat.indicator.url.registered_domain,keyword,extended,,example.com,"The highest registered url domain, stripped of the subdomain."
 9.3.0-dev+exp,true,threat,threat.indicator.url.scheme,keyword,extended,,https,Scheme of the url.
 9.3.0-dev+exp,true,threat,threat.indicator.url.subdomain,keyword,extended,,east,The subdomain of the domain.
@@ -1934,7 +1934,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 9.3.0-dev+exp,true,url,url.password,keyword,extended,,,Password of the request.
 9.3.0-dev+exp,true,url,url.path,wildcard,extended,,,"Path of the request, such as ""/search""."
 9.3.0-dev+exp,true,url,url.port,long,extended,,443,"Port of the request, such as 443."
-9.3.0-dev+exp,true,url,url.query,keyword,extended,,,Query string of the request.
+9.3.0-dev+exp,true,url,url.query,keyword,extended,,q=elasticsearch&sort=desc,Query string of the request.
 9.3.0-dev+exp,true,url,url.registered_domain,keyword,extended,,example.com,"The highest registered url domain, stripped of the subdomain."
 9.3.0-dev+exp,true,url,url.scheme,keyword,extended,,https,Scheme of the url.
 9.3.0-dev+exp,true,url,url.subdomain,keyword,extended,,east,The subdomain of the domain.

experimental/generated/ecs/ecs_flat.yml

@@ -21259,13 +21259,13 @@ threat.enrichments.indicator.url.port:
   type: long
 threat.enrichments.indicator.url.query:
   dashed_name: threat-enrichments-indicator-url-query
-  description: 'The query field describes the query string of the request, such as
-    "q=elasticsearch".
+  description: 'The field contains the entire query string, excluding the leading
+    `?` character, such as "q=elasticsearch".
 
-    The `?` is excluded from the query string. If a URL contains no `?`, there is
-    no query field. If there is a `?` but no query, the query field exists with an
-    empty string. The `exists` query can be used to differentiate between the two
-    cases.'
+    If a URL contains no `?`, there is no query field. If there is a `?` but no query,
+    the query field exists with an empty string. The `exists` query can be used to
+    differentiate between the two cases.'
+  example: q=elasticsearch&sort=desc
   flat_name: threat.enrichments.indicator.url.query
   ignore_above: 2083
   level: extended
@@ -24058,13 +24058,13 @@ threat.indicator.url.port:
   type: long
 threat.indicator.url.query:
   dashed_name: threat-indicator-url-query
-  description: 'The query field describes the query string of the request, such as
-    "q=elasticsearch".
+  description: 'The field contains the entire query string, excluding the leading
+    `?` character, such as "q=elasticsearch".
 
-    The `?` is excluded from the query string. If a URL contains no `?`, there is
-    no query field. If there is a `?` but no query, the query field exists with an
-    empty string. The `exists` query can be used to differentiate between the two
-    cases.'
+    If a URL contains no `?`, there is no query field. If there is a `?` but no query,
+    the query field exists with an empty string. The `exists` query can be used to
+    differentiate between the two cases.'
+  example: q=elasticsearch&sort=desc
   flat_name: threat.indicator.url.query
   ignore_above: 2083
   level: extended
@@ -25901,13 +25901,13 @@ url.port:
   type: long
 url.query:
   dashed_name: url-query
-  description: 'The query field describes the query string of the request, such as
-    "q=elasticsearch".
+  description: 'The field contains the entire query string, excluding the leading
+    `?` character, such as "q=elasticsearch".
 
-    The `?` is excluded from the query string. If a URL contains no `?`, there is
-    no query field. If there is a `?` but no query, the query field exists with an
-    empty string. The `exists` query can be used to differentiate between the two
-    cases.'
+    If a URL contains no `?`, there is no query field. If there is a `?` but no query,
+    the query field exists with an empty string. The `exists` query can be used to
+    differentiate between the two cases.'
+  example: q=elasticsearch&sort=desc
   flat_name: url.query
   ignore_above: 2083
   level: extended

experimental/generated/ecs/ecs_nested.yml

@@ -24171,13 +24171,13 @@ threat:
       type: long
     threat.enrichments.indicator.url.query:
       dashed_name: threat-enrichments-indicator-url-query
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
       flat_name: threat.enrichments.indicator.url.query
       ignore_above: 2083
       level: extended
@@ -26978,13 +26978,13 @@ threat:
       type: long
     threat.indicator.url.query:
       dashed_name: threat-indicator-url-query
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
       flat_name: threat.indicator.url.query
       ignore_above: 2083
       level: extended
@@ -28949,13 +28949,13 @@ url:
       type: long
     url.query:
       dashed_name: url-query
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
       flat_name: url.query
       ignore_above: 2083
       level: extended

generated/beats/fields.ecs.yml

@@ -12335,13 +12335,13 @@
       level: extended
       type: keyword
       ignore_above: 2083
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: enrichments.indicator.url.registered_domain
       level: extended
@@ -13995,13 +13995,13 @@
       level: extended
       type: keyword
       ignore_above: 2083
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: indicator.url.registered_domain
       level: extended
@@ -15064,13 +15064,13 @@
       level: extended
       type: keyword
       ignore_above: 2083
-      description: 'The query field describes the query string of the request, such
-        as "q=elasticsearch".
+      description: 'The field contains the entire query string, excluding the leading
+        `?` character, such as "q=elasticsearch".
 
-        The `?` is excluded from the query string. If a URL contains no `?`, there
-        is no query field. If there is a `?` but no query, the query field exists
-        with an empty string. The `exists` query can be used to differentiate between
-        the two cases.'
+        If a URL contains no `?`, there is no query field. If there is a `?` but no
+        query, the query field exists with an empty string. The `exists` query can
+        be used to differentiate between the two cases.'
+      example: q=elasticsearch&sort=desc
     - name: registered_domain
       level: extended
       type: keyword