[8.19] rest-api-spec: fix and expand deprecation information (#137623) (#138075)

pquentin · web-flow · commit e85eb1f1820c · 2025-11-14T08:53:40.000+01:00
* rest-api-spec: fix and expand deprecation information (#137623) * rest-api-spec: fix and expand deprecation information * Fix JSON Schema validation (cherry picked from commit 0022efd) # Conflicts: # rest-api-spec/src/main/resources/rest-api-spec/api/cluster.exists_component_template.json # rest-api-spec/src/main/resources/rest-api-spec/api/cluster.get_component_template.json # rest-api-spec/src/main/resources/rest-api-spec/api/cluster.state.json # rest-api-spec/src/main/resources/rest-api-spec/api/indices.exists_template.json # rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_index_template.json # rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_mapping.json # rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_settings.json # rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_template.json * Fix rest-api-spec validation
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/clear_scroll.json b/rest-api-spec/src/main/resources/rest-api-spec/api/clear_scroll.json
@@ -32,7 +32,10 @@
             "scroll_id": {
               "type": "list",
               "description": "A comma-separated list of scroll IDs to clear",
-              "deprecated": true
+              "deprecated": {
+                "version": "7.0.0",
+                "description": "A scroll id can be quite large and should be specified as part of the body"
+              }
             }
           },
           "deprecated": {
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/count.json b/rest-api-spec/src/main/resources/rest-api-spec/api/count.json
@@ -45,6 +45,10 @@
         "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)"
       },
       "ignore_throttled": {
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "type": "boolean",
         "default": true,
         "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json b/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json
@@ -127,6 +127,10 @@
         "description": "Maximum number of documents to process (default: all documents)"
       },
       "sort": {
+        "deprecated": {
+          "version": "9.0.0",
+          "description": "This query parameter is not supported and will be removed in a future version"
+        },
         "type": "list",
         "description": "A comma-separated list of <field>:<direction> pairs"
       },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.delete_template.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.delete_template.json
@@ -6,6 +6,10 @@
     },
     "stability": "stable",
     "visibility": "public",
+    "deprecated": {
+      "version": "7.8.0",
+      "description": "Legacy index templates are deprecated in favor of composable templates"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_template.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_template.json
@@ -6,6 +6,10 @@
     },
     "stability": "stable",
     "visibility": "public",
+    "deprecated": {
+      "version": "7.8.0",
+      "description": "Legacy index templates are deprecated in favor of composable templates"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_template.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_template.json
@@ -6,6 +6,10 @@
     },
     "stability": "stable",
     "visibility": "public",
+    "deprecated": {
+      "version": "7.8.0",
+      "description": "Legacy index templates are deprecated in favor of composable templates"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.resolve_cluster.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.resolve_cluster.json
@@ -40,6 +40,10 @@
         "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed). Only allowed when providing an index expression."
       },
       "ignore_throttled": {
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "type": "boolean",
         "default": false,
         "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled. Only allowed when providing an index expression."
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/license.get.json b/rest-api-spec/src/main/resources/rest-api-spec/api/license.get.json
@@ -29,7 +29,10 @@
       },
       "accept_enterprise": {
         "type": "boolean",
-        "deprecated": true,
+        "deprecated": {
+          "version": "7.6.0",
+          "description": "This parameter no longer has any effect"
+        },
         "default": true,
         "description": "Supported for backwards compatibility with 7.x. If this param is used it must be set to true"
       }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.flush_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.flush_job.json
@@ -6,6 +6,10 @@
     },
     "stability": "stable",
     "visibility": "public",
+    "deprecated": {
+      "version": "9.1.0",
+      "description": "Forcing any buffered data to be processed is deprecated, in a future major version a datafeed will be required."
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_trained_models.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.get_trained_models.json
@@ -54,7 +54,10 @@
         "type": "boolean",
         "description": "Should the full model definition be included in the results. These definitions can be large. So be cautious when including them. Defaults to false.",
         "default": false,
-        "deprecated": true
+        "deprecated": {
+          "version": "7.10.0",
+          "description": "This paramater is deprecated in favor of ?include=definition"
+        }
       },
       "decompress_definition": {
         "type": "boolean",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.post_data.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.post_data.json
@@ -6,6 +6,10 @@
     },
     "stability": "stable",
     "visibility": "public",
