Repository: opensearch-project/opensearch-api-specification
Pull request #824: Add additional technical writer feedback to Cluster APIs
Author: login: Naarcha-AWS
Created: 2025-02-26T17:20:37Z | Merged: 2025-03-06T17:35:24Z

This PR adds descriptions for certain enums and array options that exist for Cluster APIs. Also adds defaults where they might not exist, and makes some descriptions more descriptive.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check [here](https://github.com/opensearch-project/OpenSearch/blob/main/CONTRIBUTING.md#developer-certificate-of-origin).



Diff:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf6331b0b..a158d1228 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
+- Added defaults for Cluster APIs ([#824](https://github.com/opensearch-project/opensearch-api-specification/pull/824/))
 - Added `aggs` alias for nested aggregations ([#818](https://github.com/opensearch-project/opensearch-api-specification/pull/818))
 - Added API specs for query groups lifecycle APIs ([#649](https://github.com/opensearch-project/opensearch-api-specification/pull/649))
 - Added Python and Ruby spec validators ([#646](https://github.com/opensearch-project/opensearch-api-specification/pull/646))
diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml
index 6bf615b7e..764f7638c 100644
--- a/spec/namespaces/cluster.yaml
+++ b/spec/namespaces/cluster.yaml
@@ -834,7 +834,7 @@ components:
     cluster.allocation_explain::query.include_yes_decisions:
       in: query
       name: include_yes_decisions
-      description: When `true`, returns any `YES` decisions in the allocation explanation.
+      description: When `true`, returns any `YES` decisions in the allocation explanation. `YES` decisions indicate when a particular shard allocation attempt was successful for the given node.
       schema:
         type: boolean
         default: false
@@ -852,7 +852,7 @@ components:
     cluster.delete_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
-      description: Operation timeout for connection to cluster-manager node.
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       x-version-added: '2.0'
@@ -897,6 +897,7 @@ components:
       style: simple
     cluster.exists_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -932,14 +933,18 @@ components:
       style: simple
     cluster.get_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
+        default: 30s
       x-version-added: '2.0'
     cluster.get_component_template::query.flat_settings:
       in: query
       name: flat_settings
-      description: If `true`, returns settings in flat format.
+      description: |- 
+        Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings.
+        For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`.
       schema:
         type: boolean
         default: false
@@ -973,6 +978,7 @@ components:
       required: true
     cluster.get_settings::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1033,6 +1039,7 @@ components:
     cluster.health::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       x-version-added: '2.0'
@@ -1041,6 +1048,7 @@ components:
       name: expand_wildcards
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/ExpandWildcards'
+        default: open
       style: form
     cluster.health::query.level:
       in: query
@@ -1069,6 +1077,7 @@ components:
     cluster.health::query.timeout:
       in: query
       name: timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       style: form
@@ -1076,6 +1085,7 @@ components:
       in: query
       name: wait_for_active_shards
       schema:
+        default: 0
         $ref: '../schemas/_common.yaml#/components/schemas/WaitForActiveShards'
       style: form
     cluster.health::query.wait_for_events:
@@ -1098,6 +1108,7 @@ components:
       description: Whether to wait until there are no relocating shards in the cluster.
       schema:
         type: boolean
+        default: false
       style: form
     cluster.health::query.wait_for_nodes:
       in: query
@@ -1117,6 +1128,7 @@ components:
       style: form
     cluster.pending_tasks::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1184,6 +1196,7 @@ components:
       style: simple
     cluster.put_component_template::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1221,13 +1234,14 @@ components:
     cluster.put_decommission_awareness::path.awareness_attribute_value:
       name: awareness_attribute_value
       in: path
-      description: The value of the awareness attribute.
+      description: The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method.
       schema:
         type: string
-        description: The value of the awareness attribute.
+        description: The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method.
       required: true
     cluster.put_settings::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
@@ -1258,14 +1272,15 @@ components:
     cluster.put_weighted_routing::path.attribute:
       name: attribute
       in: path
-      description: The name of the awareness attribute.
+      description: The name of awareness attribute, usually `zone`.
       schema:
         type: string
-        description: The name of the awareness attribute.
+        description: The name of awareness attribute, usually `zone`.
       required: true
     cluster.reroute::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
       x-version-added: '2.0'
@@ -1279,7 +1294,7 @@ components:
     cluster.reroute::query.explain:
       in: query
       name: explain
-      description: When `true`, the response contains an explanation of why certain commands can or cannot be executed.
+      description: When `true`, the response contains an explanation of why reroute certain commands can or cannot be executed.
       schema:
         type: boolean
       style: form
@@ -1342,6 +1357,7 @@ components:
       style: form
     cluster.state::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
       in: query
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Duration'
diff --git a/spec/schemas/_common.yaml b/spec/schemas/_common.yaml
index 9b967da60..f75c9fe64 100644
--- a/spec/schemas/_common.yaml
+++ b/spec/schemas/_common.yaml
@@ -1054,14 +1054,25 @@ components:
         - shards
     WaitForEvents:
       description: Waits until all currently queued events with the given priority are processed. 
-      type: string
-      enum:
-        - high
-        - immediate
-        - languid
-        - low
-        - normal
-        - urgent
+      oneOf:
+        - type: string
+          const: immediate
+          description: Highest priority, processed as soon as possible.
+        - type: string
+          const: urgent
+          description: Very high priority, processed after immediate events.
+        - type: string
+          const: high
+          description: High priority, processed after urgent events.
+        - type: string
+          const: normal
+          description: Default priority, processed after high priority events.
+        - type: string
+          const: low
+          description: Low priority, processed after normal events.
+        - type: string
+          const: languid
+          description: Lowest priority, processed after all other events.
     DataStreamName:
       type: string
     CompletionStats:
diff --git a/spec/schemas/cluster.reroute.yaml b/spec/schemas/cluster.reroute.yaml
index 98de24c49..fe266bc9e 100644
--- a/spec/schemas/cluster.reroute.yaml
+++ b/spec/schemas/cluster.reroute.yaml
@@ -121,17 +121,34 @@ components:
         - node
         - shard
     Metric:
-      type: string
-      enum:
-        - _all
-        - blocks
-        - cluster_manager_node
-        - master_node
-        - metadata
-        - nodes
-        - routing_nodes
-        - routing_table
-        - version
+      oneOf:
+        - type: string
+          const: _all
+          description: Returns all available metrics.
+        - type: string
+          const: blocks
+          description: Returns information about cluster-level blocks.
+        - type: string
+          const: cluster_manager_node
+          description: Returns information about the current cluster manager node.
+        - type: string
+          const: master_node
+          description: The alias for `cluster_manager_node`. Deprecated, but maintained for backwards compatibility.
+        - type: string
+          const: metadata
+          description: Returns the cluster state metadata.
+        - type: string
+          const: nodes
+          description: Returns information about nodes in the cluster.
+        - type: string
+          const: routing_nodes
+          description: Returns the node-level shard allocations.
+        - type: string
+          const: routing_table
+          description: Returns index-level shard allocations.
+        - type: string
+          const: version
+          description: Returns the cluster state version.
     RerouteExplanation:
       type: object
       properties:


Reviews:
user: login: nhtruong
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-02-27T16:47:36Z
user: login: nhtruong
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-02-27T16:47:48Z
user: login: Naarcha-AWS
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-03T18:06:20Z
user: login: Naarcha-AWS
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-03T18:06:34Z
user: login: Naarcha-AWS
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-03T18:09:12Z
user: login: nhtruong
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-06T17:35:04Z

Review comments:
diff_hunk: @@ -973,6 +978,7 @@ components:
       required: true
     cluster.get_settings::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units).
path: spec/namespaces/cluster.yaml
user: login: nhtruong
body: The spec is being used by different applications, like codegen to generate api methods for different OpenSearch clients. So having something that's only usable on the docs website like `{{site.url}}{{site.baseurl}}` is not good. We already have the ability replace `https://opensearch.org/docs/latest` with `{{site.url}}{{site.baseurl}}` in the docs tooling here: https://github.com/opensearch-project/documentation-website/blob/main/spec-insert/config.yml#L11 
created_at: 2025-02-27T16:47:36Z
author_association: CONTRIBUTOR
diff_hunk: @@ -1033,6 +1039,7 @@ components:
     cluster.health::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units).
path: spec/namespaces/cluster.yaml
user: login: nhtruong
body: Same issue as above.
created_at: 2025-02-27T16:47:48Z
author_association: CONTRIBUTOR
diff_hunk: @@ -973,6 +978,7 @@ components:
       required: true
     cluster.get_settings::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units).
path: spec/namespaces/cluster.yaml
user: login: Naarcha-AWS
body: ```suggestion
      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
```
created_at: 2025-03-03T18:06:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -1033,6 +1039,7 @@ components:
     cluster.health::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units).
path: spec/namespaces/cluster.yaml
user: login: Naarcha-AWS
body: ```suggestion
      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
```
created_at: 2025-03-03T18:06:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -1342,6 +1357,7 @@ components:
       style: form
     cluster.state::query.cluster_manager_timeout:
       name: cluster_manager_timeout
+      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units).
path: spec/namespaces/cluster.yaml
user: login: Naarcha-AWS
body: ```suggestion
      description: The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units).
```
created_at: 2025-03-03T18:09:12Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-02-26T17:22:41Z
body: # Changes Analysis

**Commit SHA:** bc734aa7a695f89f1e9f7aa2f8c74c079db8cd6f
**Comparing To SHA:** d27f33fd3e5bbb89f597c9a6b6e1bba35fcb0c96

## API Changes

### Summary

```
├─┬Paths
│ ├─┬/_cluster/allocation/explain
│ │ ├─┬GET
│ │ │ └─┬Parameters
│ │ │   └──[🔀] description (18084:20)
│ │ └─┬POST
│ │   └─┬Parameters
│ │     └──[🔀] description (18084:20)
│ ├─┬/_cluster/pending_tasks
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18378:20)
│ ├─┬/_cluster/state/{metric}
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18607:20)
│ ├─┬/_cluster/state
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18607:20)
│ ├─┬/_cluster/reroute
│ │ └─┬POST
│ │   ├─┬Parameters
│ │   │ └──[🔀] description (18544:20)
│ │   └─┬Parameters
│ │     └──[➕] description (18530:20)
│ ├─┬/_cluster/state/{metric}/{index}
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18607:20)
│ ├─┬/_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value}
│ │ └─┬PUT
│ │   └─┬Parameters
│ │     ├──[🔀] description (18484:20)
│ │     └─┬Schema
│ │       └──[🔀] description (18487:22)
│ ├─┬/_cluster/health
│ │ └─┬GET
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18289:20)
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18327:20)
│ │   ├──Parameters
│ │   └─┬Parameters
│ │     └─┬Schema
│ │       └──[➕] default (18358:18)❌ 
│ ├─┬/_component_template
│ │ └─┬GET
│ │   ├─┬Parameters
│ │   │ └──[🔀] description (18192:20)
│ │   └─┬Parameters
│ │     └──[➕] description (18183:20)
│ ├─┬/_cluster/health/{index}
│ │ └─┬GET
│ │   ├──Parameters
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18289:20)
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18327:20)
│ │   └─┬Parameters
│ │     └─┬Schema
│ │       └──[➕] default (18358:18)❌ 
│ ├─┬/_cluster/settings
│ │ ├─┬GET
│ │ │ └─┬Parameters
│ │ │   └──[➕] description (18228:20)
│ │ └─┬PUT
│ │   └─┬Parameters
│ │     └──[➕] description (18491:20)
│ ├─┬/_component_template/{name}
│ │ ├─┬GET
│ │ │ ├─┬Parameters
│ │ │ │ └──[🔀] description (18192:20)
│ │ │ └─┬Parameters
│ │ │   └──[➕] description (18183:20)
│ │ ├─┬PUT
│ │ │ └─┬Parameters
│ │ │   └──[➕] description (18446:20)
│ │ ├─┬POST
│ │ │ └─┬Parameters
│ │ │   └──[➕] description (18446:20)
│ │ ├─┬DELETE
│ │ │ └─┬Parameters
│ │ │   └──[🔀] description (18102:20)
│ │ └─┬HEAD
│ │   └─┬Parameters
│ │     └──[➕] description (18147:20)
│ └─┬/_cluster/routing/awareness/{attribute}/weights
│   └─┬PUT
│     └─┬Parameters
│       ├──[🔀] description (18522:20)
│       └─┬Schema
│         └──[🔀] description (18525:22)
└─┬Components
  ├─┬_common___WaitForEvents
  │ ├──[➖] enum (36771:11)❌ 
  │ ├──[➖] enum (36772:11)❌ 
  │ ├──[➖] enum (36773:11)❌ 
  │ ├──[➖] enum (36768:11)❌ 
  │ ├──[➖] enum (36769:11)❌ 
  │ ├──[➖] enum (36770:11)❌ 
  │ ├──[➖] type (36766:13)❌ 
  │ ├──[➕] oneOf (36783:11)
  │ ├──[➕] oneOf (36786:11)
  │ ├──[➕] oneOf (36789:11)
  │ ├──[➕] oneOf (36792:11)
  │ ├──[➕] oneOf (36795:11)
  │ └──[➕] oneOf (36798:11)
  └─┬cluster.reroute___Metric
    ├──[➖] enum (51125:11)❌ 
    ├──[➖] enum (51128:11)❌ 
    ├──[➖] enum (51129:11)❌ 
    ├──[➖] enum (51130:11)❌ 
    ├──[➖] enum (51131:11)❌ 
    ├──[➖] enum (51133:11)❌ 
    ├──[➖] enum (51126:11)❌ 
    ├──[➖] enum (51127:11)❌ 
    ├──[➖] enum (51132:11)❌ 
    ├──[➖] type (51123:13)❌ 
    ├──[➕] oneOf (51151:11)
    ├──[➕] oneOf (51154:11)
    ├──[➕] oneOf (51157:11)
    ├──[➕] oneOf (51160:11)
    ├──[➕] oneOf (51163:11)
    ├──[➕] oneOf (51166:11)
    ├──[➕] oneOf (51169:11)
    ├──[➕] oneOf (51172:11)
    └──[➕] oneOf (51175:11)

```

| Document Element | Total Changes | Breaking Changes |
|------------------|---------------|------------------|
| paths            | 28            | 2                |
| components       | 32            | 17               |

- ❌ **BREAKING Changes**: _19_ out of _60_
- **Modifications**: _10_
- **Removals**: _17_
- **Additions**: _33_
- **Breaking Removals**: _17_
- **Breaking Additions**: _2_


### Report
The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/13661398857/artifacts/2691231367

## API Coverage


|               | Before                                              | After                                             | Δ                                                 |
|--------------:|-----------------------------------------------------|---------------------------------------------------|---------------------------------------------------|
|   Covered (%) | 663 (64.94 %)     | 663 (64.94 %)     | 0 (0 %)     |
| Uncovered (%) | 358 (35.06 %) | 358 (35.06 %) | 0 (0 %) |
|       Unknown | 45              | 45             | 0             |
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-02-26T18:06:03Z
body: ## Spec Test Coverage Analysis


| Total                        | Tested                                                        |
|------------------------------|---------------------------------------------------------------|
| 595  | 593 (99.66 %)  |
author_association: CONTRIBUTOR
user: login: Naarcha-AWS
created_at: 2025-02-26T18:10:37Z
body: Adding Missing Defaults and changing `enums` to `OneOf` are not breaking changes, since the `enums` already existed as strings and the missing default already exists. Let me know if I need to tweak anything else though.
author_association: CONTRIBUTOR
user: login: Naarcha-AWS
created_at: 2025-02-26T23:13:22Z
body: All checks are passing.

author_association: CONTRIBUTOR
user: login: nhtruong
created_at: 2025-02-27T17:16:19Z
body: I've looked into the Vale error. Looks like a bug on Vale's end. I've created an issue on their repo [here](https://github.com/errata-ai/vale/issues/972).
author_association: CONTRIBUTOR
user: login: nhtruong
created_at: 2025-03-01T00:41:36Z
body: This [PR](https://github.com/opensearch-project/opensearch-api-specification/pull/825) will handle the Vale failure
author_association: CONTRIBUTOR
user: login: nhtruong
created_at: 2025-03-03T20:58:05Z
body: There are still 8 instances of `{{site.url}}{{site.baseurl}}` that need to be replaced.
Don't forget to update CHANGELOG.md
author_association: CONTRIBUTOR
user: login: Naarcha-AWS
created_at: 2025-03-04T18:48:33Z
body: @nhtruong: Do you need update the changelog specifically for the default updates??

author_association: CONTRIBUTOR
user: login: Naarcha-AWS
created_at: 2025-03-04T19:28:55Z
body: @nhtruong: This should be ready for your review now.
author_association: CONTRIBUTOR