Merge pull request #20 from stac-api-extensions/pv/fix-openapi-model-composition

fix openapi model composition

Author: Phil Varner

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Fixed several issues with OpenAPI specification
 - Basic Spatial Operators in CQL2 now only requires BBOX and POINT support, so the text
   and examples were updated to account for this.
 

openapi.yaml

@@ -11,17 +11,19 @@ tags:
     description: Part of STAC API - Collections definition
   - name: Features
     description: Part of STAC API - Features definition
+  - name: Item Search 
+    description: Part of STAC API - Item Search definition
   - name: Filter Extension
     description: Part of STAC API - Filter extension definition
 
 paths:
-  '/':
+  "/":
     get:
       description: Landing Page
       tags:
         - Core
       responses:
-        '200':
+        "200":
           description: Landing Page
           links:
             queryables:
@@ -40,10 +42,10 @@ paths:
       tags:
         - Filter Extension
       responses:
-        '200':
-          $ref: '#/components/responses/Queryables'
+        "200":
+          $ref: "#/components/responses/Queryables"
         default:
-          $ref: '#/components/responses/Error'
+          $ref: "#/components/responses/Error"
   /collections/{collectionId}:
     get:
       description: |-
@@ -59,13 +61,48 @@ paths:
           required: true
           description: ID of Collection
       responses:
-        '200':
+        "200":
           description: Collection description
           links:
             queryables:
               operationId: getQueryablesForCollection
               description: |-
                 A link with rel=queryables for queryables to only apply to this collection.
+  /collections/{collectionId}/items:
+    get:
+      tags:
+        - Features
+        - Filter Extension
+      summary: fetch features
+      description: |-
+        Fetch features of the feature collection with id `collectionId`.
+
+        Every feature in a dataset belongs to a collection. A dataset may
+        consist of multiple feature collections. A feature collection is often a
+        collection of features of a similar type, based on a common schema.
+      operationId: getFeatures
+      parameters:
+        - in: path
+          name: collectionId
+          schema:
+            type: string
+          required: true
+          description: ID of Collection
+        - $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/limit"
+        - $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/bbox"
+        - $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/datetime"
+        - $ref: "#/components/parameters/filter"
+        - $ref: "#/components/parameters/filter-lang"
+        - $ref: "#/components/parameters/filter-crs"
+      responses:
+        "200":
+          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/Features"
+        "404":
+          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/NotFound"
+        "4XX":
+          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/Error"
+        "5XX":
+          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/Error"
   /collections/{collectionId}/queryables:
     get:
       summary: Get the JSON Schema defining the list of variable terms that can be used in CQL2 expressions.
@@ -84,10 +121,74 @@ paths:
       tags:
         - Filter Extension
       responses:
-        '200':
-          $ref: '#/components/responses/Queryables'
+        "200":
+          $ref: "#/components/responses/Queryables"
         default:
-          $ref: '#/components/responses/Error'
+          $ref: "#/components/responses/Error"
+  /search:
+    get:
+      summary: Search STAC items with full-featured filtering.
+      operationId: getItemSearch
+      description: |-
+        Retrieve Items matching filters. Intended as a shorthand API for simple
+        queries.
+        This method is required to implement.
+        If this endpoint is implemented on a server, it is required to add a
+        link referring to this endpoint with `rel` set to `search` to the
+        `links` array in `GET /`. As `GET` is the default method, the `method`
+        may not be set explicitly in the link.
+      tags:
+        - Item Search
+        - Filter Extension
+      parameters:
+        - $ref: "#/components/parameters/filter"
+        - $ref: "#/components/parameters/filter-lang"
+        - $ref: "#/components/parameters/filter-crs"
+      responses:
+        "200":
+          description: A feature collection.
+          content:
+            application/geo+json:
+              schema:
+                $ref: "https://api.stacspec.org/v1.0.0/item-search/openapi.yaml#/components/schemas/itemCollection"
+            text/html:
+              schema:
+                type: string
+        "4XX":
+          $ref: "#/components/responses/Error"
+        "5XX":
+          $ref: "#/components/responses/Error"
+    post:
+      summary: Search STAC items with full-featured filtering.
+      operationId: postItemSearch
+      description: |-
+        Retrieve items matching filters. Intended as the standard, full-featured
+        query API.
+        If this endpoint is implemented on a server, it is required to add a
+        link referring to this endpoint with `rel` set to `search` and `method`
+        set to `POST` to the `links` array in `GET /`.
+      tags:
+        - Item Search
+        - Filter Extension
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/searchBody"
+      responses:
+        "200":
+          description: A feature collection.
+          content:
+            application/geo+json:
+              schema:
+                $ref: "https://api.stacspec.org/v1.0.0/item-search/openapi.yaml#/components/schemas/itemCollection"
+            text/html:
+              schema:
+                type: string
+        "4XX":
+          $ref: "#/components/responses/Error"
+        "5XX":
+          $ref: "#/components/responses/Error"
 components:
   parameters:
     filter:
@@ -101,8 +202,8 @@ components:
       required: true
       schema:
         oneOf:
-          - $ref: '#/components/schemas/filter-cql2-json'
-          - $ref: '#/components/schemas/filter-cql2-text'
+          - $ref: "#/components/schemas/filter-cql2-json"
+          - $ref: "#/components/schemas/filter-cql2-text"
     filter-lang:
       name: filter-lang
       x-stac-api-fragment: filter
@@ -113,7 +214,7 @@ components:
         The CQL2 filter encoding that the 'filter' value uses. Must be one of 'cql2-text' or 'cql2-json'.
       required: false
       schema:
-        $ref: '#/components/schemas/filter-lang'
+        $ref: "#/components/schemas/filter-lang"
     filter-crs:
       name: filter-crs
       x-stac-api-fragment: filter
@@ -125,7 +226,7 @@ components:
         is 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'.
       required: false
       schema:
-        $ref: '#/components/schemas/filter-crs'
+        $ref: "#/components/schemas/filter-crs"
   schemas:
     searchBody:
       type: object
@@ -134,26 +235,28 @@ components:
         **Extension:** Filter
 
         A filter for properties in Items.
+      allOf: # Combines the searchBody of Item-filter and the inline model
+        - $ref: "https://api.stacspec.org/v1.0.0/item-search/openapi.yaml#/components/schemas/searchBody"
       properties:
         filter:
-          $ref: '#/components/schemas/filter-cql2-json'
+          $ref: "#/components/schemas/filter-cql2-json"
         filter-lang:
-          $ref: '#/components/schemas/filter-lang'
+          $ref: "#/components/schemas/filter-lang"
         filter-crs:
-          $ref: '#/components/schemas/filter-crs'
+          $ref: "#/components/schemas/filter-crs"
     filter-cql2-text:
       description: |
         A CQL2 filter expression in the 'cql2-text' encoding.
       type: string
     filter-cql2-json:
-      $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/cql2/standard/schema/cql2.yml#/components/schemas/booleanExpression'
+      $ref: "https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/cql2/standard/schema/cql2.yml#/components/schemas/booleanExpression"
     filter-lang:
       description: |
         The CQL2 filter encoding that the 'filter' value uses.
       type: string
       enum:
-        - 'cql2-text'
-        - 'cql2-json'
+        - "cql2-text"
+        - "cql2-json"
     filter-crs:
       description: |
         The coordinate reference system (CRS) used by spatial literals in the 'filter' value.  The only value that STAC APIs must
@@ -183,4 +286,4 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/exception'
+            $ref: "#/components/schemas/exception"