Merge pull request #279 from philvarner/pv/filter-extension-conformance-class-consistency

philvarner · web-flow · commit b6f1ef30a8c5 · 2022-03-06T15:36:50.000-05:00
Pv/filter extension conformance class consistency
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Children conformance class now requires the /children endpoint includes all child catalogs or collections
   referenced via `child` link relations from the Landing Page
 - Specifications now use the term "must" instead of "shall". The semantics of these words are identical.
+- Conformance class for Item Search Filter is now
+  `https://api.stacspec.org/v1.0.0-beta.5/item-search#filter`, whereas before it was incorrectly stated as
+  `https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter`
 ### Deprecated
 
 ### Removed
diff --git a/extensions.md b/extensions.md
@@ -30,15 +30,15 @@ are scoped against ogcapi-features*.
 
 This is the list of all extensions that are contained in the stac-api-spec repository.
 
-| Extension Name                                                                    | Scope*                                                                                                     | Description                                                                                                                                 | Maturity                              |
-| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| [Fields](item-search/README.md#fields-extension)                                            | [Item Search](item-search/) request                                                                        | Adds parameter to control which fields are returned in the response.                                                                        | *Pilot*                               |
-| [Filter](item-search/README.md#filter-extension)                                            | [Item Search](item-search/) and [STAC API - Features](ogcapi-features) `/items` requests                   | Adds parameter to search Item and Collection properties.                                                                                    | *Pilot*                               |
-| [Context](item-search/README.md#context-extension)                                          | [Item Search](item-search/) response ([ItemCollection](fragments/itemcollection/README.md))                | Adds search related metadata (context) to ItemCollection.                                                                                   | *Proposal*                            |
-| [Sort](item-search/README.md#sort-extension)                                                | [Item Search](item-search/) request                                                                        | Adds Parameter to control sorting of returns results.                                                                                       | *Pilot*                               |
-| [Transaction](ogcapi-features/extensions/transaction/README.md)                   | [STAC API - Features](ogcapi-features) POST on `/items` endpoint, DELETE/PUT on `/items/{itemId}` endpoint | Adds PUT and DELETE endpoints for the creation, editing, and deleting of Item objects.                                                      | *Pilot*                               |
-| [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | [STAC API - Features](ogcapi-features) on `/items` endpoint                                                | Adds GET versions resource to Collection and Item endpoints and provides semantics for a versioning scheme for Collection and Item objects. | *Proposal*                            |
-| [Query](item-search/README.md#query-extension)                                              | [Item Search](item-search/) request                                                                        | Adds parameter to search Item and Collection properties.                                                                                    | *Pilot* |
+| Extension Name                                                                    | Scope*                                                                                                     | Description                                                                                                                                 | Maturity   |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| [Fields](item-search/README.md#fields-extension)                                  | [Item Search](item-search/) request                                                                        | Adds parameter to control which fields are returned in the response.                                                                        | *Pilot*    |
+| [Filter](item-search/README.md#filter-extension)                                  | [Item Search](item-search/) and [STAC API - Features](ogcapi-features) `/items` requests                   | Adds parameter to search Item and Collection properties.                                                                                    | *Pilot*    |
+| [Context](item-search/README.md#context-extension)                                | [Item Search](item-search/) response ([ItemCollection](fragments/itemcollection/README.md))                | Adds search related metadata (context) to ItemCollection.                                                                                   | *Proposal* |
+| [Sort](item-search/README.md#sort-extension)                                      | [Item Search](item-search/) request                                                                        | Adds Parameter to control sorting of returns results.                                                                                       | *Pilot*    |
+| [Transaction](ogcapi-features/extensions/transaction/README.md)                   | [STAC API - Features](ogcapi-features) POST on `/items` endpoint, DELETE/PUT on `/items/{itemId}` endpoint | Adds PUT and DELETE endpoints for the creation, editing, and deleting of Item objects.                                                      | *Pilot*    |
+| [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | [STAC API - Features](ogcapi-features) on `/items` endpoint                                                | Adds GET versions resource to Collection and Item endpoints and provides semantics for a versioning scheme for Collection and Item objects. | *Proposal* |
+| [Query](item-search/README.md#query-extension)                                    | [Item Search](item-search/) request                                                                        | Adds parameter to search Item and Collection properties.                                                                                    | *Pilot*    |
 
 ### Conformance classes of extensions
 
@@ -49,11 +49,12 @@ the service supports. This are listed at the top of each extension description,
   - <https://api.stacspec.org/v1.0.0-beta.5/item-search#fields-extension>
   - <https://api.stacspec.org/v1.0.0-beta.5/ogcapi-features#fields-extension>
 - [Filter](item-search/README.md#filter-extension)
-  - <http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter-extension>
-  - <http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2>
-  - <https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter>
+  - <https://api.stacspec.org/v1.0.0-beta.5/item-search#filter>
+  - <http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter>
+  - <http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter>
   - <http://www.opengis.net/spec/cql2/1.0/conf/cql2-text>
   - <http://www.opengis.net/spec/cql2/1.0/conf/cql2-json>
+  - <http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2>
   - <http://www.opengis.net/spec/cql2/1.0/conf/advanced-comparison-operators>
   - <http://www.opengis.net/spec/cql2/1.0/conf/basic-spatial-operators>
   - <http://www.opengis.net/spec/cql2/1.0/conf/spatial-operators>
diff --git a/fragments/filter/README.md b/fragments/filter/README.md
@@ -2,8 +2,9 @@
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml)
 - **Conformance Classes:**
+  - Item Search Filter: <https://api.stacspec.org/v1.0.0-beta.5/item-search#filter>
   - Filter: <http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter>
-  - Item Search Filter: <https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter>
+  - Features Filter: <http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter>
   - CQL2 Text: <http://www.opengis.net/spec/cql2/1.0/conf/cql2-text>
   - CQL2 JSON: <http://www.opengis.net/spec/cql2/1.0/conf/cql2-json>
   - Basic CQL2: <http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2>
@@ -142,12 +143,10 @@ implementing functionality they do not need or may not be able to implement func
 their underlying datastore, e.g., Elasticsearch does not support the spatial predicates required by the
 Spatial Operators conformance class, only the `S_INTERSECTS` operator in the Basic Spatial Operators class.
 
-The precise decomposition of the OAFeat conformance classes is still a work in progress, but is being finalized
-rapidly (see [ogcapi-features/issues/579](https://github.com/opengeospatial/ogcapi-features/issues/579)).
 The STAC API Filter Extension reuses the definitions and conformance classes in OAFeat CQL,
-adding only the Item Search Filter conformance class
-(`https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter`) to bind
-the CQL2 Filter behavior to the Item Search resource.
+adding only the *Item Search Filter* conformance class
+(`https://api.stacspec.org/v1.0.0-beta.5/item-search#filter`) to bind
+the Filter behavior to the Item Search endpoint.
 
 The implementation **must** support these conformance classes:
 
@@ -157,7 +156,7 @@ The implementation **must** support these conformance classes:
   the query language used for the `filter` parameter defined by Filter. This includes logical operators (`AND`, `OR`, `NOT`),
   comparison operators (`=`, `<>`, `<`, `<=`, `>`, `>=`), and `IS NULL`. The comparison operators are allowed against
   string, numeric, boolean, date, and datetime types.
-- Item Search Filter (`https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter`) binds the Filter and
+- Item Search Filter (`https://api.stacspec.org/v1.0.0-beta.5/item-search#filter`) binds the Filter and
   Basic CQL2 conformance classes to apply to the Item Search endpoint (`/search`).  This class is the correlate of the OAFeat CQL2 Features
   Filter class that binds Filter and Basic CQL2 to the Features resource (`/collections/{cid}/items`).
 
@@ -171,7 +170,12 @@ If both are advertised as being supported, it is only required that both be supp
 only that CQL2 JSON be supported for POST JSON requests.  It is recommended that clients use CQL2 Text in GET requests and
 CQL2 JSON in POST requests.
 
-For additional capabilities, the following classes can be implemented:
+The implementation **may** support the OAFeat Part 3 *Features Filter* conformance classes:
+
+- Features Filter (`http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter`) binds the Filter and
+  CQL2 conformance classes to the Features resource(`/collections/{cid}/items`).
+
+For additional capabilities, the following classes may be implemented:
 - Advanced Comparison Operators
   (`http://www.opengis.net/spec/cql2/1.0/conf/advanced-comparison-operators`) defines the `LIKE`,
   `BETWEEN`, and `IN` operators. **Note**: this conformance class no longer requires implementing the
@@ -366,11 +370,12 @@ at least these values:
     "http://api.stacspec.org/v1.0.0-beta.5/stac-search",
     "http://api.stacspec.org/v1.0.0-beta.5/stac-response",
 
+    "https://api.stacspec.org/v1.0.0-beta.5/item-search#filter"
     "http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter",
     "http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter",
-    "http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2",
     "http://www.opengis.net/spec/cql2/1.0/conf/cql2-text",
     "http://www.opengis.net/spec/cql2/1.0/conf/cql2-json",
+    "http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2",
     "http://www.opengis.net/spec/cql2/1.0/conf/basic-spatial-operators",
     "http://www.opengis.net/spec/cql2/1.0/conf/advanced-comparison-operators"
 
diff --git a/fragments/filter/openapi.yaml b/fragments/filter/openapi.yaml
@@ -19,7 +19,7 @@ paths:
     get:
       description: Landing Page
       tags:
-        - STAC API - Core
+        - Core
       responses:
         '200':
           description: Landing Page
@@ -38,7 +38,7 @@ paths:
         precise definition of this can be found in the OGC API - Features - Part 3: Filtering and the 
         Common Query Language (CQL) specification.
       tags:
-        - STAC API - Filter Extension
+        - Filter Extension
       # parameters:
       # todo: may have collections parameter in the future
       responses:
@@ -84,7 +84,7 @@ paths:
           required: true
           description: ID of Collection
       tags:
-        - STAC API - Filter Extension
+        - Filter Extension
       responses:
         '200':
           $ref: '#/components/responses/Queryables'
@@ -103,16 +103,16 @@ components:
       required: true
       schema:
         oneOf:
-          - $ref: '#/components/schemas/filter-cql-json'
-          - $ref: '#/components/schemas/filter-cql-text'
+          - $ref: '#/components/schemas/filter-cql2-json'
+          - $ref: '#/components/schemas/filter-cql2-text'
     filter-lang:
       name: filter-lang
       x-stac-api-fragment: filter
       in: query
       description: |-
         **Extension:** Filter
 
-        The CQL2 filter encoding that the 'filter' value uses. Must be one of 'cql-text' or 'cql-json'.
+        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'
@@ -138,24 +138,24 @@ components:
         A filter for properties in Items.
       properties:
         filter:
-          $ref: '#/components/schemas/filter-cql-json'
+          $ref: '#/components/schemas/filter-cql2-json'
         filter-lang:
           $ref: '#/components/schemas/filter-lang'
         filter-crs:
           $ref: '#/components/schemas/filter-crs'
-    filter-cql-text:
+    filter-cql2-text:
       description: |
-        A CQL2 filter expression in the 'cql-text' encoding.
+        A CQL2 filter expression in the 'cql2-text' encoding.
       type: string
-    filter-cql-json:
+    filter-cql2-json:
       $ref: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/cql2/standard/schema/cql2.yml#/components/schemas/booleanValueExpression'
     filter-lang:
       description: |
         The CQL2 filter encoding that the 'filter' value uses.
       type: string
       enum:
-        - 'cql-text'
-        - 'cql-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
diff --git a/item-search/README.md b/item-search/README.md
@@ -343,7 +343,7 @@ The full description and examples of this are found in the [context fragment](..
 The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results
 by properties. The Filter extension adds a new parameter, `filter`, that can take a number of comparison operators to
 match predicates between the fields requested and the values of Item objects. It can be used with both GET and POST and supports two
-query formats, `cql-text` and `cql-json`. The full details on the JSON structure are specified in the [filter 
+query formats, `cql2-text` and `cql2-json`. The full details on the JSON structure are specified in the [filter 
 fragment](../fragments/filter/).
 
 ### Query Extension
diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md
@@ -393,14 +393,16 @@ The full description and examples of this are found in the [context fragment](..
 
 ### Filter Extension
 
-- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.5/item-search#filter>
+- **Conformance URI:** <http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter>
 - **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot
 - **Definition**: [STAC API - Filter Fragment](../fragments/filter/)
 
-The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results
+The Features items endpoint, `/collections/{collectionId}/items`, by default only accepts a few parameters to filter the results
 by properties. The Filter extension adds a new parameter, `filter`, that can take a number of comparison operators to
-match predicates between the fields requested and the values of Item objects. It can be used with both GET and POST and supports two
-query formats, `cql-text` and `cql-json`. The full details on the JSON structure are specified in the [filter 
+match predicates between the fields requested and the values of Item objects. It can only be
+used with GET requests, as a POST to the items endpoint is a create operation in the
+Transaction Extension. It supports two
+query formats, `cql2-text` and `cql2-json`. The full details on the JSON structure are specified in the [filter 
 fragment](../fragments/filter/).
 
 ### Query Extension
