Update rest-api-spec (#5539)

github-actions[bot] · pquentin · web-flow · commit 458b1b8ed7bf · 2025-10-28T21:32:37.000+04:00
Co-authored-by: pquentin &lt;42327+pquentin@users.noreply.github.com&gt;
diff --git a/specification/_json_spec/connector.sync_job_list.json b/specification/_json_spec/connector.sync_job_list.json
@@ -29,8 +29,17 @@
         "description": "specifies a max number of results to get (default: 100)"
       },
       "status": {
-        "type": "string",
-        "description": "Sync job status, which sync jobs are fetched for"
+        "type": "enum",
+        "description": "A sync job status to fetch connector sync jobs for",
+        "options": [
+          "canceling",
+          "canceled",
+          "completed",
+          "error",
+          "in_progress",
+          "pending",
+          "suspended"
+        ]
       },
       "connector_id": {
         "type": "string",
diff --git a/specification/_json_spec/esql.async_query.json b/specification/_json_spec/esql.async_query.json
@@ -20,8 +20,18 @@
     },
     "params": {
       "format": {
-        "type": "string",
-        "description": "a short version of the Accept header, e.g. json, yaml"
+        "type": "enum",
+        "description": "A short version of the Accept header, e.g. json, yaml.\n\n`csv`, `tsv`, and `txt` formats will return results in a tabular format, excluding other metadata fields from the response.\n\nFor async requests, nothing will be returned if the async query doesn't finish within the timeout.\nThe query ID and running status are available in the `X-Elasticsearch-Async-Id` and `X-Elasticsearch-Async-Is-Running` HTTP headers of the response, respectively.",
+        "options": [
+          "csv",
+          "json",
+          "tsv",
+          "txt",
+          "yaml",
+          "cbor",
+          "smile",
+          "arrow"
+        ]
       },
       "delimiter": {
         "type": "string",
diff --git a/specification/_json_spec/esql.async_query_get.json b/specification/_json_spec/esql.async_query_get.json
@@ -25,8 +25,18 @@
     },
     "params": {
       "format": {
-        "type": "string",
-        "description": "a short version of the Accept header, e.g. json, yaml"
+        "type": "enum",
+        "description": "A short version of the Accept header, for example `json` or `yaml`.",
+        "options": [
+          "csv",
+          "json",
+          "tsv",
+          "txt",
+          "yaml",
+          "cbor",
+          "smile",
+          "arrow"
+        ]
       },
       "wait_for_completion_timeout": {
         "type": "time",
diff --git a/specification/_json_spec/esql.query.json b/specification/_json_spec/esql.query.json
@@ -20,8 +20,18 @@
     },
     "params": {
       "format": {
-        "type": "string",
-        "description": "a short version of the Accept header, e.g. json, yaml"
+        "type": "enum",
+        "description": "A short version of the Accept header, e.g. json, yaml.\n\n`csv`, `tsv`, and `txt` formats will return results in a tabular format, excluding other metadata fields from the response.",
+        "options": [
+          "csv",
+          "json",
+          "tsv",
+          "txt",
+          "yaml",
+          "cbor",
+          "smile",
+          "arrow"
+        ]
       },
       "delimiter": {
         "type": "string",
diff --git a/specification/_json_spec/ml.get_trained_models.json b/specification/_json_spec/ml.get_trained_models.json
@@ -34,8 +34,15 @@
         "default": true
       },
       "include": {
-        "type": "string",
-        "description": "A comma-separate list of fields to optionally include. Valid options are 'definition' and 'total_feature_importance'. Default is none."
+        "type": "enum",
+        "description": "A comma delimited string of optional fields to include in the response\nbody.",
+        "options": [
+          "definition",
+          "feature_importance_baseline",
+          "hyperparameters",
+          "total_feature_importance",
+          "definition_status"
+        ]
       },
       "decompress_definition": {
         "type": "boolean",
diff --git a/specification/_json_spec/ml.start_trained_model_deployment.json b/specification/_json_spec/ml.start_trained_model_deployment.json
@@ -45,9 +45,9 @@
         "default": 1
       },
       "priority": {
-        "type": "string",
+        "type": "enum",
         "description": "The deployment priority.",
-        "default": "normal"
+        "options": ["normal", "low"]
       },
       "queue_capacity": {
         "type": "int",
@@ -60,9 +60,9 @@
         "default": "20s"
       },
       "wait_for": {
-        "type": "string",
-        "description": "The allocation status for which to wait",
-        "options": ["starting", "started", "fully_allocated"],
+        "type": "enum",
+        "description": "Specifies the allocation status to wait for before returning.",
+        "options": ["started", "starting", "fully_allocated"],
         "default": "started"
       }
     },
diff --git a/specification/_json_spec/simulate.ingest.json b/specification/_json_spec/simulate.ingest.json
@@ -34,8 +34,9 @@
         "description": "The pipeline id to preprocess incoming documents with if no pipeline is given for a particular document"
       },
       "merge_type": {
-        "type": "string",
-        "description": "The mapping merge type if mapping overrides are being provided in mapping_addition. The allowed values are one of index or template. The index option merges mappings the way they would be merged into an existing index. The template option merges mappings the way they would be merged into a template.",
+        "type": "enum",
+        "description": "The mapping merge type if mapping overrides are being provided in mapping_addition.\nThe allowed values are one of index or template.\nThe index option merges mappings the way they would be merged into an existing index.\nThe template option merges mappings the way they would be merged into a template.",
+        "options": ["index", "template"],
         "default": "index"
       }
     },
