Merge branch 'main' of https://github.com/Tokesh/opensearch-api-speci…

…fication

.cspell

@@ -2,6 +2,7 @@ aarch
 actiongroup
 actiongroups
 aggregatable
+aoss
 APIV
 argjson
 asciifolding
@@ -59,6 +60,7 @@ gsub
 Gsub
 haasephonetik
 heteroscedastic
+hnsw
 homoscedastic
 hotthreads
 huggingface
@@ -74,6 +76,7 @@ kstem
 kuromoji
 Kuromoji
 languageset
+localstats
 Lovins
 lucene
 Lucene
@@ -90,7 +93,6 @@ mmapfs
 mmdb
 mokotoff
 Moneyball
-Moneyball
 msearch
 msmarco
 mtermvectors
@@ -131,11 +133,15 @@ readingform
 rebalance
 Rebalance
 recoverysource
+Refn
 reindex
 Reindex
 relo
 reloadcerts
 remotestore
+rerank
+Rerank
+Reranker
 rethrottle
 Rethrottle
 rolesmapping
@@ -165,6 +171,7 @@ subqueries
 subschemas
 subword
 syserr
+tcnative
 tdigest
 tenantinfo
 termvectors
@@ -176,6 +183,7 @@ translog
 Translog
 tubone
 ulimits
+Undeploys
 unigrams
 Unmanaged
 unmatch
@@ -186,5 +194,4 @@ urldecode
 vectory
 whoamiprotected
 wordnet
-Yrtsd
-Refn
+Yrtsd

.github/workflows/changelog.yml

@@ -7,7 +7,7 @@ jobs:
   verify-changelog:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           ref: ${{ github.event.pull_request.head.sha }}

.github/workflows/test-spec.yml

@@ -27,17 +27,17 @@ jobs:
             admin_password: admin
           - version: 2.0.0
             admin_password: admin
-          - version: 2.15.0
-          - version: 2.15.0
+          - version: 2.16.0
+          - version: 2.16.0
             tests: plugins/index_state_management
-          - version: 2.15.0
-            tests: snapshot
           - version: 2.16.0
+            tests: snapshot
+          - version: 2.17.0
             hub: opensearchstaging
-            ref: '@sha256:bcd7f5d5d30231f24f266064248cc8d3306574948190f7bf93016dff29acf17e'
+            ref: '@sha256:ed4274522a50228f41b50f1a7ea86e6b52fa6737072fc151b2624d22aff80d56'
           - version: 3.0.0
             hub: opensearchstaging
-            ref: '@sha256:db1918b2b8f7ef6c22dd6ff54a0640877c3d395a392a53864745024933981e3b'
+            ref: '@sha256:cab6f71b284485c44306f8f4849ad520283c2a32ece617109b38183ba29cc401'
 
     name: test-opensearch-spec (version=${{ matrix.entry.version }}, hub=${{ matrix.entry.hub || 'opensearchproject' }}, tests=${{ matrix.entry.tests || 'default' }})
     runs-on: ubuntu-latest
@@ -47,7 +47,7 @@ jobs:
       OPENSEARCH_DOCKER_REF: ${{ matrix.entry.ref }}
       OPENSEARCH_VERSION: ${{ matrix.entry.version }}
       OPENSEARCH_PASSWORD: ${{ matrix.entry.admin_password || 'myStrongPassword123!' }}
-      OPENSEARCH_JAVA_OPTS: ${{ matrix.entry.opts }} -Xms2g -Xmx2g
+      OPENSEARCH_JAVA_OPTS: ${{ matrix.entry.opts }} -Xms8g -Xmx8g
 
     steps:
       - name: Checkout Repo
@@ -95,7 +95,7 @@ jobs:
     if: github.event_name == 'pull_request'
     needs: test-opensearch-spec
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Download Spec Coverage Data
         uses: actions/download-artifact@v4

.github/workflows/test-tools-integ.yml

@@ -24,7 +24,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     env:
-      OPENSEARCH_VERSION: 2.15.0
+      OPENSEARCH_VERSION: 2.16.0
       OPENSEARCH_PASSWORD: myStrongPassword123!
       OPENSEARCH_URL: https://localhost:9200
     steps:

.lycheeignore

@@ -1 +1 @@
-https://localhost:9200*
+https://localhost:*

CHANGELOG.md

