Clarify url.query usage to specify full query string format

CHANGELOG.next.md

@@ -39,6 +39,7 @@ Thanks, you're awesome :-) -->
 
 * Allow Unicode characters in generated ECS yml files. #2478
 * Update semconv version used in file generation to v1.34.0 #2483
+* Added details for implementation of url.query to avoid ambiguity #2488
 
 #### Deprecated
 

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 `?`.<br><br>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>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

@@ -10624,13 +10624,16 @@
       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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: enrichments.indicator.url.registered_domain
       level: extended
@@ -12284,13 +12287,16 @@
       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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: indicator.url.registered_domain
       level: extended
@@ -13353,13 +13359,16 @@
       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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
     - name: registered_domain
       level: extended
       type: keyword

experimental/generated/csv/fields.csv

@@ -1361,7 +1361,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 9.1.0-dev+exp,true,threat,threat.enrichments.indicator.url.password,keyword,extended,,,Password of the request.
 9.1.0-dev+exp,true,threat,threat.enrichments.indicator.url.path,wildcard,extended,,,"Path of the request, such as ""/search""."
 9.1.0-dev+exp,true,threat,threat.enrichments.indicator.url.port,long,extended,,443,"Port of the request, such as 443."
-9.1.0-dev+exp,true,threat,threat.enrichments.indicator.url.query,keyword,extended,,,Query string of the request.
+9.1.0-dev+exp,true,threat,threat.enrichments.indicator.url.query,keyword,extended,,q=elasticsearch&sort=desc,Query string of the request.
 9.1.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.1.0-dev+exp,true,threat,threat.enrichments.indicator.url.scheme,keyword,extended,,https,Scheme of the url.
 9.1.0-dev+exp,true,threat,threat.enrichments.indicator.url.subdomain,keyword,extended,,east,The subdomain of the domain.
@@ -1584,7 +1584,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 9.1.0-dev+exp,true,threat,threat.indicator.url.password,keyword,extended,,,Password of the request.
 9.1.0-dev+exp,true,threat,threat.indicator.url.path,wildcard,extended,,,"Path of the request, such as ""/search""."
 9.1.0-dev+exp,true,threat,threat.indicator.url.port,long,extended,,443,"Port of the request, such as 443."
-9.1.0-dev+exp,true,threat,threat.indicator.url.query,keyword,extended,,,Query string of the request.
+9.1.0-dev+exp,true,threat,threat.indicator.url.query,keyword,extended,,q=elasticsearch&sort=desc,Query string of the request.
 9.1.0-dev+exp,true,threat,threat.indicator.url.registered_domain,keyword,extended,,example.com,"The highest registered url domain, stripped of the subdomain."
 9.1.0-dev+exp,true,threat,threat.indicator.url.scheme,keyword,extended,,https,Scheme of the url.
 9.1.0-dev+exp,true,threat,threat.indicator.url.subdomain,keyword,extended,,east,The subdomain of the domain.
@@ -1720,7 +1720,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 9.1.0-dev+exp,true,url,url.password,keyword,extended,,,Password of the request.
 9.1.0-dev+exp,true,url,url.path,wildcard,extended,,,"Path of the request, such as ""/search""."
 9.1.0-dev+exp,true,url,url.port,long,extended,,443,"Port of the request, such as 443."
-9.1.0-dev+exp,true,url,url.query,keyword,extended,,,Query string of the request.
+9.1.0-dev+exp,true,url,url.query,keyword,extended,,q=elasticsearch&sort=desc,Query string of the request.
 9.1.0-dev+exp,true,url,url.registered_domain,keyword,extended,,example.com,"The highest registered url domain, stripped of the subdomain."
 9.1.0-dev+exp,true,url,url.scheme,keyword,extended,,https,Scheme of the url.
 9.1.0-dev+exp,true,url,url.subdomain,keyword,extended,,east,The subdomain of the domain.

experimental/generated/ecs/ecs_flat.yml

@@ -17748,13 +17748,15 @@ 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 `?`.
+
+    The query field describes the query string of the request, 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.'
+  example: q=elasticsearch&sort=desc
   flat_name: threat.enrichments.indicator.url.query
   ignore_above: 2083
   level: extended
@@ -20547,13 +20549,15 @@ 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 `?`.
+
+    The query field describes the query string of the request, 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.'
+  example: q=elasticsearch&sort=desc
   flat_name: threat.indicator.url.query
   ignore_above: 2083
   level: extended
@@ -22390,13 +22394,15 @@ 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 `?`.
+
+    The query field describes the query string of the request, 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.'
+  example: q=elasticsearch&sort=desc
   flat_name: url.query
   ignore_above: 2083
   level: extended

experimental/generated/ecs/ecs_nested.yml

@@ -20516,13 +20516,16 @@ 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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
       flat_name: threat.enrichments.indicator.url.query
       ignore_above: 2083
       level: extended
@@ -23323,13 +23326,16 @@ 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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
       flat_name: threat.indicator.url.query
       ignore_above: 2083
       level: extended
@@ -25294,13 +25300,16 @@ 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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
       flat_name: url.query
       ignore_above: 2083
       level: extended

generated/beats/fields.ecs.yml

@@ -10574,13 +10574,16 @@
       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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: enrichments.indicator.url.registered_domain
       level: extended
@@ -12234,13 +12237,16 @@
       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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
       default_field: false
     - name: indicator.url.registered_domain
       level: extended
@@ -13303,13 +13309,16 @@
       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
+        `?`.
+
+        The query field describes the query string of the request, 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.'
+      example: q=elasticsearch&sort=desc
     - name: registered_domain
       level: extended
       type: keyword