diff --git a/CHANGELOG.md b/CHANGELOG.md index 39975cd2..c7216e02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,21 @@ 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] - TBD + +### Changed + +- Browseable specification has been incorporated into the *STAC API - Core* specification. +- Extensions moved to standalone specification repositories: + - [Items and Collections API Version](https://github.com/stac-api-extensions/version) + - [Fields](https://github.com/stac-api-extensions/fields) + - [Filter](https://github.com/stac-api-extensions/filter) + - [Context](https://github.com/stac-api-extensions/context) + - [Sort](https://github.com/stac-api-extensions/sort) + - [Transaction](https://github.com/stac-api-extensions/transaction) + - [Query](https://github.com/stac-api-extensions/query) + - [Children](https://github.com/stac-api-extensions/children) + ## [v1.0.0-rc.1] - 2022-03-17 ### Added diff --git a/README.md b/README.md index f5f43502..0ecb9f38 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ stac-logo -# STAC API +# STAC API Foundation Specifications -- [STAC API](#stac-api) +- [STAC API Foundation Specifications](#stac-api-foundation-specifications) - [Releases (stable)](#releases-stable) - [Development (unstable)](#development-unstable) - [About](#about) @@ -34,19 +34,23 @@ of the spec. ## About The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried. -A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and +A 'spatiotemporal asset' is any file that represents information about the Earth captured in a certain space and time. The core STAC specifications live in the GitHub repository [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec). -A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), +A STAC API is a dynamic version of a SpatioTemporal Asset Catalog. This repository defines the four +STAC API foundation specifications -- [STAC API - Core](core/), [STAC API - Collections](collections/), +[STAC API - Features](ogcapi-features/), and [STAC API - Item Search](item-search/) -- which can be composed +with [Extensions](extensions.md) to define a specific STAC API implementation. + +A STAC API can be used to retrieve STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), [Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md), -or a STAC API [ItemCollection](fragments/itemcollection/README.md), depending on the endpoint. +or STAC API [ItemCollection](fragments/itemcollection/README.md) objects from various endpoints. Catalog and Collection objects are JSON, while Item and ItemCollection objects are GeoJSON-compliant entities with foreign members. Typically, a Feature is used when returning a single Item object, and FeatureCollection when multiple Item objects (rather than a JSON array of Item entities). The API can be implemented in compliance with the *[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)* standard (OAFeat is a shorthand). In this case STAC API can be thought of as a specialized Features API - to search STAC catalogs, where the features returned are STAC [Item](stac-spec/item-spec/item-spec.md) objects, that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets. @@ -96,7 +100,7 @@ the specification takes place in the [issue tracker](https://github.com/radiante The **[Overview](overview.md)** document describes all the various parts of the STAC API and how they fit together. -**STAC API - Core Specification:** +**STAC API - Core:** The *[core](core/)* folder describes the core STAC API specification that enables browsing catalogs and retrieving the API capabilities. This includes the OpenAPI schemas for STAC Item, Catalog and Collection objects. @@ -112,14 +116,6 @@ each STAC collection. It also includes extensions that can be used to further en The *[item-search](item-search)* folder contains the Item Search specification, which enables cross-collection search of STAC Item objects at a `search` endpoint, as well as a number of extensions. -**STAC API - Children:** -The *[children](children)* folder describes how a STAC API Catalog can advertise the children (child catalogs or child collections) -it contains. - -**STAC API - Browseable:** -The *[browseable](browseable)* folder describes how a STAC API Catalog can advertise that all Items can be accessed -by following through `child` and `item` link relations. - **Extensions:** The *[extensions](extensions.md) document* describes how STAC incubates new functionality, and it links to the existing extensions that can be added to enrich the functionality of a STAC API. Each has an OpenAPI yaml, but some of the yaml diff --git a/browseable/README.md b/browseable/README.md deleted file mode 100644 index 94e5ba3c..00000000 --- a/browseable/README.md +++ /dev/null @@ -1,106 +0,0 @@ -# STAC API - Browseable Specification - -- [STAC API - Browseable Specification](#stac-api---browseable-specification) - - [Link Relations](#link-relations) - - [Endpoints](#endpoints) - - [Example Landing Page for STAC API - Browseable](#example-landing-page-for-stac-api---browseable) - - [Extensions](#extensions) - -- **OpenAPI specification:** none -- **Conformance URIs:** - - - - -- **[Maturity Classification](../README.md#maturity-classification):** Proposal -- **Dependencies**: [STAC API - Core](../core) - -A STAC API conforming to the *STAC API - Browseable* conformance class must be structured such that all -all Items in the catalog can be accessed by following `child` and `item` link relations. This is a more significant -constraint than a STAC API without this conformance class or a STAC Catalog that is available over HTTP but does not -implement STAC API, neither of which have any guarantee regarding the reachability of Items. This conformance -class is used to signal to users that they can fully navigate to all available Items using a UI (like [STAC Browser](https://github.com/radiantearth/stac-browser), -and also makes it clear to crawlers that they can reach everything by following catalog links. - -Recommendations for structuring Catalogs hierarchically can be found in -[Structuring Catalog Hierarchies](../core/README.md#structuring-catalog-hierarchies) from the *STAC API - Core* specification. - -## Link Relations - -This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. - -Additionally, `child` relations must exist to child Catalogs and Collections and `item` relations to Items, such that -every Item in the Catalog can be accessed by traversing these relations. - -| **rel** | **href** | **From** | **Description** | -| ------- | -------- | --------- | -------------------------------------- | -| `child` | various | STAC Core | The child STAC Catalogs & Collections. | -| `item` | various | STAC Core | The child STAC Items. | - -Note that there is a different link relation `items` (plural) -used by the *STAC API - Features* conformance class that links from a collection resource -(at the `/collections/{collectionId}` endpoint) to the items in -that collection (at the `/collections/{collectionId}/items` endpoint). Both of these endpoints are -[derived from OGC API - Features](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_). - -## Endpoints - -This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented. - -This conformance class adds no additional endpoints. - -## Example Landing Page for STAC API - Browseable - -This JSON is what would be expected from an API that implements *STAC API - Browseable*. Note that the -`conformsTo` array contains `https://api.stacspec.org/v1.0.0-rc.1/browseable` and the `links` array -contains `child` link relations. The semantics of this conformance class imply that the the catalogs -linked to by these `child` link relations then have further `child` or `item` link relations that -eventually reach all items in this catalog. - -```json -{ - "stac_version": "1.0.0", - "id": "example-stac", - "title": "A simple STAC API Example, implementing STAC API - Browseable", - "description": "This Catalog aims to demonstrate the a simple landing page", - "type": "Catalog", - "conformsTo" : [ - "https://api.stacspec.org/v1.0.0-rc.1/core", - "https://api.stacspec.org/v1.0.0-rc.1/browseable" - ], - "links": [ - { - "rel": "self", - "type": "application/json", - "href": "https://stac-api.example.com" - }, - { - "rel": "root", - "type": "application/json", - "href": "https://stac-api.example.com" - }, - { - "rel": "service-desc", - "type": "application/vnd.oai.openapi+json;version=3.0", - "href": "https://stac-api.example.com/api" - }, - { - "rel": "service-doc", - "type": "text/html", - "href": "https://stac-api.example.com/api.html" - }, - { - "rel": "child", - "type": "application/json", - "href": "https://stac-api.example.com/catalogs/sentinel-2", - }, - { - "rel": "child", - "type": "application/json", - "href": "https://stac-api.example.com/catalogs/landsat-8", - } - ] -} -``` - -## Extensions - -None. diff --git a/build/index.html b/build/index.html index b721406b..67b2a9ce 100644 --- a/build/index.html +++ b/build/index.html @@ -17,8 +17,6 @@