+    "deprecated": {
+      "version": "7.11.0",
+      "description": "Posting data directly to anomaly detection jobs is deprecated, in a future major version a datafeed will be required."
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.put_datafeed.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.put_datafeed.json
@@ -46,6 +46,10 @@
         "description": "Ignore if the source indices expressions resolves to no concrete indices (default: true)"
       },
       "ignore_throttled": {
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "type": "boolean",
         "default": true,
         "description": "Ignore indices that are marked as throttled (default: true)"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.put_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.put_job.json
@@ -42,6 +42,10 @@
         "description": "Ignore if the source indices expressions resolves to no concrete indices (default: true). Only set if datafeed_config is provided."
       },
       "ignore_throttled": {
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "type": "boolean",
         "default": true,
         "description": "Ignore indices that are marked as throttled (default: true). Only set if datafeed_config is provided."
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.update_datafeed.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.update_datafeed.json
@@ -46,6 +46,10 @@
         "description": "Ignore if the source indices expressions resolves to no concrete indices (default: true)"
       },
       "ignore_throttled": {
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "type": "boolean",
         "default": true,
         "description": "Ignore indices that are marked as throttled (default: true)"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/monitoring.bulk.json b/rest-api-spec/src/main/resources/rest-api-spec/api/monitoring.bulk.json
@@ -33,7 +33,10 @@
             "type": {
               "type": "string",
               "description": "Default document type for items which don't provide one",
-              "deprecated": true
+              "deprecated": {
+                "version": "7.0.0",
+                "description": "Specifying types in urls has been deprecated"
+              }
             }
           },
           "deprecated": {
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/msearch.json b/rest-api-spec/src/main/resources/rest-api-spec/api/msearch.json
@@ -85,7 +85,10 @@
       },
       "ignore_throttled": {
         "type": "boolean",
-        "deprecated": true,
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "default": false,
         "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled"
       },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.delete_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.delete_job.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_jobs.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_jobs.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_rollup_caps.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_rollup_caps.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.put_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.put_job.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.rollup_search.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.rollup_search.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.start_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.start_job.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.stop_job.json b/rest-api-spec/src/main/resources/rest-api-spec/api/rollup.stop_job.json
@@ -6,6 +6,10 @@
     },
     "stability": "experimental",
     "visibility": "public",
+    "deprecated": {
+      "version": "8.11.0",
+      "description": "Rollup APIs are deprecated, use downsampling with time series data stream instead"
+    },
     "headers": {
       "accept": [
         "application/json"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/scroll.json b/rest-api-spec/src/main/resources/rest-api-spec/api/scroll.json
@@ -33,7 +33,10 @@
             "scroll_id": {
               "type": "string",
               "description": "The scroll ID",
-              "deprecated": true
+              "deprecated": {
+                "version": "7.0.0",
+                "description": "A scroll id can be quite large and should be specified as part of the body"
+              }
             }
           },
           "deprecated": {
@@ -50,6 +53,10 @@
         "description": "Specify how long a consistent view of the index should be maintained for scrolled search"
       },
       "scroll_id": {
+        "deprecated": {
+          "version": "7.0.0",
+          "description": "A scroll id can be quite large and should be specified as part of the body"
+        },
         "type": "string",
         "description": "The scroll ID for scrolled search"
       },
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/search.json b/rest-api-spec/src/main/resources/rest-api-spec/api/search.json
@@ -96,6 +96,10 @@
         "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)"
       },
       "ignore_throttled": {
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "type": "boolean",
         "default": true,
         "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/search_template.json b/rest-api-spec/src/main/resources/rest-api-spec/api/search_template.json
@@ -45,6 +45,10 @@
         "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)"
       },
       "ignore_throttled": {
+        "deprecated": {
+          "version": "7.16.0",
+          "description": "This parameter is deprecated because frozen indices have been deprecated."
+        },
         "type": "boolean",
         "default": true,
         "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled"
diff --git a/rest-api-spec/src/main/resources/schema.json b/rest-api-spec/src/main/resources/schema.json
@@ -268,10 +268,7 @@
                     "title": "Default value"
                 },
                 "deprecated": {
-                    "oneOf": [
-                      { "$ref": "#/definitions/Deprecated" },
-                      { "type": "boolean" }
-                    ]
+                    "$ref": "#/definitions/Deprecated"
                 },
                 "description": {
                     "type": "string",
