From e17c3c5cb4ee7227f7f217ab04f4de1b0d7eafe4 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Thu, 6 Oct 2022 08:20:08 -0400 Subject: [PATCH 1/3] clarify names for sortables --- README.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index fd30cd7..1cc56a0 100644 --- a/README.md +++ b/README.md @@ -4,26 +4,35 @@ - **Conformance Classes:** - **STAC API - Item Search** binding: - **STAC API - Features** binding: -- **Extension [Maturity Classification](https://github.com/radiantearth/stac-api-spec/README.md#maturity-classification):** Candidate +- **Extension [Maturity Classification](https://github.com/radiantearth/stac-api-spec/blob/main/README.md#maturity-classification):** Candidate - **Dependencies:** - [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search) - [STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search) -This defines a new parameter, `sortby`, that allows the user to define fields by which to sort results. +This specification defines a new parameter, `sortby`, that allows the user to define the 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. +may be used to sort results. -This fragment may be bound to either or both of +It is not required that implementations support sorting over all attributes, but +implementations should return a 400 Bad Request status code when attempting to sort over a field name that does +not support sorting. +This specification does not yet require the implementation of an "-ables" endpoint (like CQL2 does for queryables) +that defines the names of the +fields that can be sorted over, so implementations must provide this out-of-band. Implementers may choose to require +fields in Item Properties to be prefixed with `properties.` or not, or support use of both the prefixed and non-prefixed +name, e.g., `properties.datetime` or `datetime`. + +Sort behavior may be bound to either or both of [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search) (`/search` endpoint) or -[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/ogcapi-features) (`/collections/{collectionId}/items` endpoint) by -advertising the relevant conformance class. +[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/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 +**NOTE**: *This specification 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.* From f865fd880db259da1a8ba1f67a47307869022538 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Thu, 6 Oct 2022 08:23:26 -0400 Subject: [PATCH 2/3] changelog --- .github/pull_request_template.md | 1 - CHANGELOG.md | 7 +++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 77c127f..17df325 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,5 +10,4 @@ **PR Checklist:** - [ ] This PR has **no** breaking changes. -- [ ] This PR does not make any changes to the core spec in the `stac-spec` directory (these are included as a subtree and should be updated directly in [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec)) - [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-api-spec/blob/main/CHANGELOG.md) **or** a CHANGELOG entry is not required. diff --git a/CHANGELOG.md b/CHANGELOG.md index 39975cd..fd2dc31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ 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 + +### Fixed + +- Clarify that the names for sortable fields can either be prefixed by `properties` or not. + ## [v1.0.0-rc.1] - 2022-03-17 ### Added From a75827204c18211d3a26f3f7662a29073d76a788 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Thu, 6 Oct 2022 08:41:17 -0400 Subject: [PATCH 3/3] fix name of extension in readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1cc56a0..82e047f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# STAC API - Sort Fragment +# STAC API - Sort Extension - **OpenAPI specification:** [openapi.yaml](openapi.yaml) - **Conformance Classes:**