Conformance Classes

  • STAC API - Item Search
  • STAC API - Features
  • STAC API - Collections
    • -
  • STAC API - Children
    • -
  • STAC API - Browseable
    • diff --git a/core/README.md b/core/README.md index 09b3ea6b..41b721a3 100644 --- a/core/README.md +++ b/core/README.md @@ -10,13 +10,17 @@ - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.1/core)), - **Conformance URIs:** - + - - **[Maturity Classification](../README.md#maturity-classification):** Candidate - **Dependencies**: None and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. -All STAC API implementations must support the *STAC API - Core* conformance class. The only requirement of this class -is to provide a valid [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) that also includes a `conformsTo` -attribute with a string array value. Any API implementing this is considered a valid STAC API. +All STAC API implementations must implement the *STAC API - Core* specification. The conformance class + requires a server to provide a valid +[STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) that also includes a `conformsTo` +attribute with a string array value. Any API implementing this is considered a valid STAC API. Additionally, +a STAC API conforming conformance class () must be structured +such that all Items in the catalog can be accessed by following `child` and `item` link relations. Even if a STAC catalog is simply files on a web server or objects in cloud storage, serving these files over HTTP makes it into a defacto hypermedia-driven web API. Even if none of the @@ -27,7 +31,7 @@ this "browse" mode of interaction is complementary to the dynamic search capabil Conversely, STAC API implementations may not support browse, even though the root is a Catalog object, if they do not have the appropriate `child` and `item` link relations to traverse over the objects in the catalog. STAC API implementations may provide an even greater guarantee of Item reachability with the -[STAC API - Browseable](../browseable/README.md) conformance class. +browseable conformance class (). Providing these two complementary ways of interacting with the catalog allow users to iteratively interrogate the data to discover what data is available through browse and filter the data to only what they are interested in @@ -69,7 +73,18 @@ The scope of the conformance classes declared in the `conformsTo` field and the to the STAC API Catalog that declares them. A STAC API Catalog may link to sub-catalogs within it via `child` links that declare different conformance classes. This is useful when an entire catalog cannot be searched against to support the *STAC API - Item Search* conformance class, perhaps because it uses multiple databases to store items, -but sub-catalogs whose items are all in one database can support search. +but sub-catalogs whose items are all in one database can support search. + +A STAC API conforming to the *STAC API - Browseable* conformance class +() must be structured such that +all Items in the catalog can be accessed by following `child` and `item` link relations. This is a more significant +constraint than a STAC API without this conformance class or a STAC Catalog that is available over HTTP but does not +implement STAC API, neither of which have any guarantee regarding the reachability of Items. This conformance +class is used to signal to users that they can fully navigate to all available Items using a UI (like [STAC Browser](https://github.com/radiantearth/stac-browser), +and also makes it clear to crawlers that they can reach everything by following catalog links. + +Recommendations for structuring Catalogs hierarchically can be found in +[Structuring Catalog Hierarchies](../core/README.md#structuring-catalog-hierarchies) from the *STAC API - Core* specification. ## Link Relations @@ -96,7 +111,10 @@ supported by this endpoint, e.g., `text/html`. | `service-doc` | `/api.html` | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. | Additionally, `child` relations may exist to child Catalogs and Collections and `item` relations to Items. These -relations form a directed graph that enables traversal from a root catalog or collection to items. +relations form a directed graph that enables traversal from a root catalog or collection to items. + +If all Items in a Catalog can be accessed by traversing these links, the browseable conformance class + should be advertised also. | **rel** | **href** | **From** | **Description** | | ------- | -------- | --------- | -------------------------------------- | @@ -214,7 +232,7 @@ None. A STAC API is more useful when it presents a complete `Catalog` representation of all the data contained in the API, such that all `Item` objects can be reached by transitively traversing `child` and `item` link relations from the root. This property of being able to reach all Items in this way is formalized in the -[*STAC API - Browseable* conformance class](../browseable/README.md), but any Catalog can be structured for hierarchical traversal. +Browseable conformance class, but any Catalog can be structured for hierarchical traversal. Implementers who have search as their primary use case should consider also implementing this alternate view over the data by presenting it as a directed graph of catalogs, where the `child` link relations typically form a tree, and where each catalog can be retrieved with a single request (e.g., each Catalog JSON is small enough that diff --git a/extensions.md b/extensions.md index 7d7eef70..d2d5eb8b 100644 --- a/extensions.md +++ b/extensions.md @@ -12,72 +12,33 @@ For now anyone from the community is welcome to use the appropriate parts of the All extensions must include a [maturity classification](README.md#maturity-classification), so that STAC API specification users can easily get a sense of how much they can count on the extension. -## Extensions, Fragments, and Conformance - -Each extension has its own conformance class, which is specified with a 'conformance URI' that is defined for the extension, and listed in -the table below. These must be listed in the `conformsTo` JSON of the landing page, as specified by [STAC API Core](core/), to let clients -know that they can utilize the functionality. - -Each extension is defined to work against only one of the main API spec's conformance classes. A number of extensions define functionality -that could be used easily in a number of endpoints, such as additional parameters for search. For this repository we put those in the -[fragments](fragments/) directory. The main definition of the functionality lives there, but a fragment does not define a conformance class. -Only extensions have conformance classes, as they define the functionality along with the scope - where it is used. - -**NOTE**: *Currently the fragments are only used in item-search, but in the next release we will define extensions for all the fragments that -are scoped against ogcapi-features*. - -## List of Extensions - -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. | Candidate | -| [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. | Candidate | -| [Sort](item-search/README.md#sort-extension) | [Item Search](item-search/) request | Adds Parameter to control sorting of returns results. | Candidate | -| [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. | Candidate | -| [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. | Candidate | - -### Conformance classes of extensions - -Each extension has its own conformance URI, which is used in the `conformsTo` response of the landing page to let clients know what capabilities -the service supports. This are listed at the top of each extension description, but the full table is given here for ease of reference. - -- [Fields](item-search/README.md#fields-extension) - - - - -- [Filter](item-search/README.md#filter-extension) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- [Context](item-search/README.md#context-extension) - - - - -- [Sort](item-search/README.md#sort-extension) - - - - -- [Transaction](ogcapi-features/extensions/transaction/README.md) - - -- [Items and Collections API Version](ogcapi-features/extensions/version/README.md) - - -- [Query](item-search/README.md#query-extension) - - - -## Third-party / vendor extensions +## Extensions and Conformance + +Each extension has its own conformance class, which is specified with one or more **conformance URIs** +that are defined for the extension. These must be listed in the `conformsTo` JSON of the Landing Page, +as specified by [STAC API - Core](core/), to let clients know that they can use the functionality. + +A number of extensions define functionality that could be used easily in a number of endpoints, such +as additional parameters for search through either **STAC API - Item Search** or **STAC API - Features**. + +## Official Extensions + +This is the list of all official extensions that are contained in the +[stac-api-extensions](https://github.com/stac-api-extensions) GitHub organization. + +| Extension Name | Scope* | Description | Maturity | +| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | +| [Fields](https://github.com/stac-api-extensions/fields/blob/main/README.md) | [STAC API - Item Search](item-search/) request | Adds parameter to control which fields are returned in the response. | Candidate | +| [Filter](https://github.com/stac-api-extensions/filter/blob/main/README.md) | [STAC API - Item Search](item-search/) and [STAC API - Features](ogcapi-features) `/items` requests | Adds parameter to search Item and Collection properties. | Pilot | +| [Context](https://github.com/stac-api-extensions/context/blob/main/README.md) | [STAC API - Item Search](item-search/) response ([ItemCollection](fragments/itemcollection/README.md)) | Adds search related metadata (context) to ItemCollection. | Candidate | +| [Sort](https://github.com/stac-api-extensions/sort/blob/main/README.md) | [STAC API - Item Search](item-search/) request | Adds Parameter to control sorting of returns results. | Candidate | +| [Transaction](https://github.com/stac-api-extensions/transaction/blob/main/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. | Candidate | +| [Items and Collections API Version](https://github.com/stac-api-extensions/version/blob/main/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](https://github.com/stac-api-extensions/query/blob/main/README.md) | [STAC API - Item Search](item-search/) request | Adds parameter to search Item and Collection properties. | Candidate | +| [Children](https://github.com/stac-api-extensions/children/blob/main/README.md) | [STAC API - Core](core/) | Defines advertisement of the children (child catalogs or child collections) | +| a catalog contains. | Proposal | + +## Vendor Extensions The following extensions are provided by third parties (vendors). They tackle very specific use-cases and may be less stable than the official extensions. Once stable and adopted by multiple @@ -85,10 +46,10 @@ parties, extensions may be made official and incorporated in the STAC repository Please contact a STAC maintainer or open a Pull Request to add your extension to this table. -| Name | Scope | Description | Vendor | -| -------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | -| [Free-text Search](https://github.com/cedadev/stac-freetext-search) | [Item Search](item-search/) request | Adds `q` parameter and free-text search against item properties | [CEDA, STFC, UKRI](https://github.com/cedadev) | -| [Context Collections](https://github.com/cedadev/stac-context-collections) | [Item Search](item-search/) request | Adds a `collections` keyword to the [context](https://github.com/radiantearth/stac-api-spec/tree/main/fragments/context) extension response. | [CEDA, STFC, UKRI](https://github.com/cedadev) | +| Name | Scope | Description | Vendor | +| -------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| [Free-text Search](https://github.com/cedadev/stac-freetext-search) | [STAC API - Item Search](item-search/) request | Adds `q` parameter and free-text search against item properties | [CEDA, STFC, UKRI](https://github.com/cedadev) | +| [Context Collections](https://github.com/cedadev/stac-context-collections) | [STAC API - Item Search](item-search/) request | Adds a `collections` keyword to the [context](https://github.com/radiantearth/stac-api-spec/tree/main/fragments/context) extension response. | [CEDA, STFC, UKRI](https://github.com/cedadev) | ## Creating new extensions @@ -98,6 +59,6 @@ a service has the indicated functionality. It is also recommended to note the 'e so others can know how widely it is used. The new extension can live anywhere online, with a recommendation of using a GitHub repository to be able to track changes. -The first step in sharing the extension is to add it to the third-party / vendor extension table above. If it is of something +The first step in sharing the extension is to add it to the vendor extension table above. If it is of something that the wider community may be interested in then it should be added to the appropriate folder in the main repo as a pull request. diff --git a/fragments/README.md b/fragments/README.md deleted file mode 100644 index a0b4549a..00000000 --- a/fragments/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# STAC API - Fragments - -This directory contains reusable OpenAPI fragments that are used by other capabilities. They tend to -be common API components such as parameters that get mixed in to various endpoints. -They are kept in this separate fragment directory as they are not specific to any extension and are meant -to be re-used when drafting new API extensions. - -For example '[sort](sort/)' introduces a parameter (`sortby`) that can be used by both [item-search](../item-search) -at the `/search` endpoint, and by [features](../ogcapi-features) in any of its `items` endpoints. To keep -things clean we specify a conformance class for each, so clients can know exactly what to expect. Each -conformance class is specified in the relevant folder as an 'extension' to the main capability. But their -semantics are exactly the same, so we put the shared openapi definition in this `fragments` directory. - -| Fragment Name | Description | -| ------------------------------------------ | -------------------------------------------------------------------------- | -| [Context](context/README.md) | Adds search related metadata (context) to GeoJSON Responses. | -| [Fields](fields/README.md) | Adds parameter to control which fields are returned in the response. | -| [ItemCollection](itemcollection/README.md) | The specification for a set of items, e.g. returned by a search. | -| [Query](query/README.md) | Adds parameter to compare properties and only return the items that match. | -| [Sort](sort/README.md) | Adds Parameter to control sorting of returns results. | diff --git a/fragments/context/README.md b/fragments/context/README.md deleted file mode 100644 index 449315f0..00000000 --- a/fragments/context/README.md +++ /dev/null @@ -1,60 +0,0 @@ -# STAC API - Context Fragment - -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Classes:** - - Item Search binding: - - STAC Features binding: -- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Candidate -- **Dependents:** - - [Item Search](../../item-search) - -This extension is intended to augment the core [ItemCollection](../itemcollection/README.md) -object when the ItemCollection is the result of a search, for example, from calling the `/search` API endpoint. - -This fragment may be bound to either or both of -[Item Search](../../item-search) (`/search` endpoint) or -[STAC Features](../../ogcapi-features) (`/collections/{collectionId}/items` endpoint) by -advertising the relevant conformance class. - -**Note**: OGC API Features - Part 1 has its own way returning `numberMatched` and `numberReturned` at the top level, instead of in a context -object. We are hoping to [align](https://github.com/opengeospatial/ogcapi-common/issues/82), but until then, it -is required to implement both when implementing STAC Features. - -- [Example](examples/example.json) -- [JSON Schema](json-schema/schema.json) - -## ItemCollection fields - -| Element | Type | Description | -| --------- | --------------------------------- | ------------------------------------------------------------------------------------------------ | -| `context` | [Context Object](#context-object) | **REQUIRED.** The search-related metadata for the [ItemCollection](../itemcollection/README.md). | - -## Context Object - -| Element | Type | Description | -| -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| returned | integer | **REQUIRED** The count of results returned by this response. Equal to the cardinality of features array. | -| limit | integer \| null | The maximum number of results to which the result was limited. | -| matched | integer | The count of total number of results that match for this query, possibly estimated, particularly in the context of NoSQL data stores. | - -The default sort of query results should be stable, but may not be depending on the data store's sorting performance. -It is recommended that the [Sort API Extension](../sort/README.md) be implemented in conjunction with this extension -and that fields conducive to stable sorting have sorting enabled over them. - -**limit** - The maximum number of results requested explicitly, the default limit used by the service implementation -if no parameter was provided, or the maximum limit used by the service implementation if the limit parameter was larger. -`null` if no limit was placed on the query that retrieved these results, which should be a rare case in practice. - -## Example ItemCollection augmented with Context field - -```json -{ - "type": "FeatureCollection", - "features": [ ], - "context": { - "returned": 9, - "limit": 10, - "matched": 1092873 - } -} -``` diff --git a/fragments/context/examples/example.json b/fragments/context/examples/example.json deleted file mode 100644 index fcb6809f..00000000 --- a/fragments/context/examples/example.json +++ /dev/null @@ -1,55 +0,0 @@ -{ - "type": "FeatureCollection", - "context": { - "returned": 1, - "limit": 1, - "matched": 1092873 - }, - "features": [ - { - "stac_version": "1.0.0", - "stac_extensions": [], - "type": "Feature", - "id": "CS3-20160503_132131_05", - "bbox": [ - -122.59750209, - 37.48803556, - -122.2880486, - 37.613537207 - ], - "geometry": { - "type": "Polygon", - "coordinates": [ - [ - [ - -122.308150179, - 37.488035566 - ], - [ - -122.597502109, - 37.538869539 - ], - [ - -122.576687533, - 37.613537207 - ], - [ - -122.288048600, - 37.562818007 - ], - [ - -122.308150179, - 37.488035566 - ] - ] - ] - }, - "properties": { - "datetime": "2016-05-03T13:22:30.040Z" - }, - "collection": "CS3", - "links": [ ], - "assets": { } - } - ] -} \ No newline at end of file diff --git a/fragments/context/json-schema/schema.json b/fragments/context/json-schema/schema.json deleted file mode 100644 index f92061c1..00000000 --- a/fragments/context/json-schema/schema.json +++ /dev/null @@ -1,42 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "schema.json#", - "title": "Context Extension", - "type": "object", - "description": "STAC context metadata", - "allOf": [ - { - "$ref": "#/definitions/context" - } - ], - "definitions": { - "context": { - "type": "object", - "required": [ - "context" - ], - "properties": { - "context": { - "type": "object", - "required": [ - "returned" - ], - "properties": { - "returned": { - "type": "integer", - "minimum": 0 - }, - "limit": { - "type": ["integer", "null"], - "minimum": 0 - }, - "matched": { - "type": "integer", - "minimum": 0 - } - } - } - } - } - } -} diff --git a/fragments/context/openapi.yaml b/fragments/context/openapi.yaml deleted file mode 100644 index 025d6c76..00000000 --- a/fragments/context/openapi.yaml +++ /dev/null @@ -1,34 +0,0 @@ -openapi: 3.0.3 -info: - title: The SpatioTemporal Asset Catalog API - Context - description: Adds search related metadata (context) to GeoJSON Responses. - version: 1.0.0-rc.1 -paths: {} -components: - schemas: - itemCollection: - type: object - description: |- - **Extension:** Context - - Augments lists of resources with the number of returned and matches resource and the given limit for the request. - x-stac-api-fragment: context - properties: - 'context': - type: object - required: - - returned - properties: - returned: - type: integer - minimum: 0 - example: 1 - limit: - type: integer - nullable: true - minimum: 0 - example: 5 - matched: - type: integer - minimum: 0 - example: 314159 diff --git a/fragments/fields/README.md b/fragments/fields/README.md deleted file mode 100644 index a41b3abd..00000000 --- a/fragments/fields/README.md +++ /dev/null @@ -1,177 +0,0 @@ -# STAC API - Fields Fragment - -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Classes:** - - Item Search binding: - - STAC Features binding: -- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Candidate -- **Dependents:** - - [Item Search](../../item-search) - - [STAC Features](../../ogcapi-features) - -STAC API by default returns every attribute in an item. However, Item objects can have hundreds of fields, or incredibly large -geometries, and even smaller Item objects can get big when millions are requested but not all information is used. This -fragment provides a mechanism for clients to request that servers to explicitly include or exclude certain fields. - -This fragment may be bound to either or both of -[Item Search](../../item-search) (`/search` endpoint) or -[STAC Features](../../ogcapi-features) (`/collections/{collectionId}/items` endpoint) by -advertising the relevant conformance class. - -When used in a POST request with `Content-Type: application/json`, this adds an attribute `fields` with -an object value to the core JSON search request body. The `fields` object contains two attributes with string array -values, `include` and `exclude`. - -When used with GET or POST with `Content-Type: application/x-www-form-urlencoded` or -`Content-Type: multipart/form-data`, the semantics are the same, except the syntax is a single parameter `fields` with -a comma-separated list of attribute names, where `exclude` values are those prefixed by a `-` and `include` values are -those with no prefix, e.g., `-geometry`, or `id,-geometry,properties`. - -It is recommended that implementations provide exactly the `include` and `exclude` sets specified by the request, -but this is not required. These values are only hints to the server as to the desires of the client, and not a -contract about what the response will be. Implementations are still considered compliant if fields not specified as part of `include` -are in the response or ones specified as part of `exclude` are. For example, implementations may choose to always -include simple string fields like `id` and `type` regardless of the `exclude` specification. However, it is recommended -that implementations honor excludes for attributes with more complex and arbitrarily large values -(e.g., `geometry`, `assets`). For example, some Item objects may have a geometry with a simple 5 point polygon, but these -polygons can be very large when reprojected to EPSG:4326, as in the case of a highly-decimated sinusoidal polygons. -Implementations are also not required to implement semantics for nested values whereby one can include an object, but -exclude attributes of that object, e.g., include `properties` but exclude `properties.datetime`. - -No error must be returned if a specified field has no value for it in the catalog. For example, if the attribute -"properties.eo:cloud_cover" is specified but there is no cloud cover value for an Item or the API does not even -support the EO Extension, a successful HTTP response must be returned and the Item entities will not contain that -attribute. - -If no `fields` are specified, the response is **must** be a valid [ItemCollection](../itemcollection/README.md). If a client excludes -attributes that are required in a STAC Item, the server may return an invalid STAC Item. For example, if `type` -and `geometry` are excluded, the entity will not even be a valid GeoJSON Feature, or if `bbox` is excluded then the entity -will not be a valid STAC Item. - -Implementations may return attributes not specified, e.g., id, but must avoid anything other than a minimal entity -representation. - -## Include/Exclude Semantics - -1. If `fields` attribute is specified with an empty object, or with both `include` and `exclude` set to null or an -empty array, the recommended behavior is as if `include` was set to -`["id", "type", "geometry", "bbox", "links", "assets", "properties.datetime"]`. This default is so that the entity -returned is a valid STAC Item. Implementations may choose to add other properties, e.g., `created`, but the number -of default properties attributes should be kept to a minimum. -2. If only `include` is specified, these attributes are added to the default set of attributes (set union operation). -3. If only `exclude` is specified, these attributes are subtracted from the union of the default set of attributes and -the `include` attributes (set difference operation). This will result in an entity that is not a valid Item if any -of the excluded attributes are in the default set of attributes. -4. If both `include` and `exclude` attributes are specified, semantics are that a field must be included and **not** -excluded. E.g., if `properties` is included and `properties.datetime` is excluded, then `datetime` must not appear -in the attributes of `properties`. - -## Examples - -Return baseline fields. This **must** return valid STAC Item entities. - -Query Parameters -```http -?fields= -``` - -JSON -```json -{ - "fields": { - } -} -``` - -This has a similar effect as an empty object for `fields`, but it is up to the discretion of the implementation - -Query Parameters -```http -?fields=id,type,geometry,bbox,properties,links,assets -``` - -JSON -```json -{ - "fields": { - "include": [ - "id", - "type", - "geometry", - "bbox", - "properties", - "links", - "assets" - ] - } -} -``` - -Exclude `geometry` from the baseline fields. This **must** return an entity that is not a valid GeoJSON Feature or a valid STAC Item. - -Query Parameters -```http -?fields=-geometry -``` - -JSON -```json -{ - "fields": { - "exclude": [ - "geometry" - ] - } -} -``` - -To return the `id`, `type`, `geometry`, and the Properties attribute `eo:cloud_cover`. -This **must** return a valid STAC Item, as the includes are added to the default includes. -Explicitly specifying `id`, `type`, and `geometry` has not effect as these are default fields, -but `properties.eo:cloud_cover` is not a default field and thereby should be in the response. - -Query Parameters -```http -?fields=id,type,geometry,properties.eo:cloud_cover -``` - -JSON -```json -{ - "fields": { - "include": [ - "id", - "type", - "geometry", - "properties.eo:cloud_cover" - ] - } -} -``` - -To include `id` and all the properties fields, except for the `foo` field. - -Query Parameters -```http -?fields=id,properties,-properties.foo -``` - -also valid: -```http -?fields=+id,+properties,-properties.foo -``` - -JSON -```json -{ - "fields": { - "include": [ - "id", - "properties" - ], - "exclude": [ - "properties.foo" - ] - } -} -``` diff --git a/fragments/fields/openapi.yaml b/fragments/fields/openapi.yaml deleted file mode 100644 index f772b435..00000000 --- a/fragments/fields/openapi.yaml +++ /dev/null @@ -1,57 +0,0 @@ -openapi: 3.0.3 -info: - title: The SpatioTemporal Asset Catalog API - Fields - description: Adds parameter to control which fields are returned in the response. - version: 1.0.0-rc.1 -paths: {} -components: - parameters: - fields: - name: fields - x-stac-api-fragment: fields - in: query - description: |- - **Extension:** Fields - - Determines the shape of the features in the response - required: false - schema: - type: string - example: 'id,type,-geometry,bbox,properties,-links,-assets' - style: form - explode: false - schemas: - searchBody: - type: object - x-stac-api-fragment: fields - description: |- - **Extension:** Fields - - Determines the shape of the features in the response - properties: - fields: - $ref: '#/components/schemas/fields' - fields: - description: | - The include and exclude members specify an array of - property names that are either included or excluded - from the result, respectively. If both include and - exclude are specified, include takes precedence. - Values should include the full JSON path of the property. - type: object - properties: - include: - type: array - items: - type: string - exclude: - type: array - items: - type: string - example: - include: - - id - - 'properties.eo:cloud_cover' - exclude: - - geometry - - properties.datetime diff --git a/fragments/filter/README.md b/fragments/filter/README.md deleted file mode 100644 index 73b50539..00000000 --- a/fragments/filter/README.md +++ /dev/null @@ -1,1086 +0,0 @@ -# STAC API - Filter Fragment - -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Classes:** - - Item Search Filter: - - Filter: - - Features Filter: - - CQL2 Text: - - CQL2 JSON: - - Basic CQL2: - - Advanced Comparison Operators: - - Basic Spatial Operators: - - Spatial Operators: - - Temporal Operators: - - Custom Functions: - - Arithmetic Expressions: - - Array Operators: - - Property-Property Comparisons: - - Accent and Case-insensitive Comparison: -- **Extension [Maturity Classification](../../README.md#maturity-classification):** Pilot -- **Dependents:** - - [Item Search](../../item-search) - -- [STAC API - Filter Fragment](#stac-api---filter-fragment) - - [Overview](#overview) - - [Limitations of Item Search](#limitations-of-item-search) - - [Filter expressiveness](#filter-expressiveness) - - [Conformance Classes](#conformance-classes) - - [Getting Started with Implementation](#getting-started-with-implementation) - - [Queryables](#queryables) - - [GET Query Parameters and POST JSON fields](#get-query-parameters-and-post-json-fields) - - [Interaction with Endpoints](#interaction-with-endpoints) - - [Examples](#examples) - - [Example 1](#example-1) - - [Example 1: GET with cql2-text](#example-1-get-with-cql2-text) - - [Example 1: POST with cql2-json](#example-1-post-with-cql2-json) - - [Example 2](#example-2) - - [Example 2: GET with cql2-text](#example-2-get-with-cql2-text) - - [Example 2: POST with cql2-json](#example-2-post-with-cql2-json) - - [Example 3: Conjunction with AND](#example-3-conjunction-with-and) - - [Example 3: AND cql2-text (GET)](#example-3-and-cql2-text-get) - - [Example 3: AND cql2-json (POST)](#example-3-and-cql2-json-post) - - [Example 4: Disjunction with OR](#example-4-disjunction-with-or) - - [Example 4: OR cql2-text (GET)](#example-4-or-cql2-text-get) - - [Example 4: OR cql2-json (POST)](#example-4-or-cql2-json-post) - - [Example 5: Property-Property Comparisons](#example-5-property-property-comparisons) - - [Example 5: GET with cql2-text](#example-5-get-with-cql2-text) - - [Example 5: POST with cql2-json](#example-5-post-with-cql2-json) - - [Example 6: Temporal Intersection](#example-6-temporal-intersection) - - [Example 6: T_INTERSECTS cql2-text (GET)](#example-6-t_intersects-cql2-text-get) - - [Example 6: T_INTERSECTS cql2-json (POST)](#example-6-t_intersects-cql2-json-post) - - [Example 7: Spatial Intersection](#example-7-spatial-intersection) - - [Example 7: S_INTERSECTS cql2-text (GET)](#example-7-s_intersects-cql2-text-get) - - [Example 7: S_INTERSECTS cql2-json (POST)](#example-7-s_intersects-cql2-json-post) - - [Example 8: Spatial Intersection Disjunction](#example-8-spatial-intersection-disjunction) - - [Example 8: S_INTERSECTS cql2-text (GET)](#example-8-s_intersects-cql2-text-get) - - [Example 8: S_INTERSECTS cql2-json (POST)](#example-8-s_intersects-cql2-json-post) - - [Example 9: Using IS NULL](#example-9-using-is-null) - - [Example 9: cql2-text (GET)](#example-9-cql2-text-get) - - [Example 9: cql2-json (POST)](#example-9-cql2-json-post) - - [Example 10: Using BETWEEN](#example-10-using-between) - - [Example 10: cql2-text (GET)](#example-10-cql2-text-get) - - [Example 10: cql2-json (POST)](#example-10-cql2-json-post) - - [Example 11: Using LIKE](#example-11-using-like) - - [Example 11: cql2-text (GET)](#example-11-cql2-text-get) - - [Example 11: cql2-json (POST)](#example-11-cql2-json-post) - - [Example 12: Using the CASEI Case-insensitive Comparison Function](#example-12-using-the-casei-case-insensitive-comparison-function) - - [Example 12: cql2-text (GET)](#example-12-cql2-text-get) - - [Example 12: cql2-json (POST)](#example-12-cql2-json-post) - - [Example 13: Using the ACCENTI Accent-insensitive Comparison Function](#example-13-using-the-accenti-accent-insensitive-comparison-function) - - [Example 13: cql2-text (GET)](#example-13-cql2-text-get) - - [Example 13: cql2-json (POST)](#example-13-cql2-json-post) - -## Overview - -The Filter extension provides an expressive mechanism for searching based on Item attributes. - -This extension references behavior defined in the -[OGC API - Features - Part 3: Filtering and the Common Query Language (CQL2)](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/cql) and [Common Query Language (CQL2) -](https://github.com/opengeospatial/ogcapi-features/blob/master/cql2/README.md) -specifications. As of November 2021, these specifications are still in draft status, but rapidly converging on -finalized behavior. Several behaviors have changed since the -last published [draft](https://portal.ogc.org/files/96288), so this spec references the latest revision in the -[OAFeat Part 3 spec's GitHub repo](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/cql) -and [Common Query Language (CQL2)](https://github.com/opengeospatial/ogcapi-features/blob/master/cql2/README.md)). -Implementers should proceed with implementation, but must be aware that minor changes may be made -before these specs are final. - -OAFeat Part 3 CQL2 formally defines the syntax of "CQL2" as both a text format (cql2-text) as an ABNF grammar -(largely similar to the BNF grammar in the General Model for CQL) and a JSON format (cql2-json) as a JSON Schema and -OpenAPI schema. Additionally, it defines a natural -language description of the declarative semantics, which were never well-defined for the original CQL language. -The CQL2 Text format has had long-standing use within -geospatial software (e.g., GeoServer), is not expected to change before final. -OGC CQL2 Text has been previously described in [OGC Filter Encoding](https://www.ogc.org/standards/filter) and -[OGC Catalogue Services 3.0 - General Model](http://docs.opengeospatial.org/is/12-168r6/12-168r6.html#62) -(including a BNF grammar in Annex B). The CQL2 JSON format is newly-defined and has changed significantly during -the draft process, but is believed to be stable now. - -It should be noted that the "CQL" referred to here is "CQL2" defined in OGC API - Features - Part 3. This is a related, but -different language to the "classic" OGC CQL defined in the General Model. Relatedly, CQL is **not** -referencing or related two other "CQL" languages, -the [SRU (Search/Retrieve via URL) Contextual Query Language](https://www.loc.gov/standards/sru/cql/index.html) (formerly -known as Common Query Language) or the [Cassandra Query Language](https://cassandra.apache.org/doc/latest/cql/) used by the -Cassandra database. - -## Limitations of Item Search - -OAFeat defines a limited set of filtering capabilities. 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: -- It allows cross-collection filtering, whereas OAFeat only allows filtering within a single collection. - (`collections` parameter, accepting 0 or more collections) -- It allows filtering by Item ID (`ids` parameter) -- It allows filtering based on a single GeoJSON Geometry, rather than only a bbox (`intersects` parameter) - -However, it does not contain a formalized way to filter based on arbitrary fields in an Item. For example, there is -no way to express the filter "item.properties.eo:cloud_cover is less than 10". It also does not have a way to logically combine -multiple spatial or temporal filters. - -## Filter expressiveness - -This extension expands the capabilities of Item Search and the OAFeat Items resource with -[OAFeat Part 3 CQL2](https://portal.ogc.org/files/96288) -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 -predicates. - -CQL2 enables more expressive queries than supported by STAC API Item Search. These include: -- Use of Item Property values in predicates (e.g., `item.properties.eo:cloud_cover`), using comparison operators -- Items whose `datetime` values are in the month of August of the years 2017-2021, using OR and datetime comparisons -- Items whose `geometry` values intersect any one of several Polygons, using `OR` and `S_INTERSECTS` -- Items whose `geometry` values intersect one Polygon, but do not intersect another one, using AND, NOT, and - S_INTERSECTS - -## Conformance Classes - -OAFeat Part 3 CQL2 defines several conformance classes that allow implementers to create compositions of -functionality that support whatever expressiveness they need. This allows implementers to incrementally support CQL -syntax, without needing to implement a huge spec all at once. Some implementers choose not to incur the cost of -implementing functionality they do not need or may not be able to implement functionality that is not supported by -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 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-rc.1/item-search#filter`) to bind -the Filter behavior to the Item Search endpoint. - -The implementation **must** support these conformance classes: - -- Filter (`http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter`) defines the Queryables mechanism and - parameters `filter-lang`, `filter-crs`, and `filter`. -- Basic CQL2 (`http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2`) defines the basic operations allowed in - 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-rc.1/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`). - -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 - -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 -CQL2 JSON in POST requests. - -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 - `lower` and `upper` functions. -- Basic Spatial Operators (`http://www.opengis.net/spec/cql2/1.0/conf/basic-spatial-operators`) defines the intersects operator (`S_INTERSECTS`). -- Spatial Operators - (`http://www.opengis.net/spec/cql2/1.0/conf/spatial-operators`) defines a set of operators that - are part of the Dimensionally Extended Nine-intersection Model (DE-9IM) relation operators - (`S_CONTAINS`, `S_CROSSES`, `S_DISJOINT`, `S_EQUALS`, `S_INTERSECTS`, `S_OVERLAPS`, `S_TOUCHES`, and `S_WITHIN`) -- Temporal Operators - (`http://www.opengis.net/spec/cql2/1.0/conf/temporal-operators`) defines several temporal - operators that provide more expressivity with datetime types than the relative comparison - operators - in the Basic CQL2 class. -- Custom Functions (`http://www.opengis.net/spec/cql2/1.0/conf/functions`) defines support - for function definition and usage. -- Arithmetic Expressions: (`http://www.opengis.net/spec/cql2/1.0/conf/arithmetic`) defines - support for arithmetic expressions. -- Array Operators: (`http://www.opengis.net/spec/cql2/1.0/conf/array-operators`) - defines array operators (`A_EQUALS`, `A_CONTAINS`, `A_CONTAINED_BY`, and `A_OVERLAPS`). -- Property-Property Comparisons: (`http://www.opengis.net/spec/cql2/1.0/conf/property-property`) - allows the use of queryables (e.g., properties) in both positions of a clause, not just in the - first position. This allows predicates like `property1 = property2` be expressed, whereas the - Basic CQL2 conformance class only requires comparisons against right-hand-side literals. -- Accent and Case-insensitive Comparison: (`http://www.opengis.net/spec/cql2/1.0/conf/accent-case-insensitive-comparison`) - defines the UPPER and LOWER functions that can be used for case-insensitive comparison. - -Additionally, if an API implements the OGC API Features endpoint, it is **recommended** that the OAFeat Part 3 Filter, -Features Filter, and Basic CQL2 conformance classes be implemented, which allow use of CQL2 filters against the -OAFeat Part 1 Features endpoint (`/collections/{collectionId}/items`). Note that POST with a JSON body -to the Features resource is not supported, as POST is used by the -[Transaction Extension](../../ogcapi-features/extensions/transaction/README.md) for creating items. - -## Getting Started with Implementation - -It recommended that implementers start with fully implementing only a subset of functionality. A good place to start is -implementing only the Basic CQL2 conformance class of logical and comparison operators, defining a static Queryables -schema with no queryables advertised and the `additionalProperties` field set to `true`, and -only implementing CQL2 JSON. Following from that can be support for -S_INTERSECTS, defining a static Queryables schema with only the basic Item properties, and -implementing CQL2 Text. From there, other comparison operators can be implemented and a more -dynamic Queryables schema. - -Formal definitions and grammars for CQL2 can be found in the -[OAFeat CQL spec](https://github.com/opengeospatial/ogcapi-features/tree/master/cql2) includes a BNF grammar - for CQL2 Text and both a JSON Schema and an OpenAPI specification for CQL2 JSON. The standalone files are: -- [cql.bnf](https://github.com/opengeospatial/ogcapi-features/blob/master/extensions/cql/standard/schema/cql.bnf) -- [cql.json](https://github.com/opengeospatial/ogcapi-features/blob/master/extensions/cql/standard/schema/cql.json) -- [cql.yml](https://github.com/opengeospatial/ogcapi-features/blob/master/extensions/cql/standard/schema/cql.yml) - -These projects have or are developing CQL2 support: -- [pgstac](https://github.com/stac-utils/pgstac) supports CQL2 JSON -- [pygeofilter](https://github.com/geopython/pygeofilter) has support for CQL2 JSON and for the older ECQL standard that -- [xtraplatform-spatial](https://github.com/interactive-instruments/xtraplatform-spatial) has support for CQL2 Text and provides an [ANTLR 4 grammer](https://github.com/interactive-instruments/xtraplatform-spatial/tree/master/xtraplatform-cql/src/main/antlr/de/ii/xtraplatform/cql/infra) -- [Geotools](https://github.com/geotools/geotools) has support for [CQL2 text](https://github.com/geotools/geotools/tree/main/modules/library/cql/src/main/java/org/geotools/filter/text/cql2) -- [Franklin](https://github.com/azavea/franklin) is working on it in [this PR](https://github.com/azavea/franklin/pull/750). - -Note that the [xbib CQL library (JVM)](https://github.com/xbib/cql) is the OASIS Contextual Query Language, not -OGC CQL, and should not be used to implement this extension, as they are significantly different query languages. -[Stacatto](https://github.com/planetlabs/staccato) uses this for their query language implementation, but it is -not compliant with this extension. - -## Queryables - -The Queryables mechanism allows a client to discover what terms are available for use when writing filter -expressions. These terms can be defined per-collection, and the intersection of these terms over all collections is what -is available for filtering when there are no collection restrictions. By default, these queryables are the only terms that may be used -in filter expressions, and if any term is used in expression that is not defined as a queryable and error must be -returned according to OAFeat Part 3. It is recognized that this is a severe restriction in STAC APIs that have highly variable -and dynamic content, so this behavior may be modified by setting the `additionalProperties` attribute in the -queryables definition to `true`. As such, any syntactically-valid term for a property will be accepted, and the -matching semantics are such that, if an Item does not have an attribute by that name, the value is assumed to be -`null`. It is recommended to use fully-qualified property names (e.g., `properties.eo:cloud_cover`). - -Queryables are advertised via a JSON Schema document retrieved from the `/queryables` endpoint. This endpoint at the root -retrieves queryables that apply to all collections. When used as a subresource of the collection resource -(e.g. /collections/collection1/queryables), it returns queryables pertaining only to that single collection. - -It is required to implement both of these endpoints, but for a STAC API, this may simply be a static document of the -STAC-specific fields. A basic Queryables -definitions for STAC Items should include at least the fields id, collection, geometry, and datetime. - -```json -{ - "$schema" : "https://json-schema.org/draft/2019-09/schema", - "$id" : "https://stac-api.example.com/queryables", - "type" : "object", - "title" : "Queryables for Example STAC API", - "description" : "Queryable names for the example STAC API Item Search filter.", - "properties" : { - "id" : { - "description" : "ID", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/id" - }, - "collection" : { - "description" : "Collection", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/collection" - }, - "geometry" : { - "description" : "Geometry", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/geometry" - }, - "datetime" : { - "description" : "Datetime", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/datetime.json#/properties/datetime" - } - }, - "additionalProperties": true -} -``` - -Fields in Item Properties should be exposed with their un-prefixed names, and not require expressions to prefix them -with `properties`, e.g., `eo:cloud_cover` instead of `properties.eo:cloud_cover`. - -There may also be support for finding what queryables are available for a subset of collections, e.g., -`/queryables?collections=c1,c3`) as described in [this issue](https://github.com/opengeospatial/ogcapi-features/issues/576). - -The Landing Page endpoint (`/`) will have a Link with rel `http://www.opengis.net/def/rel/ogc/1.0/queryables` with an href to -the endpoint `/queryables`. Additionally, each Collection resource will have a Link to the queryables resource for that -collection, e.g., `/collections/collection1/queryables`. - -The queryables endpoint returns a JSON Schema describing the names and types of terms that may be used in filter expressions. -This response is defined in JSON Schema because it is a well-specified typed schema, but it is not used for validating a JSON -document derived from it. This schema defines the terms that may be used in a CQL2 filter. - -These queryable terms are mapped by the service to filter Items. For example, the service may define a queryable with the -name "eo:cloud_cover" that can be used in a CQL2 expression like `eo:cloud_cover <= 10`, with the semantics that only Items where the -`properties.eo:cloud_cover` value was <= 10 would match the filter. The server would then translate this into an appropriate -query for the data within its datastore. - -Queryables can be static or dynamically derived. For example, `cloud_cover` might be specified to have a value 0 to 100 or a field -may have a set of enumerated values dynamically determined by an aggregation at runtime. This schema can be used by a UI or -interactive client to dynamically expose to the user the fields that are available for filtering, and provide a precise group -of options for the values of these terms. - -Queryables can also be used to advertise "synthesized" property values. The only requirement in CQL2 is that the property have a type -and evaluate to literal value of that type or NULL. For example, a filter like "Items must have an Asset with an eo:band with -the common_name of 'nir'" can be expressed. A Queryable `assets_bands` could be defined to have a type of array of string and -have the semantics that it contains all of `common_name` values across all assets and bands for an Item. This could then be -filtered with the CQL2 expression `'nir' in assets_bands`. Implementations would then expand this expression into the -appropriate query against its datastore. (TBD if this will actually work or not. This is also related to the upcoming -restriction on property/literal comparisons) - -An implementation may also choose not to advertise any queryables, and provide the user with out-of-band information or -simply let them try querying against fields. While this is not allowed according to the OGC CQL2 Queryable spec, it is allowed -in STAC API by the Filter Extension. In this case, the queryables endpoint (`/queryables`) would return this document: - -```json -{ - "$schema" : "https://json-schema.org/draft/2019-09/schema", - "$id" : "https://stac-api.example.com/queryables", - "type" : "object", - "title" : "Queryables for Example STAC API", - "description" : "Queryable names for the example STAC API Item Search filter.", - "properties" : { - }, - "additionalProperties": true -} -``` - -## GET Query Parameters and POST JSON fields - -This extension adds three GET query parameters or POST JSON fields to an Item Search request: - -- filter-lang:`cql2-text` or `cql2-json`. If undefined, defaults to `cql2-text` for a GET request and `cql2-json` for a POST request. -- filter-crs: recommended to not be passed, but server must only accept `http://www.opengis.net/def/crs/OGC/1.3/CRS84` as - a valid value, may reject any others -- filter: CQL2 filter expression - -API implementations advertise which `filter-lang` values are supported via conformance classes in the Landing Page. -At least one must be implemented, but it is recommended to implement both. If both are advertised as conformance classes, the -server should process either for a GET request, but may only process cql2-json for a POST request. If POST of cql2-text is not -supported, the server must return a 400 error if `filter-lang=cql2-text`. - -## Interaction with Endpoints - -In an implementation that supports several operator classes, the Landing Page (`/`) must return a document including -at least these values: - -```json -{ - "id": "example_stacapi", - "conformsTo": [ - "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core", - "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30", - "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson", - - "http://www.opengis.net/spec/ogcapi_common-2/1.0/conf/collections", - - "http://api.stacspec.org/v1.0.0-rc.1/core", - "http://api.stacspec.org/v1.0.0-rc.1/stac-search", - "http://api.stacspec.org/v1.0.0-rc.1/stac-response", - - "https://api.stacspec.org/v1.0.0-rc.1/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/basic-spatial-operators", - "http://www.opengis.net/spec/cql2/1.0/conf/advanced-comparison-operators" - - ], - "links": [ - { - "title": "Search", - "href": "https://stac-api.example.com/search", - "rel": "search", - "type": "application/geo+json" - }, - { - "title": "Queryables", - "href": "https://stac-api.example.com/queryables", - "rel": "http://www.opengis.net/def/rel/ogc/1.0/queryables", - "type": "application/schema+json" - } - ], - "stac_extensions": [], - "stac_version": "1.0.0", - "type": "Catalog", -} -``` - -A client can use the link with `"rel": "http://www.opengis.net/def/rel/ogc/1.0/queryables"` to retrieve the queryables. - -The Queryables endpoint (`/queryables`) returns something like the following: - -```json -{ - "$schema" : "https://json-schema.org/draft/2019-09/schema", - "$id" : "https://stac-api.example.com/queryables", - "type" : "object", - "title" : "Queryables for Example STAC API", - "description" : "Queryable names for the example STAC API Item Search filter.", - "properties" : { - "id" : { - "description" : "ID", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/id" - }, - "collection" : { - "description" : "Collection", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/collection" - }, - "geometry" : { - "description" : "Geometry", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/geometry" - }, - "datetime" : { - "description" : "Datetime", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/datetime.json#/properties/datetime" - }, - "eo:cloud_cover" : { - "description" : "Cloud Cover", - "$ref": "https://stac-extensions.github.io/eo/v1.0.0/schema.json#/properties/eo:cloud_cover" - }, - "gsd" : { - "description" : "Ground Sample Distance", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/instrument.json#/properties/gsd" - }, - "assets_bands" : { - "description" : "Asset eo:bands common names", - "$ref": "https://stac-extensions.github.io/eo/v1.0.0/schema.json#/properties/eo:bands/common_name" - } - }, - "additionalProperties": true -} -``` - -Alternately, the client could retrieve the queryables for a single collection with -`/collections/collections1/queryables`, which may have more queryables than available for the entire catalog, since -there may be queryables that are only relevant to that collection. - -Notice in this schema that instead of directly defining the type information about each field, we have instead used the JSON -Schema `$ref` mechanism to refer to a STAC schema definition. This not only allows the reuse of these JSON Schema definitions, -but also binds an arbitrarily-named Queryable to a specific STAC field. For example, in the above we know that the -`eo:cloud_cover` field is referring to the field of the same name in the EO Extension not because they happen to have the same -name, but rather because the `$ref` indicates it. The field could just as well be named "cloud_cover", "CloudCover", or "cc", -and we would still know it filtered on the EO extension `eo:cloud_cover` field. For example, if the queryable was named -"CloudCover", a CQL2 expression using that queryable would look like `CloudCover <= 10`. - -While these do seem quite complex to write and understand, keep in mind that query construction will likely be done with a -more ergonomic SDK, and query parsing will be done with the help of a ABNF grammar and OpenAPI schema. - -These parameters/fields must be supported by the STAC Item Search endpoint and OAFeat Features resource (`/collections/$collectionId/items`). - -## Examples - -Note: the GET examples with query parameters are unescaped to make them easier to read. - -The GET examples are assuming a call to `GET /search` and the POST examples are assuming a -call to `POST /search`. - -The parameter `filter-crs` always defaults to `http://www.opengis.net/def/crs/OGC/1.3/CRS84` for a STAC API, so is not shown -in any of these examples. - -### Example 1 - -This example uses the queryables definition in (Interaction with Endpoints)(#interaction-with-endpoints). - -#### Example 1: GET with cql2-text - -Note that `filter-lang` defaults to `cql2-text` in this case. The parameter `filter-crs` defaults -to `http://www.opengis.net/def/crs/OGC/1.3/CRS84` for a STAC API. - -```http -filter=id='LC08_L1TP_060247_20180905_20180912_01_T1_L1TP' AND collection='landsat8_l1tp' -``` - -#### Example 1: POST with cql2-json - -Note that `filter-lang` defaults to `cql2-json` in this case. The parameter `filter-crs` defaults -to `http://www.opengis.net/def/crs/OGC/1.3/CRS84` for a STAC API. - -```json -{ - "filter": { - "op" : "and", - "args": [ - { - "op": "=", - "args": [ { "property": "id" }, "LC08_L1TP_060247_20180905_20180912_01_T1_L1TP" ] - }, - { - "op": "=", - "args" : [ { "property": "collection" }, "landsat8_l1tp" ] - } - ] - } -} -``` - -### Example 2 - -This example uses the queryables definition in [Interaction with Endpoints](#interaction-with-endpoints). - -Note that filtering on the `collection` field is relevant in Item Search, since the queries are cross-collection, whereas -OGC API Features filters only operate against a single collection already. - -#### Example 2: GET with cql2-text - -```http -filter=collection = 'landsat8_l1tp' - AND eo:cloud_cover <= 10 - AND datetime >= TIMESTAMP('2021-04-08T04:39:23Z') - AND S_INTERSECTS(geometry, POLYGON((43.5845 -79.5442, 43.6079 -79.4893, 43.5677 -79.4632, 43.6129 -79.3925, 43.6223 -79.3238, 43.6576 -79.3163, 43.7945 -79.1178, 43.8144 -79.1542, 43.8555 -79.1714, 43.7509 -79.6390, 43.5845 -79.5442))) -``` - -#### Example 2: POST with cql2-json - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "and", - "args": [ - { - "op": "=", - "args": [ { "property": "collection" }, "landsat8_l1tp" ] - }, - { - "op": "<=", - "args": [ { "property": "eo:cloud_cover" }, 10 ] - }, - { - "op": ">=", - "args": [ { "property": "datetime" }, { "timestamp": "2021-04-08T04:39:23Z" } ] - }, - { - "op": "s_intersects", - "args": [ - { - "property": "geometry" - }, - { - "type": "Polygon", - "coordinates": [ - [ - [43.5845, -79.5442], - [43.6079, -79.4893], - [43.5677, -79.4632], - [43.6129, -79.3925], - [43.6223, -79.3238], - [43.6576, -79.3163], - [43.7945, -79.1178], - [43.8144, -79.1542], - [43.8555, -79.1714], - [43.7509, -79.6390], - [43.5845, -79.5442] - ] - ] - } - ] - } - ] - } -} -``` - -### Example 3: Conjunction with AND - -We'll be imagining these as queries against [EarthSearch Sentinel 2 -COG](https://stacindex.org/catalogs/earth-search#/Cnz1sryATwWudkxyZekxWx6356v9RmvvCcLLw79uHWJUDvt2?t=items) data. - -The queryables defined are as follows: - -```json -{ - "$schema" : "https://json-schema.org/draft/2019-09/schema", - "$id" : "https://stac-api.example.com/queryables", - "type" : "object", - "title" : "Queryables for Example STAC API", - "description" : "Queryable names for the example STAC API Item Search filter.", - "properties" : { - "geometry" : { - "description" : "Geometry", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/geometry" - }, - "datetime" : { - "description" : "Datetime", - "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/datetime.json#/properties/datetime" - }, - "eo:cloud_cover" : { - "description" : "Cloud Cover", - "$ref": "https://stac-extensions.github.io/eo/v1.0.0/schema.json#/properties/eo:cloud_cover" - }, - "acme:data_coverage" : { - "description" : "Acme Sat Data Coverage", - "type": "integer", - "minimum": 0, - "maximum": 100 - }, - "acme:grid_id" : { - "description" : "Acme Sat Grid ID", - "type": "string" - } - } -} -``` - -Note that `acme:data_coverage` and `acme:grid_id` are properties that are not defined in an extension schema, and are intended to -represent vendor-specific properties. Because of this, they are fully specified directly in the JSON Schema. However, it is -recommended that vendor-specific properties be published as part of a well-defined extension schema, so these only represent ones -that have not followed that recommendation. - -A sample STAC Item (excluding `assets`) is: - -```json -{ - "type": "Feature", - "stac_version": "1.0.0", - "stac_extensions": [ - "https://stac-extensions.github.io/eo/v1.0.0/schema.json", - "https://stac-extensions.github.io/view/v1.0.0/schema.json", - "https://stac-extensions.github.io/projection/v1.0.0/schema.json" - ], - "id": "S2A_60HWB_20201111_0_L2A", - "bbox": [ 176.9997779369264, -39.83783732066656, 178.14624317719924, -38.842842449352425], - "geometry": { - "type": "Polygon", - "coordinates": [[[176.9997779369264, -39.83783732066656],[176.99978104582647,-38.84846679951431], - [178.14624317719924, -38.842842449352425],[177.8514661209684,-39.83471270154608], - [176.9997779369264, -39.83783732066656]]] - }, - "properties": { - "datetime": "2020-11-11T22:16:58Z", - "platform": "sentinel-2a", - "constellation": "sentinel-2", - "instruments": ["msi"], - "gsd": 10, - "view:off_nadir": 0, - "proj:epsg": 32760, - "sentinel:utm_zone": 60, - "sentinel:latitude_band": "H", - "sentinel:grid_square": "WB", - "sentinel:sequence": "0", - "sentinel:product_id": "S2A_MSIL2A_20201111T221611_N0214_R129_T60HWB_20201111T235959", - "sentinel:data_coverage": 78.49, - "eo:cloud_cover": 0.85, - "sentinel:valid_cloud_cover": true, - "created": "2020-11-12T02:08:31.563Z", - "updated": "2020-11-12T02:08:31.563Z" - } -} -``` - -One problem in working with Sentinel-2 data is that many scenes only contain a tiny "sliver" of data, where the satellite's -recording path intersection only a corner of a grid square. This examples shows -Show me all imagery that has low cloud cover (less than 10), and high data coverage (50), as I'd like a cloud free image that is not just -a tiny sliver of data. - -#### Example 3: AND cql2-text (GET) - -```http -filter=sentinel:data_coverage > 50 AND eo:cloud_cover < 10 -``` - -#### Example 3: AND cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "and", - "args": [ - { - "op": ">", - "args": [ { "property": "sentinel:data_coverage" }, 50 ] - }, - { - "op": "<", - "args": [ { "property": "eo:cloud_cover" }, 10 ] - } - ] - } -} -``` - -An 'or' is also supported, matching if either condition is true. Though it's not a sensible query you could get images that have full data -coverage or low cloud cover. - -### Example 4: Disjunction with OR - -This uses the same queryables as Example 4. - -#### Example 4: OR cql2-text (GET) - -```http -filter=sentinel:data_coverage > 50 OR eo:cloud_cover < 10 -``` - -#### Example 4: OR cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "or", - "args": [ - { - "op": ">", - "args": [ { "property": "sentinel:data_coverage" }, 50 ] - }, - { - "op": "<", - "args": [ { "property": "eo:cloud_cover" }, 10 ] - } - ] - } -} -``` - -### Example 5: Property-Property Comparisons - -The Property-Property Comparisons conformance class permits queryable properties to be used on either side -of an operator. This is a generic example, as there are few STAC properties -that are comparable in a meaningful way. This example uses a contrived example of two proprietary properties, -`prop1` and `prop2` that are of the same type. - -This queryables JSON Schema is used in these examples: - -```json -{ - "$schema" : "https://json-schema.org/draft/2019-09/schema", - "$id" : "https://stac-api.example.com/queryables", - "type" : "object", - "title" : "Queryables for Example STAC API", - "description" : "Queryable names for the example STAC API Item Search filter.", - "properties" : { - "prop1" : { - "description" : "Property 1", - "type": "integer" - }, - "prop2" : { - "description" : "Property 2", - "type": "integer" - } - } -} -``` - -#### Example 5: GET with cql2-text - -```http -filter=prop1 = prop2 -``` - -#### Example 5: POST with cql2-json - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "=", - "args": [ - { "property": "prop1" }, - { "property": "prop2" } - ] - } -} -``` - -### Example 6: Temporal Intersection - -This uses the same queryables as Example 4. - -The only temporal operator required is `ANYINTERACTS`. This is effectively that the datetime or interval operands -have any overlap between them. - -#### Example 6: T_INTERSECTS cql2-text (GET) - -```http -filter=datetime T_INTERSECTS INTERVAL('2020-11-11T00:00:00Z', '2020-11-12T00:00:00Z') -``` - -#### Example 6: T_INTERSECTS cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "t_intersects", - "args": [ - { "property": "datetime" }, - { "interval" : [ "2020-11-11T00:00:00Z", "2020-11-12T00:00:00Z"] } - ] - } -} -``` - -### Example 7: Spatial Intersection - -The only spatial operator that must be implemented for Basic Spatial Operators -is `S_INTERSECTS`. This has the same semantics as provided -by the Item Search `intersects` parameter. The `cql2-text` format uses WKT geometries and the `cql2-json` -format uses GeoJSON geometries. - -#### Example 7: S_INTERSECTS cql2-text (GET) - -```http -filter=S_INTERSECTS(geometry,POLYGON((-77.0824 38.7886,-77.0189 38.7886,-77.0189 38.8351,-77.0824 38.8351,-77.0824 38.7886))) -``` - -#### Example 7: S_INTERSECTS cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "s_intersects", - "args": [ - { "property": "geometry" } , - { - "type": "Polygon", - "coordinates": [[ - [-77.0824, 38.7886], [-77.0189, 38.7886], - [-77.0189, 38.8351], [-77.0824, 38.8351], - [-77.0824, 38.7886] - ]] - } - ] - } -} -``` - -### Example 8: Spatial Intersection Disjunction - -One limitation of the `intersects` parameter is that only a single geometry may be provided. While most -GeoJSON geometries can be combined to form a composite (e.g., multiple Polygons can be combined to form a -MultiPolygon), this is much easier to do in the query by combining `S_INTERSECTS` predicates with the `OR` -logical operator. - -#### Example 8: S_INTERSECTS cql2-text (GET) - -```http -filter=S_INTERSECTS(geometry,POLYGON((-77.0824 38.7886,-77.0189 38.7886,-77.0189 38.8351,-77.0824 38.8351,-77.0824 38.7886))) OR S_INTERSECTS(geometry,POLYGON((-79.0935 38.7886,-79.0290 38.7886,-79.0290 38.8351,-79.0935 38.8351,-79.0935 38.7886))) -``` - -#### Example 8: S_INTERSECTS cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "or" , - "args": [ - { - "op": "s_intersects", - "args": [ - { "property": "geometry" } , - { - "type": "Polygon", - "coordinates": [[ - [-77.0824, 38.7886], [-77.0189, 38.7886], - [-77.0189, 38.8351], [-77.0824, 38.8351], - [-77.0824, 38.7886] - ]] - } - ] - }, - { - "op": "s_intersects", - "args": [ - { "property": "geometry" } , - { - "type": "Polygon", - "coordinates": [[ - [-79.0935, 38.7886], [-79.0290, 38.7886], - [-79.0290, 38.8351], [-79.0935, 38.8351], - [-79.0935, 38.7886] - ]] - } - ] - } - ] - } -} -``` - -### Example 9: Using IS NULL - -One of the main use cases for STAC API is doing cross-collection query. Commonly, this means that items have -different sets of properties. For example, a collection of Sentinel 2 data may have a property -`sentinel:data_coverage` and a collection of Landsat 8 data may have a corresponding property -`landsat:coverage_percent`, both representing what percentage of a given gridded scene actually contains -data. However, we many also want to also include in our result items that do not have a value defined for -either of those properties. - -#### Example 9: cql2-text (GET) - -```http -filter=sentinel:data_coverage > 50 OR landsat:coverage_percent < 10 OR (sentinel:data_coverage IS NULL AND landsat:coverage_percent IS NULL) -``` - -#### Example 9: cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "or", - "args": [ - { - "op": ">", - "args": [ { "property": "sentinel:data_coverage" }, 50 ] - }, - { - "op": "<", - "args": [ { "property": "landsat:coverage_percent" }, 10 ] - }, - { - "op": "and", - "args": [ - { - "op": "isNull", - "args": [ { "property": "sentinel:data_coverage" } ] - }, - { - "op": "isNull", - "args": [ { "property": "landsat:coverage_percent" } ] - } - ] - } - ] - } -} -``` - -### Example 10: Using BETWEEN - -The BETWEEN operator allows for checking if a numeric value is within a specified inclusive range. - -#### Example 10: cql2-text (GET) - -```http -filter=eo:cloud_cover BETWEEN 0 AND 50 -``` - -#### Example 10: cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "between", - "args": [ - { "property": "eo:cloud_cover" }, - [ 0, 50 ] - ] - } -} -``` - -### Example 11: Using LIKE - -The LIKE operator allows for pattern-based string matching. - -#### Example 11: cql2-text (GET) - -```http -filter=mission LIKE 'sentinel%' -``` - -#### Example 11: cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "like", - "args": [ - { "property": "mission" }, - "sentinel%" - ] - } -} -``` - -### Example 12: Using the CASEI Case-insensitive Comparison Function - -The predefined function `CASEI` allows for case-insensitive comparisons. This function is -defined in the Accent and Case-insensitive Comparison conformance class. - -In the example using 'Straße', both the capitalized 'S' and Eszett ('ß') are converted to an -insensitive representation whereby the expressions `CASEI('Straße')`, `CASEI('straße')`, -`CASEI('Strasse')`, and `CASEI('strasse')` are all equal. - -#### Example 12: cql2-text (GET) - -```http -filter=CASEI(provider) = CASEI('coolsat') -``` - -```http -filter=CASEI(provider) = CASEI('Straße') -``` - -#### Example 12: cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "=", - "args": [ - { - "function" : "casei", - "args" : [ { "property": "provider" } ] - }, - { - "function" : "casei", - "args" : [ "coolsat" ] - } - ] - } -} -``` - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "=", - "args": [ - { - "function" : "casei", - "args" : [ { "property": "provider" } ] - }, - { - "function" : "casei", - "args" : [ "Straße" ] - } - ] - } -} -``` - -### Example 13: Using the ACCENTI Accent-insensitive Comparison Function - -The predefined function `ACCENTI` allows for accent-insensitive comparisons. This function is -defined in the Accent and Case-insensitive Comparison conformance class. In the example below, -`ACCENTI('tiburon')` and `ACCENTI('tiburón')` evaluate to be equal. - -#### Example 13: cql2-text (GET) - -```http -filter=ACCENTI(provider) = ACCENTI('tiburón') -``` - -#### Example 13: cql2-json (POST) - -```json -{ - "filter-lang": "cql2-json", - "filter": { - "op": "=", - "args": [ - { - "function" : "accenti", - "args" : [ { "property": "provider" } ] - }, - { - "function" : "accenti", - "args" : [ "tiburón" ] - } - ] - } -} -``` diff --git a/fragments/filter/openapi.yaml b/fragments/filter/openapi.yaml deleted file mode 100644 index e5c7f508..00000000 --- a/fragments/filter/openapi.yaml +++ /dev/null @@ -1,171 +0,0 @@ -openapi: 3.0.3 -info: - title: The SpatioTemporal Asset Catalog API - Filter - description: Adds parameters to compare properties and only return the items that match - version: 1.0.0-rc.1 - -tags: - - name: Core - description: Part of STAC API - Core definition - - name: Collections - description: Part of STAC API - Collections definition - - name: Features - description: Part of STAC API - Features definition - - name: Filter Extension - description: Part of STAC API - Filter extension definition - -paths: - '/': - get: - description: Landing Page - tags: - - Core - responses: - '200': - description: Landing Page - links: - queryables: - operationId: getQueryables - description: |- - A link with rel=queryables for the entire catalog. - - /queryables: - get: - summary: Get the JSON Schema defining the list of variable terms that can be used in CQL2 expressions. - operationId: getQueryables - description: |- - This endpoint returns a list of variable terms that can be used in CQL2 expressions. The - precise definition of this can be found in the OGC API - Features - Part 3: Filtering and the - Common Query Language (CQL) specification. - tags: - - Filter Extension - # parameters: - # todo: may have collections parameter in the future - responses: - '200': - $ref: '#/components/responses/Queryables' - default: - $ref: '../../core/commons.yaml#/components/responses/Error' - /collections/{collectionId}: - get: - description: |- - This endpoint returns a list of Collections. - tags: - - Features - - Collections - parameters: - - in: path - name: collectionId - schema: - type: string - required: true - description: ID of Collection - responses: - '200': - description: Collection description - links: - queryables: - operationId: getQueryables - description: |- - A link with rel=queryables for queryables to only apply to this collection. - /collections/{collectionId}/queryables: - get: - summary: Get the JSON Schema defining the list of variable terms that can be used in CQL2 expressions. - operationId: getQueryablesForCollection - description: |- - This endpoint returns a list of variable terms that can be used in CQL2 expressions. The - precise definition of this can be found in the OGC API - Features - Part 3: Filtering and the - Common Query Language (CQL) specification. - parameters: - - in: path - name: collectionId - schema: - type: string - required: true - description: ID of Collection - tags: - - Filter Extension - responses: - '200': - $ref: '#/components/responses/Queryables' - default: - $ref: '../../core/commons.yaml#/components/responses/Error' -components: - parameters: - filter: - name: filter - x-stac-api-fragment: filter - in: query - description: |- - **Extension:** Filter - - A CQL2 filter expression for filtering items. - required: true - schema: - oneOf: - - $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 'cql2-text' or 'cql2-json'. - required: false - schema: - $ref: '#/components/schemas/filter-lang' - filter-crs: - name: filter-crs - x-stac-api-fragment: filter - in: query - description: |- - **Extension:** Filter - - The CRS used by spatial predicates in the filter parameter. In STAC API, only value that must be accepted - is 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'. - required: false - schema: - $ref: '#/components/schemas/filter-crs' - schemas: - searchBody: - type: object - x-stac-api-fragment: filter - description: |- - **Extension:** Filter - - A filter for properties in Items. - properties: - filter: - $ref: '#/components/schemas/filter-cql2-json' - filter-lang: - $ref: '#/components/schemas/filter-lang' - 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' - filter-lang: - description: | - The CQL2 filter encoding that the 'filter' value uses. - type: string - enum: - - '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 - accept is 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'. - type: string - format: uri - responses: - Queryables: - description: A JSON Schema defining the Queryables allowed in CQL2 expressions - content: - application/schema+json: - schema: - type: object diff --git a/fragments/itemcollection/README.md b/fragments/itemcollection/README.md index f9af3cdd..0af528f4 100644 --- a/fragments/itemcollection/README.md +++ b/fragments/itemcollection/README.md @@ -27,7 +27,7 @@ This object describes a STAC ItemCollection. The fields `type` and `features` ar ## Extensions -- The [Context Extension](../../item-search/README.md#context-extension) adds additional fields to STAC ItemCollection relevant +- The [Context Extension](https://github.com/stac-api-extensions/context) adds additional fields to STAC ItemCollection relevant to their use as search results. - The [Single File STAC Extension](https://github.com/stac-extensions/single-file-stac/blob/main/README.md) provides a set of Collection and Item objects as a single file catalog. diff --git a/fragments/query/README.md b/fragments/query/README.md deleted file mode 100644 index d9d27348..00000000 --- a/fragments/query/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# STAC API - Query Fragment - -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Class:** -- **Extension [Maturity Classification](../../README.md#maturity-classification):** Candidate -- **Dependents:** - - [Item Search](../../item-search) - -The `query` parameter adds additional filters for searching on the properties of Item objects. The JSON syntax for -these filters is known as "STACQL" (pronounced `stack-cue-el`). - -The syntax for the `query` filter is: - -```js -{ - "query": { - "": { - "": - } - } -} -``` - -Each property to search is an entry in the `query` filter. `` can be one of: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `startsWith`, `endsWith`, `contains`, `in`. -Multiple operators may be provided for each property and are treated as a logical AND, where all conditions must be met. - -## Examples - -Find scenes with cloud cover between 0 and 10%: - -```json -{ - "query": { - "eo:cloud_cover": { - "gte": 0, - "lte": 10 - }, - "stringAttr1": { - "startsWith": "abc", - "endsWith": "xyz" - }, - "stringAttr2": { - "contains": "mnop" - }, - "stringAttr3": { - "in": ["landsat", "modis", "naip"] - } - } -} -``` diff --git a/fragments/query/openapi.yaml b/fragments/query/openapi.yaml deleted file mode 100644 index d95cb413..00000000 --- a/fragments/query/openapi.yaml +++ /dev/null @@ -1,117 +0,0 @@ -openapi: 3.0.3 -info: - title: The SpatioTemporal Asset Catalog API - Query - description: Adds parameter to compare properties and only return the items that match - version: 1.0.0-rc.1 -paths: {} -components: - parameters: - query: - name: query - x-stac-api-fragment: query - in: query - description: |- - **Extension:** Query - - Query for properties in items. - Use the JSON form of the query used in POST. - required: false - schema: - type: string - schemas: - searchBody: - type: object - x-stac-api-fragment: query - description: |- - **Extension:** Query - - Allows users to query properties for specific values - properties: - query: - $ref: '#/components/schemas/query' - query: - type: object - description: Define which properties to query and the operations to apply - additionalProperties: - $ref: '#/components/schemas/queryProp' - example: - eo:cloud_cover: - gt: 8 - lt: 50 - platform: - eq: 'landsat-8' - datetime: - gte: '2018-02-12T00:00:00Z' - lte: '2018-03-18T12:31:12Z' - pl:item_type: - startsWith: PSScene - product: - in: - - foo - - bar - - baz - eo:gsd: - in: - - 10 - - 20 - queryProp: - description: Apply query operations to a specific property - anyOf: - - description: if the object doesn't contain any of the operators, it is equivalent to using the equals operator - - type: object - description: Match using an operator - properties: - eq: - description: Find items with a property that is equal to the specified value. For strings, a case-insensitive comparison must be performed. - nullable: true - oneOf: - - type: string - - type: number - - type: boolean - neq: - description: Find items that *don't* contain the specified value. For strings, a case-insensitive comparison must be performed. - nullable: true - oneOf: - - type: string - - type: number - - type: boolean - gt: - description: Find items with a property value greater than the specified value. - oneOf: - - type: string - format: date-time - - type: number - lt: - description: Find items with a property value less than the specified value. - oneOf: - - type: string - format: date-time - - type: number - gte: - description: Find items with a property value greater than or equal the specified value. - oneOf: - - type: string - format: date-time - - type: number - lte: - description: Find items with a property value less than or equal the specified value. - oneOf: - - type: string - format: date-time - - type: number - startsWith: - description: Find items with a property that begins with the specified string. A case-insensitive comparison must be performed. - type: string - endsWith: - description: Find items with a property that ends with the specified string. A case-insensitive comparison must be performed. - type: string - contains: - description: Find items with a property that contains the specified literal string, e.g., matches ".*.*". A case-insensitive comparison must be performed. - type: string - in: - description: Find items with a property that equals at least one entry in the specified array. A case-insensitive comparison must be performed. - type: array - items: - oneOf: - - type: string - - type: number diff --git a/fragments/sort/README.md b/fragments/sort/README.md deleted file mode 100644 index 79dc2a33..00000000 --- a/fragments/sort/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# STAC API - Sort Fragment - -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Class:** - - Item Search binding: - - STAC Features binding: -- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Candidate -- **Dependents:** - - [Item Search](../../item-search) - - [STAC Features](../../ogcapi-features) - -This defines a new parameter, `sortby`, that allows the user to define fields by which to sort results. -Only string, numeric, and datetime attributes of Item (`id` and `collection` only) or Item Properties (any attributes) -may be used to sort results. It is not required that implementations support sorting over all attributes, but -implementations should return an error when attempting to sort over a field that does not support sorting. - -This fragment may be bound to either or both of -[Item Search](../../item-search) (`/search` endpoint) or -[STAC Features](../../ogcapi-features) (`/collections/{collectionId}/items` endpoint) by -advertising the relevant conformance class. - -Fields may be sorted in ascending or descending order. The syntax between GET requests and POST requests with a JSON -body vary. The `sortby` value is an array, so multiple sort fields can be defined which will be used to sort -the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`). - -**NOTE**: *This fragment may change, as our goal is to align with OGC API functionality, and sorting is currently being -worked on as part of OGC API - Records, see [this issue](https://github.com/opengeospatial/ogcapi-records/issues/22) -for the latest discussion.* - -## HTTP GET (or POST Form) - -When calling a relevant endpoint using GET (or POST with `Content-Type: application/x-www-form-urlencoded` or -`Content-Type: multipart/form-data)`, a single parameter `sortby` with a comma-separated list of item field names must -be provided. The field names may be prefixed with either "+" for ascending, or "-" for descending. If no sign is -provided before the field name, it will be assumed to be "+". - -Examples of `sortby` parameter: - -1. `GET /search?sortby=properties.created` -2. `GET /search?sortby=+properties.created` -3. `GET /search?sortby=properties.created,-id` -4. `GET /search?sortby=+properties.created,-id` -5. `GET /search?sortby=-properties.eo:cloud_cover` - -Note that examples 1 and 2 are symantically equivalent, as well as examples 3 and 4. - -## HTTP POST JSON Entity - -When calling the relevant endpoint using POST with`Content-Type: application/json`, this adds an attribute `sortby` with -an object value to the core JSON search request body. - -The syntax for the `sortby` attribute is: - -```json -{ - "sortby": [ - { - "field": "", - "direction": "" - } - ] -} -``` - -```json -{ - "sortby": [ - { - "field": "properties.created", - "direction": "asc" - }, - { - "field": "properties.eo:cloud_cover", - "direction": "desc" - }, - { - "field": "id", - "direction": "desc" - }, - { - "field": "collection", - "direction": "desc" - } - ] -} -``` diff --git a/fragments/sort/openapi.yaml b/fragments/sort/openapi.yaml deleted file mode 100644 index 3b533b85..00000000 --- a/fragments/sort/openapi.yaml +++ /dev/null @@ -1,58 +0,0 @@ -openapi: 3.0.3 -info: - title: The SpatioTemporal Asset Catalog API - Sort - description: Adds Parameter to control sorting of returns results. - version: 1.0.0-rc.1 -paths: {} -components: - parameters: - sortby: - name: sortby - x-stac-api-fragment: sort - in: query - description: |- - **Extension:** Sort - - An array of property names, prefixed by either "+" for ascending or - "-" for descending. If no prefix is provided, "+" is assumed. - required: false - schema: - type: string - example: '+id,-properties.eo:cloud_cover' - style: form - explode: false - schemas: - searchBody: - type: object - x-stac-api-fragment: sort - description: |- - **Extension:** Sort - - Sort the results. - properties: - sortby: - $ref: '#/components/schemas/sortby' - sortby: - type: array - description: | - An array of objects containing a property name and sort direction. - minItems: 1 - items: - type: object - required: - - field - - direction - properties: - field: - type: string - direction: - type: string - default: asc - enum: - - asc - - desc - example: - - field: properties.eo:cloud_cover - direction: asc - - field: id - direction: desc diff --git a/item-search/README.md b/item-search/README.md index 4d1a9d74..ab7a47d2 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -14,11 +14,6 @@ - [PUT / PATCH / DELETE](#put--patch--delete) - [Example Landing Page for STAC API - Item Search](#example-landing-page-for-stac-api---item-search) - [Extensions](#extensions) - - [Fields Extension](#fields-extension) - - [Sort Extension](#sort-extension) - - [Context Extension](#context-extension) - - [Filter Extension](#filter-extension) - - [Query Extension](#query-extension) - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.1/item-search)) - **Conformance URIs:** @@ -294,69 +289,10 @@ the [overview](../overview.md#example-landing-page) document. ## Extensions -These extensions provide additional functionality that enhances Item Search. All are specified as -[fragments](../fragments), as they are re-used by other extensions STAC API's that offer the following capabilities at -the `search` endpoint must include the relevant **conformance URI** in the `conformsTo` response at -the root (`/`) landing page, to indicate to clients that they will respond properly to requests from clients. +These extensions provide additional functionality that enhances Item Search. -### Fields Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Fields Fragment](../fragments/fields/) - -By default, the STAC search endpoint `/search` returns all attributes of each Item, as there is no way to specify -exactly those attributes that should be returned. The Fields extension to Item Search adds new functionality that -allows the client to suggest to the server which Item attributes should be included or excluded in the response, -through the use of a `fields` parameter. The full description of how this extension works can be found in the -[fields fragment](../fragments/fields/). - -### Sort Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Sort Fragment](../fragments/sort/) - -By default, the STAC search endpoint `/search` returns results in no specified order. Whatever order the results are in -is up to the implementor, and will typically default to an arbitrary order that is fastest for the underlying data store -to retrieve results. This extension adds a new parameter, `sortby`, that lets a user specify a comma separated list of -field names to sort by, with an indication of direction. It can be used with both GET and POST, the former using '+' and -'-' to indicate sort order, and the latter including a 'direction' field in JSON. The full description of the semantics -of this extension can be found in the [sort fragment](../fragments/sort). - -### Context Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Context Fragment](../fragments/context/) - -This extension is intended to augment the core ItemCollection responses from the `search` API endpoint with a -JSON object called `context` that includes the number of items `matched`, `returned` and the `limit` requested. -The full description and examples of this are found in the [context fragment](../fragments/context). - -### Filter Extension - -- **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 -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, `cql2-text` and `cql2-json`. The full details on the JSON structure are specified in the [filter -fragment](../fragments/filter/). - -### Query Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Query Fragment](../fragments/query/) - -**Note**: It is recommended that implementers implement the [Filter Extension](#filter-extension) instead, as -it offers a more robust set of operators and uses the CQL2 standard. - -The STAC API search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results -by properties. The Query extension adds a new parameter, `query`, 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, though -GET includes the exact same JSON. The full details on the JSON structure are specified in the [query -fragment](../fragments/query/). +- [Fields Extension](https://github.com/stac-api-extensions/fields/blob/main/README.mda) +- [Sort Extension](https://github.com/stac-api-extensions/sort/blob/main/README.mda) +- [Context Extension](https://github.com/stac-api-extensions/context/blob/main/README.mda) +- [Filter Extension](https://github.com/stac-api-extensions/filter/blob/main/README.mda) +- [Query Extension](https://github.com/stac-api-extensions/query/blob/main/README.mda) diff --git a/item-search/openapi.yaml b/item-search/openapi.yaml index 113452e8..6c4a49ec 100644 --- a/item-search/openapi.yaml +++ b/item-search/openapi.yaml @@ -38,20 +38,13 @@ paths: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/ids' - $ref: '#/components/parameters/collectionsArray' - # extensions - - $ref: '../fragments/fields/openapi.yaml#/components/parameters/fields' - - $ref: '../fragments/filter/openapi.yaml#/components/parameters/filter' - - $ref: '../fragments/sort/openapi.yaml#/components/parameters/sortby' responses: '200': description: A feature collection. content: application/geo+json: schema: - allOf: - - $ref: '../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection' - # extensions - - $ref: '../fragments/context/openapi.yaml#/components/schemas/itemCollection' + $ref: '../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection' text/html: schema: type: string @@ -75,12 +68,7 @@ paths: content: application/json: schema: - allOf: - - $ref: '#/components/schemas/searchBody' - # extensions - - $ref: '../fragments/fields/openapi.yaml#/components/schemas/searchBody' - - $ref: '../fragments/filter/openapi.yaml#/components/schemas/searchBody' - - $ref: '../fragments/sort/openapi.yaml#/components/schemas/searchBody' + $ref: '#/components/schemas/searchBody' responses: '200': description: A feature collection. diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 81c232c8..0b6496c5 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -9,13 +9,6 @@ - [Example Landing Page for STAC API - Features](#example-landing-page-for-stac-api---features) - [Example Collection for STAC API - Features](#example-collection-for-stac-api---features) - [Extensions](#extensions) - - [Transaction Extension](#transaction-extension) - - [Items and Collections API Version Extension](#items-and-collections-api-version-extension) - - [Fields Extension](#fields-extension) - - [Sort Extension](#sort-extension) - - [Context Extension](#context-extension) - - [Filter Extension](#filter-extension) - - [Query Extension](#query-extension) *based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)* @@ -327,95 +320,11 @@ as is typical with a static STAC Collection, there are no links here with rel va ## Extensions These extensions provide additional functionality that enhances *STAC API - Features*. -All are specified as [fragments](../fragments), as they are re-used by extensions to other STAC APIs. -STAC APIs that offer the following capabilities must include the relevant **conformance URI** in the -`conformsTo` response at the root (`/`) landing page, to indicate to clients that they will respond properly -to requests from clients. -### Transaction Extension - -- **Conformance URIs:** - - - - -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Transaction Fragment](extensions/transaction/) - -The core STAC API only supports retrieving existing Items. -The Transaction extension supports the creation, editing, and deleting of items through the use of the -POST, PUT, PATCH, and DELETE methods. The full description of how this extension works can be found in the -[transaction fragment](extensions/transaction/). - -### Items and Collections API Version Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Version](extensions/version/) - -The core API only supports semantics for creating and accessing a single version of an Item or Collection. -The Version Extension defines the API resources and semantics for creating and accessing versioned records. -It is the STAC API equivalent of [OGC API - Features - Part 4: Create, Replace, Update and Delete](https://docs.ogc.org/DRAFTS/20-002.html). - -### Fields Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Fields Fragment](../fragments/fields/) - -By default, the Items resource `/collections/{collectionId}/items` returns all attributes -of each Item, as there is no way to specify -exactly those attributes that should be returned. The Fields extension to STAC Features adds new functionality that -allows the client to suggest to the server which Item attributes should be included or excluded in the response, -through the use of a `fields` parameter. The full description of how this extension works can be found in the -[fields fragment](../fragments/fields/). - -### Sort Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Sort Fragment](../fragments/sort/) - -By default, the Items resource `/collections/{collectionId}/items` returns results in no specified order. Whatever order the results are in -is up to the implementor, and will typically default to an arbitrary order that is fastest for the underlying data store -to retrieve results. This extension adds a new parameter, `sortby`, that lets a user specify a comma separated list of -field names to sort by, with an indication of direction. It uses '+' and -'-' to indicate sort order of the list of fields. The full description of the semantics -of this extension can be found in the [sort fragment](../fragments/sort). - -### Context Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Context Fragment](../fragments/context/) - -This extension is intended to augment the core ItemCollection responses from the Items resource `/collections/{collectionId}/items` with a -JSON object called `context` that includes the number of items `matched`, `returned` and the `limit` requested. -The full description and examples of this are found in the [context fragment](../fragments/context). - -### Filter Extension - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot -- **Definition**: [STAC API - Filter Fragment](../fragments/filter/) - -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 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 - -- **Conformance URI:** -- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate -- **Definition**: [STAC API - Query Fragment](../fragments/query/) - -**Note**: It is recommended that implementers implement the [Filter Extension](#filter-extension) instead, as -it offers a more robust set of operators and uses the CQL2 standard. - -The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results -by properties. The Query extension adds a new parameter, `query`, 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, though -GET includes the exact same JSON. The full details on the JSON structure are specified in the [query -fragment](../fragments/query/). +- [Transaction Extension](https://github.com/stac-api-extensions/transaction/blob/main/README.mda) +- [Items and Collections API Version Extension](https://github.com/stac-api-extensions/version/blob/main/README.mda) +- [Fields Extension](https://github.com/stac-api-extensions/fields/blob/main/README.mda) +- [Sort Extension](https://github.com/stac-api-extensions/sort/blob/main/README.mda) +- [Context Extension](https://github.com/stac-api-extensions/context/blob/main/README.mda) +- [Filter Extension](https://github.com/stac-api-extensions/filter/blob/main/README.mda) +- [Query Extension](https://github.com/stac-api-extensions/query/blob/main/README.mda) diff --git a/ogcapi-features/extensions/version/README.md b/ogcapi-features/extensions/version/README.md deleted file mode 100644 index 043bcde4..00000000 --- a/ogcapi-features/extensions/version/README.md +++ /dev/null @@ -1,176 +0,0 @@ -# Items and Collections API Version Extension - -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance URI:** -- **Extension [Maturity Classification](../../../README.md#maturity-classification):** Proposal -- **Dependencies**: [STAC API - Features](../../README.md) - -The core API doesn't support semantics to creating and accessing different versions of an Item or Collection. -This version API extension defines the API resources and semantics for creating and accessing versioned records. -It is the STAC API equivalent of [OGC API - Features - Part 4: Create, Replace, Update and Delete](https://docs.ogc.org/DRAFTS/20-002.html). - -## Methods - -| Path | Content-Type Header | Description | -| ------------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------- | -| `GET /collections/{collectionID}/versions` | `application/json` | Returns a catalog response with links to all versions of a given collection. | -| `GET /collections/{collectionID}/versions/{versionId}` | `application/json` | Returns a collection record. | -| `GET /collections/{collectionID}/items/{featureId}/versions` | `application/json` | Returns a catalog response with links to all versions of a given item. | -| `GET /collections/{collectionID}/items/{featureId}/versions/{versionId}` | `application/json` | Returns an item record. | - -## How It Works - -When this extension is implemented, the API supports `versions` resource that list all versions -of an item or collection and provides permanent links to each version. - -The latest version of an item is accessible at `/collections/{collectionID}/items/{itemsId}`. -The record has a link with `"rel": "permalink"` that links to the permanent location of the record -which is `/collections/{collectionID}/items/{itemsId}/versions/{versionId}`. - -If the record has a previous version it also provides a link to the permanent location of that version -using `"rel": "predecessor-version"`. - -Each updated records provides the link to the previous version. - -The path `/collections/{collectionID}/items/{itemsId}/versions/` provides a catalog response with -list of links to all versions available for an item. - -## Version ID - -Version ID is a unique identifier for a version of an Item or Collection. -This extension remains agnostic about what the identifier should be. -There are many options for a versioning schema including: -- md5 hash of the record -- datetime epoch -- incrementing number -- semantic versioning - -## Link "rel" Types - -The extension uses [RFC5829](https://tools.ietf.org/html/rfc5829) rel types to link to different versions: - -| Type | Description | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| latest-version | Points to the latest version of the record. | -| version-history | Points to the list of versions. | -| predecessor-version | Points to the previous version of the document. | -| successor-version | Points to the successor version in the version history. | -| permalink | Points to the permanent location of the record. This location points to a specific version, remains accessible and will not change even when there are future versions of the record. | - -## Example - -For an item record with the id `this_is_my_id` and version of `02`, this is how the versioning works - -Request to `GET /collections/my_collection/items/this_is_my_id`: -```json -{ - "id": "this_is_my_id", - "type": "Feature", - "bbox": [], - "geometry": {}, - "properties": {}, - "links": [ - { - "rel": "self", - "href": "/collections/my_collection/items/this_is_my_id" - }, - { - "rel" : "permalink", - "href": "/collections/my_collection/items/this_is_my_id/versions/02" - }, - { - "rel": "predecessor-version", - "href": "/collections/my_collection/items/this_is_my_id/versions/01" - }, - { - "rel": "latest-version", - "href": "/collections/my_collection/items/this_is_my_id" - }, - { - "rel": "version-history", - "href": "/collections/my_collection/items/this_is_my_id/versions" - } - ] -} -``` - -Request to `GET /collections/my_collection/items/this_is_my_id/versions/02`: -```json -{ - "id": "this_is_my_id", - "type": "Feature", - "bbox": [], - "geometry": {}, - "properties": {}, - "links": [ - { - "rel": "self", - "href": "/collections/my_collection/items/this_is_my_id/versions/02" - }, - { - "rel" : "permalink", - "href": "/collections/my_collection/items/this_is_my_id/versions/02" - }, - { - "rel": "predecessor-version", - "href": "/collections/my_collection/items/this_is_my_id/versions/01" - }, - { - "rel": "latest-version", - "href": "/collections/my_collection/items/this_is_my_id" - }, - { - "rel": "version-history", - "href": "/collections/my_collection/items/this_is_my_id/versions" - } - ] -} -``` - -Request to `GET /collections/my_collection/items/this_is_my_id/versions/01`: -```json -{ - "id": "this_is_my_id", - "type": "Feature", - "bbox": [], - "geometry": {}, - "properties": {}, - "links": [ - { - "rel": "self", - "href": "/collections/my_collection/items/this_is_my_id/versions/01" - }, - { - "rel" : "permalink", - "href": "/collections/my_collection/items/this_is_my_id/versions/01" - }, - { - "rel": "predecessor-version", - "href": "/collections/my_collection/items/this_is_my_id/versions/01" - }, - { - "rel": "latest-version", - "href": "/collections/my_collection/items/this_is_my_id" - }, - { - "rel": "version-history", - "href": "/collections/my_collection/items/this_is_my_id/versions" - } - ] -} -``` - -## FAQ - -- **How do I find the latest version of an item?** - - By going to `/collections/{collectionID}/items/{itemsId}` *or* - - by looking at `"rel": "latest-version"`. - -- **How do I find the permalink of an item I'm looking at?** - - By looking at the `href` value of a link with `"rel": "permalink"` - -- **How do I find the previous versions of a record?** - - By going to `/collections/{collectionID}/items/{itemsId}/versions` - -- **How do I find the order of versions?** - - By following the `"rel": "predecessor-version"` links. diff --git a/ogcapi-features/extensions/version/openapi.yaml b/ogcapi-features/extensions/version/openapi.yaml deleted file mode 100644 index e802233b..00000000 --- a/ogcapi-features/extensions/version/openapi.yaml +++ /dev/null @@ -1,86 +0,0 @@ -openapi: 3.0.3 -info: - title: The SpatioTemporal Asset Catalog API - Item Search - version: 1.0.0-rc.1 - description: >- - This is an OpenAPI definition of the SpatioTemporal Asset Catalog API Item Search - specification. - contact: - name: STAC Specification - url: 'http://stacspec.org' - license: - name: Apache License 2.0 - url: 'http://www.apache.org/licenses/LICENSE-2.0' -tags: - - name: Version - description: This version API extension defines the API resources and semantics for creating and accessing versioned records. -paths: - '/collections/{collectionId}/versions': - get: - summary: returns a list of links for a versioned collection - description: returns a list of links for a versioned collection - tags: - - Version - operationId: getCollectionVersions - parameters: - - $ref: '../../openapi.yaml#/components/parameters/collectionId' - responses: - '200': - description: A catalog JSON definition the returns list of links of a collection versions - content: - application/json: - schema: - $ref: '../../../core/commons.yaml#/components/schemas/catalog' - '/collections/{collectionId}/versions/{versionId}': - get: - summary: returns the requested version of a collection - description: returns the requested version of a collection - tags: - - Version - operationId: getCollectionVersion - parameters: - - $ref: '../../openapi.yaml#/components/parameters/collectionId' - - $ref: '#/components/parameters/versionId' - responses: - '200': - $ref: '../../openapi.yaml#/components/responses/Collections' - '/collections/{collectionId}/items/{featureId}/versions': - get: - summary: returns a list of links for a versioned item - description: returns a list of links for a versioned item - tags: - - Version - operationId: getItemVersions - parameters: - - $ref: '../../openapi.yaml#/components/parameters/collectionId' - - $ref: '../../openapi.yaml#/components/parameters/featureId' - responses: - '200': - description: A catalog JSON definition the returns list of links of an item versions - content: - application/json: - schema: - $ref: '../../../core/commons.yaml#/components/schemas/catalog' - '/collections/{collectionId}/items/{featureId}/versions/{versionId}': - get: - summary: returns the requested version of an item - description: returns the requested version of an item - tags: - - Version - operationId: getItemVersion - parameters: - - $ref: '../../openapi.yaml#/components/parameters/collectionId' - - $ref: '../../openapi.yaml#/components/parameters/featureId' - - $ref: '#/components/parameters/versionId' - responses: - '200': - $ref: '../../openapi.yaml#/components/responses/Collections' -components: - parameters: - versionId: - name: versionId - in: path - description: local identifier of a version - required: true - schema: - type: string diff --git a/overview.md b/overview.md index ac6f7f70..abf0b8b6 100644 --- a/overview.md +++ b/overview.md @@ -142,10 +142,8 @@ have the URIs for conformance to actually resolve to machine-readable informatio | Item Search | [Item Search](item-search) | | Enables search of all STAC Item objects on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. | | STAC Features | [STAC API - Features](ogcapi-features) | | Specifies the use of OGC API - Features to serve STAC Item and Collection objects | | Collections | [Collections](collections) | | Specifies the use of a subset of OGC API - Features to serve Collection objects | -| Children | [Children](children) | | Returns child objects of a Catalog | -| Browseable | [Browseable](browseable) | | Indicates that all Items in a Catalog can be accessed through following child and item link relations | -Additional conformance classes are specified in the [STAC Extensions](extensions.md#Conformance-classes-of-extensions). +Additional conformance classes can be specified by [STAC API Extensions](extensions.md). ## Example Landing Page diff --git a/package-lock.json b/package-lock.json index 14138b41..e54156dc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "@redocly/openapi-cli": "^1.0.0-beta.94", "@stoplight/spectral-cli": "^6.4.2", "gh-pages": "^4.0.0", - "redoc-cli": "^0.13.16", + "redoc-cli": "^0.13.17", "remark-cli": "^11.0.0", "remark-gfm": "^3.0.1", "remark-lint": "^9.1.1", @@ -3841,9 +3841,9 @@ } }, "node_modules/redoc-cli": { - "version": "0.13.16", - "resolved": "https://registry.npmjs.org/redoc-cli/-/redoc-cli-0.13.16.tgz", - "integrity": "sha512-/rqkqJV1r5xgnEFh6cSmv+sZuo/TGCXKRBKZwoC0rLny5N6WGx9YykJhe1jSM4XRbK3VDfrQtOJmPCaI1ut6gg==", + "version": "0.13.17", + "resolved": "https://registry.npmjs.org/redoc-cli/-/redoc-cli-0.13.17.tgz", + "integrity": "sha512-9nlebYPiysVnuSJSoXAfEmwy8eHMsp14Rt4oRKqXaCz00O6chMnveZpzTB6APMVwA9gtNbiGO3Rbsm5PQQExzQ==", "hasShrinkwrap": true, "dependencies": { "chokidar": "^3.5.1", @@ -3854,7 +3854,7 @@ "node-libs-browser": "^2.2.1", "react": "^17.0.1", "react-dom": "^17.0.1", - "redoc": "2.0.0-rc.72", + "redoc": "2.0.0-rc.74", "styled-components": "^5.3.0", "yargs": "^17.3.1" }, @@ -4048,9 +4048,9 @@ } }, "node_modules/redoc-cli/node_modules/@redocly/openapi-core": { - "version": "1.0.0-beta.97", - "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.0.0-beta.97.tgz", - "integrity": "sha512-3WW9/6flosJuRtU3GI0Vw39OYFZqqXMDCp5TLa3EjXOb7Nm6AZTWRb3Y+I/+UdNJ/NTszVJkQczoa1t476ekiQ==", + "version": "1.0.0-beta.105", + "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.0.0-beta.105.tgz", + "integrity": "sha512-8uYDMcqBOPhFgjRlg5uetW/E2uTVVRpk+YsJhaH78ZNuzBkQP5Waw5s8P8ym6myvHs5me8l5AdniY/ePLMT5xg==", "dependencies": { "@redocly/ajv": "^8.6.4", "@types/node": "^14.11.8", @@ -4068,9 +4068,19 @@ } }, "node_modules/redoc-cli/node_modules/@redocly/openapi-core/node_modules/@types/node": { - "version": "14.18.17", - "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.17.tgz", - "integrity": "sha512-oajWz4kOajqpKJMPgnCvBajPq8QAvl2xIWoFjlAJPKGu6n7pjov5SxGE45a+0RxHDoo4ycOMoZw1SCOWtDERbw==" + "version": "14.18.22", + "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.22.tgz", + "integrity": "sha512-qzaYbXVzin6EPjghf/hTdIbnVW1ErMx8rPzwRNJhlbyJhu2SyqlvjGOY/tbUt6VFyzg56lROcOeSQRInpt63Yw==" + }, + "node_modules/redoc-cli/node_modules/@types/chokidar": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@types/chokidar/-/chokidar-2.1.3.tgz", + "integrity": "sha512-6qK3xoLLAhQVTucQGHTySwOVA1crHRXnJeLwqK6KIFkkKa2aoMFXh+WEi8PotxDtvN6MQJLyYN9ag9P6NLV81w==", + "deprecated": "This is a stub types definition. chokidar provides its own type definitions, so you do not need this installed.", + "extraneous": true, + "dependencies": { + "chokidar": "*" + } }, "node_modules/redoc-cli/node_modules/@types/eslint": { "version": "8.4.1", @@ -4098,11 +4108,30 @@ "integrity": "sha512-C6N5s2ZFtuZRj54k2/zyRhNDjJwwcViAM3Nbm8zjBpbqAdZ00mr0CFxvSKeO8Y/e03WVFLpQMdHYVfUd6SB+Hw==", "peer": true }, + "node_modules/redoc-cli/node_modules/@types/handlebars": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/@types/handlebars/-/handlebars-4.1.0.tgz", + "integrity": "sha512-gq9YweFKNNB1uFK71eRqsd4niVkXrxHugqWFQkeLRJvGjnxsLr16bYtcsG4tOFwmYi0Bax+wCkbf1reUfdl4kA==", + "deprecated": "This is a stub types definition. handlebars provides its own type definitions, so you do not need this installed.", + "extraneous": true, + "dependencies": { + "handlebars": "*" + } + }, "node_modules/redoc-cli/node_modules/@types/json-schema": { "version": "7.0.9", "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" }, + "node_modules/redoc-cli/node_modules/@types/mkdirp": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@types/mkdirp/-/mkdirp-1.0.1.tgz", + "integrity": "sha512-HkGSK7CGAXncr8Qn/0VqNtExEE+PHMWb+qlR1faHMao7ng6P3tAaoWWBMdva0gL5h4zprjIO89GJOLXsMcDm1Q==", + "extraneous": true, + "dependencies": { + "@types/node": "*" + } + }, "node_modules/redoc-cli/node_modules/@types/node": { "version": "15.12.2", "resolved": "https://registry.npmjs.org/@types/node/-/node-15.12.2.tgz", @@ -5387,7 +5416,7 @@ "node_modules/redoc-cli/node_modules/lodash.isequal": { "version": "4.5.0", "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=" + "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==" }, "node_modules/redoc-cli/node_modules/loose-envify": { "version": "1.4.0", @@ -5486,9 +5515,9 @@ "integrity": "sha1-9sAMHAsIIkblxNmd+4x8CDsrWCo=" }, "node_modules/redoc-cli/node_modules/minimatch": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.0.1.tgz", - "integrity": "sha512-nLDxIFRyhDblz3qMuq+SoRZED4+miJ/G+tdDrjkkkRnjAsBexeGpgjLEQ0blJy7rHhR2b93rhQY4SvyWu9v03g==", + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.0.tgz", + "integrity": "sha512-9TPBGGak4nHfGZsPBohm9AWg6NoT7QTCehS3BIJABslyZbzxfV78QM2Y6+i741OPZIafFAaiiEMh5OyIrJPgtg==", "dependencies": { "brace-expansion": "^2.0.1" }, @@ -6007,11 +6036,11 @@ } }, "node_modules/redoc-cli/node_modules/redoc": { - "version": "2.0.0-rc.72", - "resolved": "https://registry.npmjs.org/redoc/-/redoc-2.0.0-rc.72.tgz", - "integrity": "sha512-IX/WvVh4N3zwo4sAjnQFz6ffIUd6G47hcflxPtrpxblJaeOy0MBSzzY8f179WjssWPYcSmmndP5v0hgEXFiimg==", + "version": "2.0.0-rc.74", + "resolved": "https://registry.npmjs.org/redoc/-/redoc-2.0.0-rc.74.tgz", + "integrity": "sha512-OeOWGcbmVdfVgN//7ispiRX0fhD7Gk3tWcERugyFfP8QX/1Pttw3jRYSXmiB0i+H48zFn20K1cMppBp/qzm5xQ==", "dependencies": { - "@redocly/openapi-core": "^1.0.0-beta.97", + "@redocly/openapi-core": "^1.0.0-beta.104", "classnames": "^2.3.1", "decko": "^1.2.0", "dompurify": "^2.2.8", @@ -11750,9 +11779,9 @@ } }, "redoc-cli": { - "version": "0.13.16", - "resolved": "https://registry.npmjs.org/redoc-cli/-/redoc-cli-0.13.16.tgz", - "integrity": "sha512-/rqkqJV1r5xgnEFh6cSmv+sZuo/TGCXKRBKZwoC0rLny5N6WGx9YykJhe1jSM4XRbK3VDfrQtOJmPCaI1ut6gg==", + "version": "0.13.17", + "resolved": "https://registry.npmjs.org/redoc-cli/-/redoc-cli-0.13.17.tgz", + "integrity": "sha512-9nlebYPiysVnuSJSoXAfEmwy8eHMsp14Rt4oRKqXaCz00O6chMnveZpzTB6APMVwA9gtNbiGO3Rbsm5PQQExzQ==", "requires": { "chokidar": "^3.5.1", "handlebars": "^4.7.7", @@ -11762,7 +11791,7 @@ "node-libs-browser": "^2.2.1", "react": "^17.0.1", "react-dom": "^17.0.1", - "redoc": "2.0.0-rc.72", + "redoc": "2.0.0-rc.74", "styled-components": "^5.3.0", "yargs": "^17.3.1" }, @@ -11936,9 +11965,9 @@ } }, "@redocly/openapi-core": { - "version": "1.0.0-beta.97", - "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.0.0-beta.97.tgz", - "integrity": "sha512-3WW9/6flosJuRtU3GI0Vw39OYFZqqXMDCp5TLa3EjXOb7Nm6AZTWRb3Y+I/+UdNJ/NTszVJkQczoa1t476ekiQ==", + "version": "1.0.0-beta.105", + "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.0.0-beta.105.tgz", + "integrity": "sha512-8uYDMcqBOPhFgjRlg5uetW/E2uTVVRpk+YsJhaH78ZNuzBkQP5Waw5s8P8ym6myvHs5me8l5AdniY/ePLMT5xg==", "requires": { "@redocly/ajv": "^8.6.4", "@types/node": "^14.11.8", @@ -11953,19 +11982,13 @@ }, "dependencies": { "@types/node": { - "version": "14.18.17", - "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.17.tgz", - "integrity": "sha512-oajWz4kOajqpKJMPgnCvBajPq8QAvl2xIWoFjlAJPKGu6n7pjov5SxGE45a+0RxHDoo4ycOMoZw1SCOWtDERbw==" + "version": "14.18.22", + "resolved": "https://registry.npmjs.org/@types/node/-/node-14.18.22.tgz", + "integrity": "sha512-qzaYbXVzin6EPjghf/hTdIbnVW1ErMx8rPzwRNJhlbyJhu2SyqlvjGOY/tbUt6VFyzg56lROcOeSQRInpt63Yw==" } } }, - "@redocly/react-dropdown-aria": { - "version": "2.0.12", - "resolved": "https://registry.npmjs.org/@redocly/react-dropdown-aria/-/react-dropdown-aria-2.0.12.tgz", - "integrity": "sha512-feQEZlyBvQsbT/fvpJ4jJ5OLGaUPpnskHYDsY8DGpPymN+HUeDQrqkBEbbKRwMKidFTI2cxk2kJNNTnvdS9jyw==", - "requires": {} -}, -"@types/chokidar": { + "@types/chokidar": { "version": "https://registry.npmjs.org/@types/chokidar/-/chokidar-2.1.3.tgz", "integrity": "sha512-6qK3xoLLAhQVTucQGHTySwOVA1crHRXnJeLwqK6KIFkkKa2aoMFXh+WEi8PotxDtvN6MQJLyYN9ag9P6NLV81w==", "extraneous": true, @@ -11999,11 +12022,27 @@ "integrity": "sha512-C6N5s2ZFtuZRj54k2/zyRhNDjJwwcViAM3Nbm8zjBpbqAdZ00mr0CFxvSKeO8Y/e03WVFLpQMdHYVfUd6SB+Hw==", "peer": true }, + "@types/handlebars": { + "version": "https://registry.npmjs.org/@types/handlebars/-/handlebars-4.1.0.tgz", + "integrity": "sha512-gq9YweFKNNB1uFK71eRqsd4niVkXrxHugqWFQkeLRJvGjnxsLr16bYtcsG4tOFwmYi0Bax+wCkbf1reUfdl4kA==", + "extraneous": true, + "requires": { + "handlebars": "*" + } + }, "@types/json-schema": { "version": "7.0.9", "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" }, + "@types/mkdirp": { + "version": "https://registry.npmjs.org/@types/mkdirp/-/mkdirp-1.0.1.tgz", + "integrity": "sha512-HkGSK7CGAXncr8Qn/0VqNtExEE+PHMWb+qlR1faHMao7ng6P3tAaoWWBMdva0gL5h4zprjIO89GJOLXsMcDm1Q==", + "extraneous": true, + "requires": { + "@types/node": "*" + } + }, "@types/node": { "version": "15.12.2", "resolved": "https://registry.npmjs.org/@types/node/-/node-15.12.2.tgz", @@ -13096,7 +13135,7 @@ "lodash.isequal": { "version": "4.5.0", "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=" + "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==" }, "loose-envify": { "version": "1.4.0", @@ -13179,9 +13218,9 @@ "integrity": "sha1-9sAMHAsIIkblxNmd+4x8CDsrWCo=" }, "minimatch": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.0.1.tgz", - "integrity": "sha512-nLDxIFRyhDblz3qMuq+SoRZED4+miJ/G+tdDrjkkkRnjAsBexeGpgjLEQ0blJy7rHhR2b93rhQY4SvyWu9v03g==", + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.0.tgz", + "integrity": "sha512-9TPBGGak4nHfGZsPBohm9AWg6NoT7QTCehS3BIJABslyZbzxfV78QM2Y6+i741OPZIafFAaiiEMh5OyIrJPgtg==", "requires": { "brace-expansion": "^2.0.1" } @@ -13588,11 +13627,11 @@ } }, "redoc": { - "version": "2.0.0-rc.72", - "resolved": "https://registry.npmjs.org/redoc/-/redoc-2.0.0-rc.72.tgz", - "integrity": "sha512-IX/WvVh4N3zwo4sAjnQFz6ffIUd6G47hcflxPtrpxblJaeOy0MBSzzY8f179WjssWPYcSmmndP5v0hgEXFiimg==", + "version": "2.0.0-rc.74", + "resolved": "https://registry.npmjs.org/redoc/-/redoc-2.0.0-rc.74.tgz", + "integrity": "sha512-OeOWGcbmVdfVgN//7ispiRX0fhD7Gk3tWcERugyFfP8QX/1Pttw3jRYSXmiB0i+H48zFn20K1cMppBp/qzm5xQ==", "requires": { - "@redocly/openapi-core": "^1.0.0-beta.97", + "@redocly/openapi-core": "^1.0.0-beta.104", "classnames": "^2.3.1", "decko": "^1.2.0", "dompurify": "^2.2.8", diff --git a/package.json b/package.json index 272f0f20..9ece5932 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,7 @@ "@redocly/openapi-cli": "^1.0.0-beta.94", "@stoplight/spectral-cli": "^6.4.2", "gh-pages": "^4.0.0", - "redoc-cli": "^0.13.16", + "redoc-cli": "^0.13.17", "remark-cli": "^11.0.0", "remark-lint": "^9.1.1", "remark-gfm": "^3.0.1",