Merge branch 'main' into execute-watch

Author: kosabogi

.github/validate-pr/index.js

@@ -141,12 +141,10 @@ async function run() {
     }
     comment += `\nYou can validate ${table.length === 1 ? 'this' : 'these'} API${table.length === 1 ? '' : 's'} yourself by using the ${tick}make validate${tick} target.\n`
 
-    await octokit.rest.issues.createComment({
-      owner: 'elastic',
-      repo: 'elasticsearch-specification',
-      issue_number: context.payload.pull_request.number,
-      body: comment
-    })
+    core.setOutput('has_results', 'true')
+    core.setOutput('comment_body', comment)
+  } else {
+    core.setOutput('has_results', 'false')
   }
 
   core.info('Done!')

.github/workflows/validate-pr.yml

@@ -60,18 +60,26 @@ jobs:
           fi
           node scripts/upload-recording/download.js --branch $branch --git
           node scripts/clone-elasticsearch/index.js --branch $branch
-        env:
-          GCS_CREDENTIALS: ${{ secrets.GCS_CREDENTIALS }}
-
-      - name: Remove previous comment
-        uses: maheshrayas/action-pr-comment-delete@v1
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          org: elastic
-          repo: elasticsearch-specification
-          user: github-actions[bot]
-          issue: ${{ github.event.number }}
 
       - name: Run validation
+        id: validation
         working-directory: ./elasticsearch-specification
         run: node .github/validate-pr --token ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Find existing comment
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: 'Following you can find the validation results'
+
+      - name: Create or update comment
+        if: steps.validation.outputs.has_results == 'true'
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: ${{ steps.validation.outputs.comment_body }}
+          edit-mode: replace

api-design-guidelines/data-modelling.md

@@ -150,7 +150,7 @@ Or better yet, to completely avoid using dynamic keys the user-defined value can
 
 ### Model object variants in a consumable way
 
-Sometimes an API accepts an object but the keys are determined by what "kind/variant" of the object is intended. An example of this is aggregations, queries, and pipeline steps. There are two ways the Elasticsearch API handles this situation. The first method is using an **internal variant type** property like "type" with analyzers:
+Sometimes an API accepts an object but the keys are determined by what "kind/variant" of the object is intended. An example of this is aggregations, queries, and pipeline steps. There are two ways the Elasticsearch API handles this situation. The first method is using **internal tagging** with property like "type" with analyzers:
 
 ```yaml
 {
@@ -159,7 +159,7 @@ Sometimes an API accepts an object but the keys are determined by what "kind/var
 }
 ```
 
-The second is using **external variants** where the inner object is wrapped with an object with a single key containing the kind of the inner object. This example changes the analyzer from above to use an external variant:
+The second is using **external tagging** where the inner object is wrapped with an object with a single key containing the kind of the inner object. This example changes the analyzer from above to use an external variant:
 
 ```yaml
 {
@@ -169,7 +169,7 @@ The second is using **external variants** where the inner object is wrapped with
 }
 ```
 
-When choosing between these two possibilities **favor using external variants** as it removes the requirement to buffer key-value pairs until the internal variant property is found. Using external variants also improves traversability of the API (ie auto-complete) as properties can be anticipated without waiting for the discriminant property.
+Internal tagging is a common way to identify variants and should usually be preferred. However, it may have performance implications when used to deserialize large objects in strongly-typed languages. In that case, external tagging should be considered instead, as it removes the requirement to buffer key-value pairs until the internal variant property is found. Using external tagging also improves traversability of the API (ie auto-complete) as properties can be anticipated without waiting for the discriminant property.
 
 ## Model enumerations in a portable way
 

api-design-guidelines/requests-responses.md

@@ -97,34 +97,6 @@ It's best to use the body for large or high cardinality variable-length request
 - Large objects (Query DSL, aggregations, machine learning models)
 - High cardinality variable length values (list of fields, indices, shards, document IDs)
 