@@ -65,7 +65,18 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added metadata additionalProperties to `ErrorCause` ([#462](https://github.com/opensearch-project/opensearch-api-specification/pull/462))
 - Added `creation_date` field to `DanglingIndex` ([#462](https://github.com/opensearch-project/opensearch-api-specification/pull/462))
 - Added doc on `cluster create-index blocked` workaround ([#465](https://github.com/opensearch-project/opensearch-api-specification/pull/465))
+- Added `observability` namespace API specifications ([#474](https://github.com/opensearch-project/opensearch-api-specification/pull/474))
 - Added support for reusing output variables as keys in payload expectations ([#471](https://github.com/opensearch-project/opensearch-api-specification/pull/471))
+- Added support for running tests against Amazon OpenSearch ([#476](https://github.com/opensearch-project/opensearch-api-specification/pull/476))
+- Added API spec for security plugin  ([#271](https://github.com/opensearch-project/opensearch-api-specification/pull/271))
+- Added `/_plugins/_security/api/certificates/` ([#439](https://github.com/opensearch-project/opensearch-api-specification/pull/439))
+- Added `/_plugins/_ml/models/{model_id}/_deploy`, `_undeploy` and `knn_vector` type in `passage_embedding` ([#504](https://github.com/opensearch-project/opensearch-api-specification/pull/504))
+- Added `PersonalizeSearchRanking`, `RetrievalAugmentedGeneration`, `Rerank`, `Collapse`, `TruncateHits` and `SplitResponseProcessor` ([#505](https://github.com/opensearch-project/opensearch-api-specification/pull/505))
+- Added `/_plugins/_security/api/certificates/` to API spec  ([#439](https://github.com/opensearch-project/opensearch-api-specification/pull/439))
+- Added support for annotating and testing the API spec against multiple OpenSearch distributions ([#483](https://github.com/opensearch-project/opensearch-api-specification/pull/483))
+- Added `read_time`, `write_time`, `queue_size` and `io_time_in_millis` to `IoStatDevice` ([#483](https://github.com/opensearch-project/opensearch-api-specification/pull/483))
+- Added `total_rejections_breakup` to `ShardIndexingPressureStats` ([#483](https://github.com/opensearch-project/opensearch-api-specification/pull/483))
+- Added `cancelled_task_percentage` and `current_cancellation_eligible_tasks_count` to `ShardSearchBackpressureTaskCancellationStats` ([#483](https://github.com/opensearch-project/opensearch-api-specification/pull/483))
 
 ### Changed
 
@@ -106,7 +117,11 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Fixed `/_mapping` with `index` in query ([#385](https://github.com/opensearch-project/opensearch-api-specification/pull/385))
 - Fixed duplicate `/_nodes/{node_id}` path ([#416](https://github.com/opensearch-project/opensearch-api-specification/pull/416))
 - Fixed `_source` accepting an array of fields in `/_search` ([#430](https://github.com/opensearch-project/opensearch-api-specification/pull/430))
-- Fixed `_update_by_query` with a simple term ([451](https://github.com/opensearch-project/opensearch-api-specification/pull/451))
+- Fixed `_update_by_query` with a simple term ([#451](https://github.com/opensearch-project/opensearch-api-specification/pull/451))
+- Fixed `Duration` to allow for non-integers ([#479](https://github.com/opensearch-project/opensearch-api-specification/pull/479))
+- Fixed accuracy of the index stats schemas ([#491](https://github.com/opensearch-project/opensearch-api-specification/pull/491))
+- Fixed security spec to add support for 400 and 403s ([#439](https://github.com/opensearch-project/opensearch-api-specification/pull/439))
+- Fixed required parameters in `NodeInfo` and `NodeOperatingSystemInfo` ([#483](https://github.com/opensearch-project/opensearch-api-specification/pull/483))
 
 ### Security
 

DEVELOPER_GUIDE.md

@@ -146,6 +146,10 @@ This repository includes several OpenAPI Specification Extensions to fill in any
 - `x-ignorable`: Denotes that the operation should be ignored by the client generator. This is used in operation groups where some operations have been replaced by newer ones, but we still keep them in the specs because the server still supports them.
 - `x-global`: Denotes that the parameter is a global parameter that is included in every operation. These parameters are listed in the [spec/_global_parameters.yaml](spec/_global_parameters.yaml).
 - `x-default`: Contains the default value of a parameter. This is often used to override the default value specified in the schema, or to avoid accidentally changing the default value when updating a shared schema.
+- `x-distributions-included`: Contains a list of distributions known to include the API.
+- `x-distributions-excluded`: Contains a list of distributions known to exclude the API.
+
+Use `opensearch.org` for the official distribution in `x-distributions-*`, `amazon-managed` for Amazon Managed OpenSearch, and `amazon-serverless` for Amazon OpenSearch Serverless. 
 
 ## Writing Spec Tests
 

TESTING_GUIDE.md

@@ -1,13 +1,17 @@
 <!-- TOC -->
 - [Spec Testing Guide](#spec-testing-guide)
-  - [Running Spec Tests Locally](#running-spec-tests-locally)
-  - [Common Errors](#common-errors)
-    - [401 Unauthorized](#401-unauthorized)
-    - [FORBIDDEN/10/cluster create-index blocked (api)](#forbidden10cluster-create-index-blocked-api)
+  - [Running Spec Tests](#running-spec-tests)
+    - [Running Spec Tests Locally](#running-spec-tests-locally)
+    - [Running Spec Tests with Amazon OpenSearch](#running-spec-tests-with-amazon-opensearch)
+    - [Common Errors](#common-errors)
+      - [401 Unauthorized](#401-unauthorized)
+      - [FORBIDDEN/10/cluster create-index blocked (api)](#forbidden10cluster-create-index-blocked-api)
+      - [FAILED  Cat with a json response (from security-analytics).](#failed--cat-with-a-json-response-from-security-analytics)
   - [Writing Spec Tests](#writing-spec-tests)
     - [Simple Test Story](#simple-test-story)
     - [Using Output from Previous Chapters](#using-output-from-previous-chapters)
     - [Managing Versions](#managing-versions)
+    - [Managing Distributions](#managing-distributions)
     - [Waiting for Tasks](#waiting-for-tasks)
     - [Warnings](#warnings)
       - [multiple-paths-detected](#multiple-paths-detected)
@@ -18,7 +22,9 @@
 
 We have devised our own test framework to test the spec against an OpenSearch cluster. We're still adding more features to the framework as the needs arise, and this document will be updated accordingly. This test framework has also been integrated into the repo's CI/CD pipeline. Checkout the [test-spec](.github/workflows/test-spec.yml) workflow for more details.
 
-## Running Spec Tests Locally
+## Running Spec Tests
+
+### Running Spec Tests Locally
 
 Set up an OpenSearch cluster with Docker:
 
@@ -44,11 +50,25 @@ Verbose output:
 npm run test:spec -- --opensearch-insecure --verbose
 ```
 
+### Running Spec Tests with Amazon OpenSearch
+
+Use an Amazon OpenSearch service instance.
+
+```bash
+export AWS_ACCESS_KEY_ID=<<your AWS access key ID>>
+export AWS_SECRET_ACCESS_KEY=<<your AWS secret access key>>
+export AWS_SESSION_TOKEN=<<optional AWS session token>>
+export AWS_REGION=us-west-2
+export OPENSEARCH_URL=https://....us-west-2.es.amazonaws.com
+
+npm run test:spec
+```
+
 ### Common Errors
 
 #### 401 Unauthorized
 
-Remember to set the `OPENSEARCH_PASSWORD` environment variable everytime you start a new shell to run the tests.
+Remember to set the `OPENSEARCH_PASSWORD` or `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables every time you start a new shell to run the tests.
 
 #### FORBIDDEN/10/cluster create-index blocked (api)
 
@@ -67,6 +87,9 @@ curl -k -X PUT --user "admin:${OPENSEARCH_PASSWORD}" https://localhost:9200/_clu
 '
 ```
 
+#### FAILED  Cat with a json response (from security-analytics).
+The cluster is not loading plugins correctly, maybe it was stopped using `docker kill` instead of `docker stop`. Recreating the cluster should fix the issue: `docker compose up --force-recreate -d`.
+
 ## Writing Spec Tests
 
 The spec tests reside in the [tests/](tests) directory. Tests are organized in suites ([default](tests/default/), etc.), and subsequently in folders that match [namespaces](spec/namespaces). For example, tests for APIs defined in [spec/namespaces/indices.yaml](spec/namespaces/indices.yaml) can be found in [tests/default/indices/index.yaml](tests/default/indices/index.yaml) (for `/{index}`), and [tests/default/indices/doc.yaml](tests/default/indices/doc.yaml) (for `/{index}/_doc`). 
@@ -173,11 +196,11 @@ You can also reuse output in payload expectations. See [tests/plugins/index_stat
 
 ### Managing Versions
 
-It's common to add a feature to the next version of OpenSearch. When adding a new API in the spec, make sure to specify `x-version-added`, `x-version-deprecated` or `x-version-removed`. Finally, specify a semver range in your test stories or chapters as follows.
+It's common to add a feature to the next version of OpenSearch. When adding a new API in the spec, make sure to specify `x-version-added`, `x-version-deprecated` or `x-version-removed`. Finally, specify a semver or a semver range in your test stories or chapters as follows.
 
 ```yaml
-- synopsis: Search with `phase_took` added in OpenSearch 2.12.
-  version: '>= 2.12'
+- synopsis: Search with `phase_took` added in OpenSearch 2.12 and removed in version 3.
+  version: '>=2.12 <3'
   path: /{index}/_search
   parameters:
     index: movies
@@ -187,7 +210,59 @@ It's common to add a feature to the next version of OpenSearch. When adding a ne
     status: 200
 ```
 
-The [integration test workflow](.github/workflows/test-spec.yml) runs a matrix of OpenSearch versions, including the next version. Please check whether the workflow needs an update when adding version-specific tests.
+The test tool will fetch the server version when it starts and use it automatically. The [integration test workflow](.github/workflows/test-spec.yml) runs a matrix of OpenSearch versions, including the next version. Please check whether the workflow needs an update when adding version-specific tests.
+
+### Managing Distributions
+
+OpenSearch consists of plugins that may or may not be present in various distributions. When adding a new API in the spec, you can specify `x-distributions-included` or `x-distributions-excluded` with a list of distributions that have a particular feature. For example, the Amazon Managed OpenSearch supports `GET /`, but Amazon Serverless OpenSearch does not.
+
+```yaml
+/:
+  get:
+    operationId: info.0
+    x-distributions-included:
+      - opensearch.org
+      - amazon-managed
+    x-distributions-excluded:
+      - amazon-serverless
+    description: Returns basic information about the cluster.
+```
+
+Similarly, skip tests that are not applicable to a distribution by listing the distributions that support it.
+
+```yaml
+description: Test root endpoint.
+distributions:
+  - amazon-managed
+  - opensearch.org
+chapters:
+  - synopsis: Get server info.
+    path: /
+    method: GET
+    response:
+      status: 200
+```
+
+To test a particular distribution pass `--opensearch-distribution` to the test tool. For example, the following runs tests against an Amazon Managed OpenSearch instance.
+
+```bash
+export AWS_ACCESS_KEY_ID=...
+export AWS_SECRET_ACCESS_KEY=...
+export AWS_SESSION_TOKEN=...
+export AWS_REGION=us-west-2
+
+export OPENSEARCH_URL=https://....us-west-2.es.amazonaws.com
+
+npm run test:spec -- --opensearch-distribution=amazon-managed
+```
+
+The output will visible skip APIs that are not available in the `amazon-managed` distribution.
+
+```
+PASSED  _core/bulk.yaml (.../_core/bulk.yaml)
+PASSED  _core/info.yaml (.../_core/info.yaml)
+SKIPPED indices/forcemerge.yaml (Skipped because distribution amazon-managed is not opensearch.org.)
+```
 
 ### Waiting for Tasks
 

eslint.config.mjs

@@ -8,6 +8,7 @@ import pluginTs from '@typescript-eslint/eslint-plugin'
 import pluginYml from 'eslint-plugin-yml'
 import pluginCspell from '@cspell/eslint-plugin'
 import pluginStylistic from '@stylistic/eslint-plugin'
+import pluginJest from 'eslint-plugin-jest'
 
 export default [
   pluginJs.configs.recommended,
@@ -28,7 +29,8 @@ export default [
       'license-header': pluginLicenseHeader,
       'eslint-comments': pluginComments,
       '@cspell': pluginCspell,
-      '@stylistic': pluginStylistic
+      '@stylistic': pluginStylistic,
+      'jest': pluginJest
     },
     rules: {
       ...pluginJs.configs.recommended.rules,
@@ -78,6 +80,8 @@ export default [
       ],
       '@typescript-eslint/require-await': 'error',
       '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/unbound-method': 'off',
+      'jest/unbound-method': 'error',
       'array-callback-return': 'off',
       'indent': ['error', 2, { 'SwitchCase': 1 }],
       'new-cap': 'off',

json_schemas/test_story.schema.yaml

@@ -21,6 +21,8 @@ properties:
       $ref: '#/definitions/Chapter'
   version:
     $ref: '#/definitions/Version'
+  distributions:
+    $ref: '#/definitions/Distributions'
 required: [chapters,description]
 additionalProperties: false
 
@@ -85,6 +87,8 @@ definitions:
         $ref: '#/definitions/Output'
       version:
         $ref: '#/definitions/Version'
+      distributions:
+        $ref: '#/definitions/Distributions'
       retry:
         $ref: '#/definitions/Retry'
     required: [method, path]
@@ -106,6 +110,13 @@ definitions:
       The semver range to execute the story or chapter against.
     type: string
 
+  Distributions:
+    description: |
+      The list of distributions that support this API.
+    type: array
+    items:
+      type: string
+
   Retry:
     description: |
       Number of times to retry on error.