adding specs for SQL namespace

.cspell

@@ -177,3 +177,7 @@ urldecode
 vectory
 whoamiprotected
 wordnet
+datarows
+syserr
+cuserr
+Rudnick

CHANGELOG.md

@@ -35,6 +35,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added AjvErrorsParser to print more informative error messages ([#364](https://github.com/opensearch-project/opensearch-api-specification/issues/364))
 - Added JsonSchemaValidator, a wrapper for AJV ([#364](https://github.com/opensearch-project/opensearch-api-specification/issues/364))
 - Added support for `application/cbor` responses ([#371](https://github.com/opensearch-project/opensearch-api-specification/pull/371))
+- Added `/_plugins/_sql`, `close`, `explain` and `stats` ([#379](https://github.com/opensearch-project/opensearch-api-specification/pull/379))
+- Added tests for SQL namespace ([#379](https://github.com/opensearch-project/opensearch-api-specification/pull/379))
 - Added support for `application/smile` responses ([#386](https://github.com/opensearch-project/opensearch-api-specification/pull/386))
 - Added `doc_status`, `remote_store`, `segment_replication` and `unreferenced_file_cleanups_performed` to `SegmentStats` ([#395](https://github.com/opensearch-project/opensearch-api-specification/pull/395))
 - Added `concurrent_query_*` and `search_idle_reactivate_count_total` fields to `SearchStats` ([#395](https://github.com/opensearch-project/opensearch-api-specification/pull/395))

spec/namespaces/sql.yaml

@@ -0,0 +1,216 @@
+openapi: 3.1.0
+info:
+  title: OpenSearch SQL API
+  description: OpenSearch SQL API
+  version: 1.0.0
+paths:
+  /_plugins/_sql:
+    post:
+      operationId: sql.query.0
+      x-operation-group: sql.query
+      x-version-added: '1.0'
+      description: Send a SQL/PPL query to the SQL plugin. 
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/sql-ppl-api/
+      parameters:
+        - $ref: '#/components/parameters/sql.query::query.format'
+        - $ref: '#/components/parameters/sql.query::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/sql.query'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.query@200'
+  /_plugins/_sql/_explain:
+    post:
+      operationId: sql.explain.0
+      x-operation-group: sql.explain
+      x-version-added: '1.0'
+      description: Shows how a query is executed against OpenSearch.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/sql-ppl-api/
+      parameters:
+        - $ref: '#/components/parameters/sql.explain::query.format'
+        - $ref: '#/components/parameters/sql.explain::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/sql.explain'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.explain@200'
+  /_plugins/_sql/close:
+    post:
+      operationId: sql.close.0
+      x-operation-group: sql.close
+      x-version-added: '1.0'
+      description: Clear the cursor context.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/sql-ppl-api/
+      parameters:
+        - $ref: '#/components/parameters/sql.close::query.format'
+        - $ref: '#/components/parameters/sql.close::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/sql.close'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.close@200'
+  /_plugins/_sql/stats:
+    get:
+      operationId: sql.get_stats.0
+      x-operation-group: sql.get_stats
+      x-version-added: '1.0'
+      description: Collect metrics for the plugin within the interval.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/monitoring/
+      parameters:
+        - $ref: '#/components/parameters/sql.get_stats::query.format'
+        - $ref: '#/components/parameters/sql.get_stats::query.sanitize'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.get_stats@200'
+    post:
+      operationId: sql.post_stats.1
+      x-operation-group: sql.post_stats
+      x-version-added: '1.0'
+      description: By a stats endpoint, you are able to collect metrics for the plugin within the interval.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/monitoring/
+      parameters:
+        - $ref: '#/components/parameters/sql.post_stats::query.format'
+        - $ref: '#/components/parameters/sql.post_stats::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/sql.post_stats'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.post_stats@200'
+components:
+  parameters:
+    sql.query::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+        description: A short version of the Accept header, e.g. json, yaml.
+    sql.query::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
+    sql.explain::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+        description: A short version of the Accept header, e.g. json, yaml.
+    sql.explain::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
+    sql.close::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+        description: A short version of the Accept header, e.g. json, yaml.
+    sql.close::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
+    sql.get_stats::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+        description: A short version of the Accept header, e.g. json, yaml.
+    sql.get_stats::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
+    sql.post_stats::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+        description: A short version of the Accept header, e.g. json, yaml.
+    sql.post_stats::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
+  requestBodies:
+    sql.query:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlQuery'
+      required: true
+    sql.explain:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlExplain'
+      required: true
+    sql.close:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlClose'
+      required: true
+    sql.post_stats:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlStats'
+      required: true
+  responses:
+    sql.query@200:
+      description: ''
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlQueryResponse'
+    sql.explain@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlExplainResponse'
+      required: true
+    sql.close@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlCloseResponse'
+      required: true
+    sql.get_stats@200:
+      content:
+        text/plain:
+          schema:
+            type: string
+      required: true
+    sql.post_stats@200:
+      content:
+        text/plain:
+          schema:
+            type: string
+      required: true

spec/schemas/sql._common.yaml

@@ -0,0 +1,88 @@
+openapi: 3.1.0
+info:
+  title: Schemas of sql._common category.
+  description: Schemas of sql._common category.
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    SqlQuery:
+      type: object
+      properties:
+        query:
+          type: string
+        filter:
+          type: object
+        fetch_size:
+          type: integer
+    SqlQueryResponse:
+      type: object
+      properties:
+        schema:
+          type: array
+          items:
+            type: object
+        datarows:
+          type: array
+          items:
+            type: array
+        cursor:
+          type: string
+        total:
+          type: integer
+        size:
+          type: integer
+        status:
+          type: integer
+    SqlExplain:
+      type: object
+      properties:
+        query:
+          type: string
+        filter:
+          type: object
+        fetch_size:
+          type: integer
+    SqlExplainResponse:
+      type: object
+      properties:
+        root:
+          $ref: '#/components/schemas/Explain'
+    Explain:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: object
+        children:
+          type: array
+          items: 
+            $ref: '#/components/schemas/Explain'
+    SqlClose:
+      type: object
+      properties:
+        cursor:
+          type: string
+    SqlCloseResponse:
+      type: object
+      properties:
+        succeeded:
+          type: boolean
+    SqlStats:
+      type: object
+      properties:
+        start_time:
+          type: string
+        end_time:
+          type: object
+        cluster_name:
+          type: object
+        index:
+          type: object
+        query:
+          type: object
+        user:
+          type: object
+        execution_time:
+          type: object

tests/sql/close.yaml

@@ -0,0 +1,49 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test to explicitly clear the cursor context
+
+prologues:
+  - path: /{index}
+    method: PUT
+    parameters:
+      index: books
+    request_body:
+      payload: {}
+  - path: /_bulk
+    method: POST
+    request_body:
+      content_type: application/x-ndjson
+      payload:
+        - {create: {_index: books, _id: book_1392214}}
+        - {author: Harper Lee, title: To Kill a Mockingbird, year: 1960}
+        - {create: {_index: books, _id: book_1392215}}
+        - {author: Elizabeth Rudnick, title: Beauty and the Beast, year: 1991}
+  - path: /{index}/_refresh
+    method: POST
+    parameters:
+      index: books
+epilogues:
+  - path: /books
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Get SQL query.
+    id: query_sql
+    path: /_plugins/_sql
+    method: POST
+    request_body:
+      payload:
+        fetch_size: 1
+        query: 'SELECT * FROM books'
+    response:
+      status: 200
+    output:
+      cursor: payload.cursor
+  - synopsis: Close cursor.
+    path: /_plugins/_sql/close
+    method: POST
+    request_body:
+      payload:
+        cursor: ${query_sql.cursor}
+    response:
+      status: 200

tests/sql/explain.yaml

@@ -0,0 +1,22 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test how a query is executed against OpenSearch.
+
+prologues:
+  - path: /books
+    method: PUT
+    request_body:
+      payload: {}
+epilogues:
+  - path: /books
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Get explain of SQL Query
+    path: /_plugins/_sql/_explain
+    method: POST
+    request_body:
+      payload:
+        query: SELECT * FROM books
+    response:
+      status: 200