diff --git a/specification/_json_spec/sql.query.json b/specification/_json_spec/sql.query.json
@@ -20,8 +20,9 @@
     },
     "params": {
       "format": {
-        "type": "string",
-        "description": "a short version of the Accept header, e.g. json, yaml"
+        "type": "enum",
+        "description": "The format for the response.\nYou can also specify a format using the `Accept` HTTP header.\nIf you specify both this parameter and the `Accept` HTTP header, this parameter takes precedence.",
+        "options": ["csv", "json", "tsv", "txt", "yaml", "cbor", "smile"]
       },
       "project_routing": {
         "type": "string",
diff --git a/specification/_json_spec/streams.logs_disable.json b/specification/_json_spec/streams.logs_disable.json
@@ -1,10 +1,10 @@
 {
   "streams.logs_disable": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/streams-logs-disable.html",
+      "url": "https://www.elastic.co/docs/api/doc/elasticsearch#TODO",
       "description": "Disable the Logs Streams feature for this cluster"
     },
-    "stability": "stable",
+    "stability": "experimental",
     "visibility": "feature_flag",
     "feature_flag": "logs_stream",
     "headers": {
diff --git a/specification/_json_spec/streams.logs_enable.json b/specification/_json_spec/streams.logs_enable.json
@@ -1,10 +1,10 @@
 {
   "streams.logs_enable": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/streams-logs-enable.html",
+      "url": "https://www.elastic.co/docs/api/doc/elasticsearch#TODO",
       "description": "Enable the Logs Streams feature for this cluster"
     },
-    "stability": "stable",
+    "stability": "experimental",
     "visibility": "feature_flag",
     "feature_flag": "logs_stream",
     "headers": {
diff --git a/specification/_json_spec/streams.status.json b/specification/_json_spec/streams.status.json
@@ -1,10 +1,10 @@
 {
   "streams.status": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/streams-status.html",
+      "url": "https://www.elastic.co/docs/api/doc/elasticsearch#TODO",
       "description": "Return the current status of the streams feature for each streams type"
     },
-    "stability": "stable",
+    "stability": "experimental",
     "visibility": "feature_flag",
     "feature_flag": "logs_stream",
     "headers": {
diff --git a/specification/_json_spec/text_structure.find_field_structure.json b/specification/_json_spec/text_structure.find_field_structure.json
@@ -64,9 +64,10 @@
         "description": "Optional parameter to specify the Grok pattern that should be used to extract fields from messages in a semi-structured text file"
       },
       "ecs_compatibility": {
-        "type": "string",
-        "default": "disabled",
-        "description": "Optional parameter to specify the compatibility mode with ECS Grok patterns - may be either 'v1' or 'disabled'"
+        "type": "enum",
+        "description": "The mode of compatibility with ECS compliant Grok patterns.\nUse this parameter to specify whether to use ECS Grok patterns instead of legacy ones when the structure finder creates a Grok pattern.\nThis setting primarily has an impact when a whole message Grok pattern such as `%{CATALINALOG}` matches the input.\nIf the structure finder identifies a common structure but has no idea of the meaning then generic field names such as `path`, `ipaddress`, `field1`, and `field2` are used in the `grok_pattern` output.\nThe intention in that situation is that a user who knows the meanings will rename the fields before using them.",
+        "options": ["disabled", "v1"],
+        "default": "disabled"
       },
       "timestamp_field": {
         "type": "string",
diff --git a/specification/_json_spec/text_structure.find_message_structure.json b/specification/_json_spec/text_structure.find_message_structure.json
@@ -50,9 +50,10 @@
         "description": "Optional parameter to specify the Grok pattern that should be used to extract fields from messages in a semi-structured text file"
       },
       "ecs_compatibility": {
-        "type": "string",
-        "default": "disabled",
-        "description": "Optional parameter to specify the compatibility mode with ECS Grok patterns - may be either 'v1' or 'disabled'"
+        "type": "enum",
+        "description": "The mode of compatibility with ECS compliant Grok patterns.\nUse this parameter to specify whether to use ECS Grok patterns instead of legacy ones when the structure finder creates a Grok pattern.\nThis setting primarily has an impact when a whole message Grok pattern such as `%{CATALINALOG}` matches the input.\nIf the structure finder identifies a common structure but has no idea of meaning then generic field names such as `path`, `ipaddress`, `field1`, and `field2` are used in the `grok_pattern` output, with the intention that a user who knows the meanings rename these fields before using it.",
+        "options": ["disabled", "v1"],
+        "default": "disabled"
       },
       "timestamp_field": {
         "type": "string",
