[Backport][8.x] Add overlay for deep objects in ML analysis_config, datafeed_config, and transform source #2904 (#2923)

Author: lcawl

.spectral.yaml

@@ -19,6 +19,8 @@ rules:
   operation-operationId-valid-in-url: warn
   operation-tag-defined: warn
   operation-tags: warn
+  # Parameters
+  path-params: warn
   # Responses
   operation-success-response: warn
   # Schema

Makefile

@@ -61,10 +61,10 @@ contrib: | generate license-check spec-format-fix transform-to-openapi filter-fo
 
 overlay-docs: ## Apply overlays to OpenAPI documents
 	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp1.json"
-	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-example-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp2.json"
+	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp2.json"
 	@npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-serverless-openapi.examples.json
 	@npx bump overlay "output/openapi/elasticsearch-openapi.json" "docs/overlays/elasticsearch-openapi-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp1.json"
-	@npx bump overlay "output/openapi/elasticsearch-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-example-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp2.json"
+	@npx bump overlay "output/openapi/elasticsearch-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp2.json"
 	@npx @redocly/cli bundle output/openapi/elasticsearch-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-openapi.examples.json
 	rm output/openapi/elasticsearch-serverless-openapi.tmp*.json
 	rm output/openapi/elasticsearch-openapi.tmp*.json

docs/overlays/elasticsearch-openapi-overlays.yaml

@@ -11,7 +11,7 @@ actions:
       description: >
         ## Documentation source and versions
         
-        This documentation is derived from the `main` branch of the [elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) repository.
+        This documentation is derived from the `8.x` branch of the [elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) repository.
         It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
       x-doc-license:
         name: Attribution-NonCommercial-NoDerivatives 4.0 International

docs/overlays/elasticsearch-serverless-openapi-overlays.yaml

@@ -15,7 +15,7 @@ actions:
 
         ## Documentation source and versions
         
-        This documentation is derived from the `main` branch of the [elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) repository.
+        This documentation is derived from the `8.x` branch of the [elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) repository.
         It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
       x-doc-license:
         name: Attribution-NonCommercial-NoDerivatives 4.0 International

docs/overlays/elasticsearch-shared-example-overlays.yaml renamed to docs/overlays/elasticsearch-shared-overlays.yaml

@@ -1,9 +1,80 @@
 # Overlays that are applicable to both Elasticsearch and Elasticsearch Serverless OpenAPI documents
 overlay: 1.0.0
 info:
-  title: Overlays for examples that apply to both Elasticsearcb and Elasticsearch Serverless OpenAPI documents
+  title: Overlays for changes that apply to both Elasticsearch and Elasticsearch Serverless OpenAPI documents
   version: 0.0.1
 actions:
+# Abbreviate and annotate items that are not shown in Bump.sh due to depth limits
+  - target: "$.components['schemas']['ml._types:Datafeed'].properties.query"
+    description: Remove query object from anomaly detection datafeed
+    remove: true
+  - target: "$.components['schemas']['ml._types:Datafeed'].properties"
+    description: Re-add a simplified query object in anomaly detection datafeed
+    update:
+      query:
+        x-abbreviated: true
+        type: object
+        description: >
+          The Elasticsearch query domain-specific language (DSL).
+          This value corresponds to the query object in an Elasticsearch search POST body.
+          All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch.
+          By default, this property has the following value: `{"match_all": {"boost": 1}}`.
+        externalDocs:
+          url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+          description: Query DSL
+  - target: "$.components['schemas']['ml._types:CategorizationAnalyzerDefinition'].properties.tokenizer"
+    description: Remove tokenizer object from ML anomaly detection analysis config
+    remove: true
+  - target: "$.components['schemas']['ml._types:CategorizationAnalyzerDefinition'].properties"
+    description: Re-add a simplified tokenizer object in anomaly detection analysis config
+    update:
+      tokenizer:
+        x-abbreviated: true
+        oneOf:
+          - type: object
+          - type: string
+        description: >
+          The name or definition of the tokenizer to use after character filters are applied.
+          This property is compulsory if `categorization_analyzer` is specified as an object.
+          Machine learning provides a tokenizer called `ml_standard` that tokenizes in a way that has been determined to produce good categorization results on a variety of log file formats for logs in English.
+          If you want to use that tokenizer but change the character or token filters, specify `"tokenizer": "ml_standard"` in your `categorization_analyzer`.
+          Additionally, the `ml_classic` tokenizer is available, which tokenizes in the same way as the non-customizable tokenizer in old versions of the product (before 6.2).
+          `ml_classic` was the default categorization tokenizer in versions 6.2 to 7.13, so if you need categorization identical to the default for jobs created in these versions, specify `"tokenizer": "ml_classic"` in your `categorization_analyzer`.
+        externalDocs:
+          url: https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-tokenizers.html
+          description: Tokenizer reference
+  - target: "$.components['schemas']['ml._types:DataframeAnalyticsSource'].properties.query"
+    description: Remove query object from data frame analytics source
+    remove: true
+  - target: "$.components['schemas']['ml._types:DataframeAnalyticsSource'].properties"
+    description: Re-add a simplified query object in data frame analytics source
+    update:
+      query:
+        x-abbreviated: true
+        type: object
+        description: >
+          The Elasticsearch query domain-specific language (DSL).
+          This value corresponds to the query object in an Elasticsearch search POST body.
+          All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch.
+          By default, this property has the following value: `{"match_all": {}}`.
+        externalDocs:
+          url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+          description: Query DSL
+  - target: "$.components['schemas']['transform._types:Source'].properties.query"
+    description: Remove query object from transform source
+    remove: true
+  - target: "$.components['schemas']['transform._types:Source'].properties"
+    description: Re-add a simplified query object in transform source
+    update:
+      query:
+        x-abbreviated: true
+        type: object
+        description: >
+          A query clause that retrieves a subset of data from the source index.
+        externalDocs:
+          url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+          description: Query DSL
+# Examples
   - target: "$.components['requestBodies']['async_search.submit']"
     description: "Add example for asynch search submit request"
     update: