From 164bddae0ee7045ce441d632efed6bfb7ac7d9fd Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Tue, 7 Sep 2021 15:45:11 -0400 Subject: [PATCH] support binding sort, fields, and context extension to STAC Features --- CHANGELOG.md | 3 +++ extensions.md | 3 +++ fragments/context/README.md | 17 ++++++++++------ fragments/fields/README.md | 14 ++++++++++--- fragments/sort/README.md | 10 +++++++++- ogcapi-features/README.md | 39 +++++++++++++++++++++++++++++++++++++ 6 files changed, 76 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a08e4299..958226f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Support binding Sort, Fields, and Context Extensions to STAC Features items resource + endpoint (`/collections/{collection_id}/items`) + ### Changed ### Deprecated diff --git a/extensions.md b/extensions.md index 035a93bb..74bd1d52 100644 --- a/extensions.md +++ b/extensions.md @@ -67,6 +67,7 @@ the service supports. This are listed at the top of each extension description, - [Fields](item-search/README.md#fields) - + - - [Filter](item-search/README.md#filter) - - @@ -75,8 +76,10 @@ the service supports. This are listed at the top of each extension description, - - [Context](item-search/README.md#context) - + - - [Sort](item-search/README.md#sort) - + - - [Transaction](ogcapi-features/extensions/transaction/README.md) - - [Items and Collections API Version](ogcapi-features/extensions/version/README.md) diff --git a/fragments/context/README.md b/fragments/context/README.md index 1074e085..1564f82c 100644 --- a/fragments/context/README.md +++ b/fragments/context/README.md @@ -1,7 +1,9 @@ # STAC API - Context Fragment - **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Class:** +- **Conformance Classes:** + - Item Search binding: + - STAC Features binding: - **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot - **Dependents:** - [Item Search](../../item-search) @@ -9,11 +11,14 @@ 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. -**Note**: *This fragment is currently scoped to just the STAC-specific functionality such as [STAC Item Search](../../item-search). -OGC API has their 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 recommended to use STAC Context in the cross-collection `search` endpoint, and follow the OGC API way when -implementing OGC API - Features.* +This fragment may be bound to either or both of +[Item Search](../../item-search) (`/search` endpoint) or +[STAC Features](../../ogcapi-features) (`/collections/{collection_id}/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) diff --git a/fragments/fields/README.md b/fragments/fields/README.md index c140bb44..9cc0051f 100644 --- a/fragments/fields/README.md +++ b/fragments/fields/README.md @@ -1,14 +1,22 @@ # STAC API - Fields Fragment - **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Class:** +- **Conformance Classes:** + - Item Search binding: + - STAC Features binding: - **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot - **Dependents:** - [Item Search](../../item-search) + - [STAC Features](../../ogcapi-features) -STAC API by default returns everything within an item. But Item objects can have hundreds of fields, or incredibly large +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. +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/{collection_id}/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 diff --git a/fragments/sort/README.md b/fragments/sort/README.md index dd531bb3..a50ca2dd 100644 --- a/fragments/sort/README.md +++ b/fragments/sort/README.md @@ -1,16 +1,24 @@ # STAC API - Sort Fragment - **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance Class:** +- **Conformance Class:** + - Item Search binding: + - STAC Features binding: - **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot - **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/{collection_id}/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`). diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 016d7a2a..b6fe864a 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -9,6 +9,9 @@ - [Extensions](#extensions) - [Transaction](#transaction) - [Items and Collections API Version Extension](#items-and-collections-api-version-extension) + - [Fields](#fields) + - [Sort](#sort) + - [Context](#context) *based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)* @@ -261,3 +264,39 @@ POST, PUT, PATCH, and DELETE methods. The full description of how this extension 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 + +- **Conformance URI:** +- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Definition**: [STAC API - Fields Fragment](../fragments/fields/) + +By default, the Items resource `/collections/{collection_id}/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 + +- **Conformance URI:** +- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Definition**: [STAC API - Sort Fragment](../fragments/sort/) + +By default, the Items resource `/collections/{collection_id}/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 + +- **Conformance URI:** +- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Definition**: [STAC API - Context Fragment](../fragments/context/) + +This extension is intended to augment the core ItemCollection responses from the Items resource `/collections/{collection_id}/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).