Update spec and add tests for xy, geo shape, and geo bounding box query

CHANGELOG.md

@@ -141,6 +141,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Fixed content-type for `/hot_threads` ([#543](https://github.com/opensearch-project/opensearch-api-specification/pull/543))
 - Fixed `/_cluster/settings` returning flat results ([#545](https://github.com/opensearch-project/opensearch-api-specification/pull/545))
 - Fixed missing fields in cat API ([#551](https://github.com/opensearch-project/opensearch-api-specification/pull/551))
+- Removed `shape` query from the spec and replaced with `xy_query`. Added specs for `xy_point` and `xy_shape`. Updated spec for `geo_shape` query ([#531](https://github.com/opensearch-project/opensearch-api-specification/pull/531))
 
 ### Security
 

spec/schemas/_common.mapping.yaml

@@ -191,8 +191,8 @@ components:
         - $ref: '#/components/schemas/TokenCountProperty'
         - $ref: '#/components/schemas/GeoPointProperty'
         - $ref: '#/components/schemas/GeoShapeProperty'
-        - $ref: '#/components/schemas/PointProperty'
-        - $ref: '#/components/schemas/ShapeProperty'
+        - $ref: '#/components/schemas/XyPointProperty'
+        - $ref: '#/components/schemas/XyShapeProperty'
         - $ref: '#/components/schemas/ByteNumberProperty'
         - $ref: '#/components/schemas/DoubleNumberProperty'
         - $ref: '#/components/schemas/FloatNumberProperty'
@@ -913,6 +913,10 @@ components:
               $ref: '#/components/schemas/GeoOrientation'
             strategy:
               $ref: '#/components/schemas/GeoStrategy'
+              deprecated: true
+            distance_error_pct:
+              type: number
+              deprecated: true
             type:
               type: string
               enum:
@@ -929,7 +933,8 @@ components:
       enum:
         - recursive
         - term
-    PointProperty:
+    XyPointProperty:
+      x-version-added: 2.4
       allOf:
         - $ref: '#/components/schemas/DocValuesPropertyBase'
         - type: object
@@ -939,14 +944,15 @@ components:
             ignore_z_value:
               type: boolean
             null_value:
-              type: string
+              $ref: '_common.yaml#/components/schemas/XyLocation'
             type:
               type: string
               enum:
-                - point
+                - xy_point
           required:
             - type
-    ShapeProperty:
+    XyShapeProperty:
+      x-version-added: 2.4
       allOf:
         - $ref: '#/components/schemas/DocValuesPropertyBase'
         - type: object
@@ -962,7 +968,7 @@ components:
             type:
               type: string
               enum:
-                - shape
+                - xy_shape
           required:
             - type
     ByteNumberProperty:

spec/schemas/_common.query_dsl.yaml

@@ -153,8 +153,6 @@ components:
           $ref: '#/components/schemas/ScriptQuery'
         script_score:
           $ref: '#/components/schemas/ScriptScoreQuery'
-        shape:
-          $ref: '#/components/schemas/ShapeQuery'
         simple_query_string:
           $ref: '#/components/schemas/SimpleQueryStringQuery'
         span_containing:
@@ -209,6 +207,8 @@ components:
             $ref: '#/components/schemas/TextExpansionQuery'
           minProperties: 1
           maxProperties: 1
+        type:
+          $ref: '#/components/schemas/TypeQuery'
         weighted_tokens:
           description: Supports returning text_expansion query results by sending in precomputed tokens with the query.
           type: object
@@ -225,8 +225,8 @@ components:
           maxProperties: 1
         wrapper:
           $ref: '#/components/schemas/WrapperQuery'
-        type:
-          $ref: '#/components/schemas/TypeQuery'
+        xy_shape:
+          $ref: '#/components/schemas/XyShapeQuery'
       minProperties: 1
       maxProperties: 1
     BoolQuery:
@@ -623,6 +623,8 @@ components:
         - $ref: '#/components/schemas/QueryBase'
         - type: object
           properties:
+            field:
+              $ref: '_common.yaml#/components/schemas/GeoBounds'
             type:
               $ref: '#/components/schemas/GeoExecution'
             validation_method:
@@ -667,13 +669,33 @@ components:
               $ref: '#/components/schemas/GeoValidationMethod'
             ignore_unmapped:
               $ref: '#/components/schemas/IgnoreUnmapped'
+    GeoShape:
+      type: object
+      properties:
+        type:
+          type: string
+        coordinates:
+          type: array
+    GeoShapeField:
+      type: object
+      properties:
+        shape:
+          $ref: '#/components/schemas/GeoShape'
+        relation: 
+          $ref: '_common.yaml#/components/schemas/GeoShapeRelation'
+      required:
+        - shape
     GeoShapeQuery:
       allOf:
         - $ref: '#/components/schemas/QueryBase'
         - type: object
           properties:
+            field:
+              $ref: '#/components/schemas/GeoShapeField'
             ignore_unmapped:
               $ref: '#/components/schemas/IgnoreUnmapped'
+          required:
+            - field
     HasChildQuery:
       allOf:
         - $ref: '#/components/schemas/QueryBase'
@@ -1626,13 +1648,6 @@ components:
           required:
             - query
             - script
-    ShapeQuery:
-      allOf:
-        - $ref: '#/components/schemas/QueryBase'
-        - type: object
-          properties:
-            ignore_unmapped:
-              $ref: '#/components/schemas/IgnoreUnmapped'
     SimpleQueryStringQuery:
       allOf:
         - $ref: '#/components/schemas/QueryBase'
@@ -1918,6 +1933,15 @@ components:
         only_score_pruned_tokens:
           description: Whether to only score pruned tokens, vs only scoring kept tokens.
           type: boolean
+    TypeQuery:
+      allOf:
+        - $ref: '#/components/schemas/QueryBase'
+        - type: object
+          properties:
+            value:
+              type: string
+          required:
+            - value      
     WeightedTokensQuery:
       allOf:
         - $ref: '#/components/schemas/QueryBase'
@@ -1960,12 +1984,29 @@ components:
               type: string
           required:
             - query
-    TypeQuery:
+    XyShape:
+      type: object
+      properties:
+        type:
+          type: string
+        coordinates:
+          type: array
+    XyShapeField:
+      type: object
+      properties:
+        shape:
+          $ref: '#/components/schemas/XyShape'
+        relation: 
+          $ref: '_common.yaml#/components/schemas/GeoShapeRelation'
+      required:
+        - shape
+    XyShapeQuery:
+      x-version-added: 2.4
       allOf:
         - $ref: '#/components/schemas/QueryBase'
         - type: object
           properties:
-            value:
-              type: string
+            field:
+              $ref: '#/components/schemas/XyShapeField'
           required:
-            - value
+            - field

spec/schemas/_common.yaml

@@ -133,6 +133,32 @@ components:
           type: string
       required:
         - wkt
+    XyLocation:
+      x-version-added: 2.4
+      description: |-
+        A two-dimensional Cartesian point specified by x and y coordinates. It can be represented in various ways:
+        - as a `{x, y}` object
+        - as a `[x, y]` array
+        - as a string in `"x, y"` or WKT point formats.
+      oneOf:
+        - $ref: '#/components/schemas/XyCartesianCoordinates'
+        - type: array
+          items:
+            type: number
+        - type: string
+    XyCartesianCoordinates:
+      x-version-added: 2.4
+      type: object
+      properties:
+        x:
+          description: The x coordinate
+          type: number
+        y:
+          description: The y coordinate
+          type: number
+      required:
+        - x
+        - y
     EpochTimeUnitMillis:
       allOf:
         - $ref: '#/components/schemas/UnitMillis'

tests/default/_core/search/geo_bounding_box.yaml

@@ -0,0 +1,61 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test search endpoint with geo_bounding_box query.
+prologues:
+  - path: /point_index
+    method: PUT
+    request:
+      payload:
+        mappings:
+          properties:
+            field:
+              type: geo_point
+  - path: /point_index/_doc/1
+    method: POST
+    parameters:
+      refresh: true
+    request:
+      payload:
+        field:
+          lat: 74
+          lon: 40
+    status: [201]
+epilogues:
+  - path: /point_index
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Search point_index for documents whose point objects are within the specified bounding box.
+    path: /{index}/_search
+    parameters:
+      index: point_index
+    method: GET
+    request:
+      payload:
+        query:
+          geo_bounding_box:
+            field:
+              top: 75
+              left: 28
+              bottom: 73
+              right: 41
+            validation_method: strict
+            type: memory
+            ignore_unmapped: false
+            _name: my_query  
+    response:
+      status: 200
+      payload:
+        timed_out: false
+        hits:
+          total:
+            value: 1
+            relation: eq
+          max_score: 1
+          hits:
+            - _index: point_index
+              _score: 1
+              _source:
+                field:
+                  lat: 74
+                  lon: 40