From 87ba737ca39b8d20560219319c2266c3b8aadf87 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Sun, 6 Mar 2022 08:36:58 -0500 Subject: [PATCH] fix uri for filter extension to remove item-search-filter --- CHANGELOG.md | 4 +++- extensions.md | 25 +++++++++++++------------ fragments/filter/README.md | 23 ++++++++++++++--------- fragments/filter/openapi.yaml | 18 +++++++++--------- item-search/README.md | 2 +- ogcapi-features/README.md | 10 ++++++---- 6 files changed, 46 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fb504e6..24808c9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Query Extension is no longer deprecated. - Children conformance class now requires the /children endpoint includes all child catalogs or collections referenced via `child` link relations from the Landing Page - +- 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 index 43c6030a..e7204ea8 100644 --- 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, - - - [Filter](item-search/README.md#filter-extension) - - - - - - + - + - + - - - + - - - - diff --git a/fragments/filter/README.md b/fragments/filter/README.md index 7ef6a3ab..b8a508a3 100644 --- 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: - Filter: - - Item Search Filter: + - Features Filter: - CQL2 Text: - CQL2 JSON: - 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 index 3d27caf8..4c17ae92 100644 --- a/fragments/filter/openapi.yaml +++ b/fragments/filter/openapi.yaml @@ -103,8 +103,8 @@ 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 @@ -112,7 +112,7 @@ components: 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 index b00f4247..a0fb12b4 100644 --- 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 index 0250a924..44cb176d 100644 --- 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:** +- **Conformance URI:** - **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