Skip to content

Commit e17c3c5

Browse files
committed
clarify names for sortables
1 parent 8010b93 commit e17c3c5

1 file changed

Lines changed: 17 additions & 8 deletions

File tree

README.md

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,35 @@
44
- **Conformance Classes:**
55
- **STAC API - Item Search** binding: <https://api.stacspec.org/v1.0.0-rc.1/item-search#sort>
66
- **STAC API - Features** binding: <https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features#sort>
7-
- **Extension [Maturity Classification](https://github.com/radiantearth/stac-api-spec/README.md#maturity-classification):** Candidate
7+
- **Extension [Maturity Classification](https://github.com/radiantearth/stac-api-spec/blob/main/README.md#maturity-classification):** Candidate
88
- **Dependencies:**
99
- [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search)
1010
- [STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search)
1111

12-
This defines a new parameter, `sortby`, that allows the user to define fields by which to sort results.
12+
This specification defines a new parameter, `sortby`, that allows the user to define the fields by which
13+
to sort results.
1314
Only string, numeric, and datetime attributes of Item (`id` and `collection` only) or Item Properties (any attributes)
14-
may be used to sort results. It is not required that implementations support sorting over all attributes, but
15-
implementations should return an error when attempting to sort over a field that does not support sorting.
15+
may be used to sort results.
1616

17-
This fragment may be bound to either or both of
17+
It is not required that implementations support sorting over all attributes, but
18+
implementations should return a 400 Bad Request status code when attempting to sort over a field name that does
19+
not support sorting.
20+
This specification does not yet require the implementation of an "-ables" endpoint (like CQL2 does for queryables)
21+
that defines the names of the
22+
fields that can be sorted over, so implementations must provide this out-of-band. Implementers may choose to require
23+
fields in Item Properties to be prefixed with `properties.` or not, or support use of both the prefixed and non-prefixed
24+
name, e.g., `properties.datetime` or `datetime`.
25+
26+
Sort behavior may be bound to either or both of
1827
[STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search) (`/search` endpoint) or
19-
[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/ogcapi-features) (`/collections/{collectionId}/items` endpoint) by
20-
advertising the relevant conformance class.
28+
[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/ogcapi-features)
29+
(`/collections/{collectionId}/items` endpoint) by advertising the relevant conformance class.
2130

2231
Fields may be sorted in ascending or descending order. The syntax between GET requests and POST requests with a JSON
2332
body vary. The `sortby` value is an array, so multiple sort fields can be defined which will be used to sort
2433
the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`).
2534

26-
**NOTE**: *This fragment may change, as our goal is to align with OGC API functionality, and sorting is currently being
35+
**NOTE**: *This specification may change, as our goal is to align with OGC API functionality, and sorting is currently being
2736
worked on as part of OGC API - Records, see [this issue](https://github.com/opengeospatial/ogcapi-records/issues/22)
2837
for the latest discussion.*
2938

0 commit comments

Comments
 (0)