-## Adhere to the robustness principle
-
-The robustness principle states:
-
-> "be conservative in what you do, be liberal in what you accept from others"
-
-This principle can apply in a number of ways, but in particular it can determine the design of API requests and responses. An API request may be built flexibly so as to allow both verbose detailed payloads and terse convenience payloads. The corresponding response, however, should always be structured predictably, and not depend on a particular syntax used within the request.
-
-As an example, consider an API that looks up entities based on their ID. The request may be structured to allow either a single ID or a collection of IDs to be passed in. However, the API response should always return a collection of entities, even if that collection only contains one entity.
-
-This principle allows for simpler consumer code that neither has to remember state between request and response, nor needs to "sniff" the output to determine its structure. If multiple variants of the response are truly desired, this may suggest that multiple API endpoints should be introduced, for example called `get_single_entity` and `get_multiple_entities`.
-
-An example of this is the datafeeds API which accepts either a string or list of strings for indices but always returns a list of strings:
-
-```yaml
-PUT /_ml/datafeeds/feed-id
-{
-  "indices": "index-name", // Input is a string.
-  ...
-}
-
-GET /_ml/datafeeds/feed-id
-{
-  "indices": ["index-name"], // Always returns a list of strings.
-  ...
-}
-```
-
 ## Consider how client functions would wrap the API endpoint
 
 It is common within client-side architecture to provide a one-to-one mapping between API endpoint and client language function. This simplifies implementation and documentation, provides good developer experience, and makes tracking of endpoint usage straightforward.

compiler/src/model/utils.ts

@@ -1094,7 +1094,7 @@ export function parseVariantsTag (jsDoc: JSDoc[]): model.Variants | undefined {
   const nonExhaustive = (typeof tags.non_exhaustive === 'string') ? true : undefined
 
   const [type, ...values] = tags.variants.split(' ')
-  if (type === 'external') {
+  if (type === 'typed_keys_quirk') {
     return {
       kind: 'external_tag',
       nonExhaustive: nonExhaustive

docs/modeling-guide.md

@@ -332,7 +332,9 @@ type FooOrBar = Foo | Bar
 
 An example of internal variants are the type mapping properties.
 
-#### External
+#### typed_keys_quirk
+
+**Note**: this feature exists because of some early Elasticsearch APIs where tagging was forgotten, and added after the fact using this quirk to avoid breaking compatibility. **It should not be used for new APIs.**
 
 The key that defines the variant is external to the definition, like in the
 case of aggregations in responses or suggesters.
@@ -343,15 +345,15 @@ name in the definition itself.
 The syntax is:
 
 ```ts
-/** @variants external */
+/** @variants typed_keys_quirk */
 
 /** @variant name='<field-name>' */
 ```
 
 For example:
 
 ```ts
-/** @variants external */
+/** @variants typed_keys_quirk */
 type FooAlias = Faz | Bar
 
 /** @variant name='faz' */
@@ -369,7 +371,7 @@ In the example above, `FooAlias` will look like this:
 
 ```json
 {
-  "faz": {
+  "name#faz": {
     "prop": "hello world"
   }
 }
@@ -379,7 +381,7 @@ or:
 
 ```json
 {
-  "bar": {
+  "name#bar": {
     "prop": true
   }
 }

docs/overlays/elasticsearch-openapi-overlays.yaml

@@ -65,4 +65,12 @@ actions:
   - target: "$.components['schemas']['_types.aggregations.RandomSamplerAggregation']"
     description: Add x-model
     update:
-      x-model: true
+      x-model: true
+# Remove long lists of enum values
+  - target: "$.components['schemas']['cat._types.CatNodeColumn'].anyOf"
+    description: Remove anyOf from cat nodes
+    remove: true
+  - target: "$.components['schemas']['cat._types.CatNodeColumn']"
+    description: Add basic string data type for cat node columns
+    update:
+      type: string

docs/overlays/elasticsearch-shared-overlays.yaml

@@ -1079,5 +1079,17 @@ actions:
   #       x-model: true
 # Remove long lists of enum values
   - target: "$.components['schemas']['cat._types.CatAnomalyDetectorColumn'].enum"
-    description: Remove enum array
+    description: Remove enum array from cat detectors
+    remove: true
+  - target: "$.components['schemas']['cat._types.CatDfaColumn'].enum"
+    description: Remove enum array from cat data frame analytics
+    remove: true
+  - target: "$.components['schemas']['cat._types.CatDatafeedColumn'].enum"
+    description: Remove enum array from cat datafeeds
+    remove: true
+  - target: "$.components['schemas']['cat._types.CatTrainedModelsColumn'].enum"
+    description: Remove enum array from cat trained models
+    remove: true
+  - target: "$.components['schemas']['cat._types.CatTransformColumn'].enum"
+    description: Remove enum array from cat transforms
     remove: true