Merge pull request #4 from stac-api-extensions/pv/clarify-sortable-names

clarify names for sortables

.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.

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

README.md

@@ -1,29 +1,38 @@
-# STAC API - Sort Fragment
+# STAC API - Sort Extension
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml)
 - **Conformance Classes:** 
   - **STAC API - Item Search** binding: <https://api.stacspec.org/v1.0.0-rc.1/item-search#sort>
   - **STAC API - Features** binding: <https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features#sort>
-- **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.*