diff --git a/CHANGELOG.md b/CHANGELOG.md index 541a4d3..ee32b9a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## Unreleased + +### Added + +- Added Collection Search conformance class + ## [v1.0.0-rc.4] - 2025-02-27 ### Changed diff --git a/README.md b/README.md index b29daca..2411b65 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,7 @@ - Filter: `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter` - Features Filter: `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter` - Item Search Filter: `https://api.stacspec.org/v1.0.0/item-search#filter` + - Collection Search Filter: `https://api.stacspec.org/v1.0.0/collection-search#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` @@ -78,14 +79,16 @@ - Property-Property Comparisons: `http://www.opengis.net/spec/cql2/1.0/conf/property-property` - Functions: `http://www.opengis.net/spec/cql2/1.0/conf/functions` - Arithmetic Expressions: `http://www.opengis.net/spec/cql2/1.0/conf/arithmetic` -- **Scope:** STAC API - Features, STAC API - Item Search +- **Scope:** STAC API - Features, STAC API - Item Search, STAC API - Collection Search - **[Extension Maturity Classification](https://github.com/radiantearth/stac-api-spec/tree/main/README.md#maturity-classification):** Candidate - **Dependencies:** - - [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search) - [STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features) + - [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search) + - [STAC API - Collection Search](https://github.com/stac-api-extensions/collection-search) - **Owner**: @philvarner -The Filter extension provides an expressive mechanism for searching based on Item attributes. +The Filter extension provides an expressive mechanism for searching based on Item and Collection attributes, +depending on the conformance class implemented. This extension references behavior defined in the [OGC API - Features - Part 3: Filtering Version 1.0](https://docs.ogc.org/is/19-079r2/19-079r2.html) @@ -112,7 +115,7 @@ Cassandra database, or the OASIS Contextual Query Language. ## Limitations of Item Search -OAFeat defines a limited set of filtering capabilities. Filtering can only be done over a single collection and +OAFeat defines a limited set of filtering capabilities for Items. For Items, filtering can only be done over a single collection and with only a single `bbox` (rectangular spatial filter) parameter and a single datetime (instant or interval) parameter. The STAC Item Search specification extends the functionality of OAFeat in a few key ways: @@ -128,7 +131,7 @@ multiple spatial or temporal filters. ## Filter Expressiveness -This extension expands the capabilities of Item Search and the OAFeat Items resource with +This extension expands the capabilities of Item Search, Collection Search and the OAFeat Items resource with [Common Query Language (CQL2)](https://docs.ogc.org/is/21-065r2/21-065r2.html) by providing an expressive query language to construct more complex filter predicates using operators that are similar to those provided by SQL. This extension also supports the Queryables mechanism that allows discovery of what Item fields can be used in @@ -142,6 +145,9 @@ CQL2 enables more expressive queries than supported by STAC API Item Search. The - Items whose `geometry` values intersect one Polygon, but do not intersect another one, using AND, NOT, and S_INTERSECTS +For Collection Search, no filtering capabilities are present by default. As such this extension formally allows to formulate +filters for Collections in an expressive way. + ## Conformance Classes The OAFeat Part 3 - Filter and CQL2 specifications define several conformance classes that allow implementers @@ -156,7 +162,10 @@ Basic Spatial Functions with additional Spatial Literals class. 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/item-search#filter`) to bind -the Filter behavior to the Item Search endpoint. +the Filter behavior to the Item Search endpoint +and the *Collection Search Filter* conformance class +(`https://api.stacspec.org/v1.0.0/collection-search#filter`) to bind +the Filter behavior to the Collection endpoint. The implementation **must** support these conformance classes: @@ -166,15 +175,17 @@ 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/item-search#filter`) binds the Filter and +- For Item Search only : Item Search Filter (`https://api.stacspec.org/v1.0.0/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`). +- For Collection Search only: Collection Search Filter (`https://api.stacspec.org/v1.0.0/collection-search#filter`) binds the Filter and + Basic CQL2 conformance classes to apply to the Collection endpoint (`/collection`). The implementation **must** support at least one of the "CQL2 Text" or "CQL2 JSON" conformance classes that define the CQL2 format used in the filter parameter: -- CQL2 Text (`http://www.opengis.net/spec/cql2/1.0/conf/cql2-text`) defines that the CQL2 Text format is supported by Item Search -- CQL2 JSON (`http://www.opengis.net/spec/cql2/1.0/conf/cql2-json`) defines that the CQL2 JSON format is supported by Item Search +- 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`) If both are advertised as being supported, it is only required that both be supported for GET query parameters, and that only that CQL2 JSON be supported for POST JSON requests. It is recommended that clients use CQL2 Text in GET requests and