You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search)
19
-
-[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search)
21
+
-[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features)
22
+
-[STAC API - Collection Search](https://github.com/stac-api-extensions/collection-search/tree/v1.0.0-rc.1)
20
23
-**Owner**: @philvarner
21
24
22
25
This specification defines a new parameter, `sortby`, that allows the user to define the fields by which
@@ -25,27 +28,24 @@ Only string, numeric, and datetime attributes of Item (`id` and `collection` onl
25
28
may be used to sort results.
26
29
27
30
It is not required that implementations support sorting over all attributes, but
28
-
implementations should return a 400 Bad Request status code when attempting to sort over a field name that does
29
-
not support sorting.
30
-
This specification does not yet require the implementation of an "-ables" endpoint (like CQL2 does for queryables)
31
-
that defines the names of the
32
-
fields that can be sorted over, so implementations must provide this out-of-band. Implementers may choose to require
33
-
fields in Item Properties to be prefixed with `properties.` or not, or support use of both the prefixed and non-prefixed
34
-
name, e.g., `properties.datetime` or `datetime`.
35
-
36
-
Sort behavior may be bound to either or both of
37
-
[STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search) (`/search` endpoint) or
38
-
[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features)
39
-
(`/collections/{collectionId}/items` endpoint) by advertising the relevant conformance class.
31
+
implementations should either implement Sortables or just return a 400 Bad Request status code
32
+
when attempting to sort over a field name that does not support sorting.
33
+
Implementers may choose to require fields in Item Properties to be prefixed with `properties.` or not,
34
+
or support use of both the prefixed and non-prefixed name, e.g., `properties.datetime` or `datetime`.
35
+
36
+
Sort behavior may be bound to any of the following endpoints by advertising the relevant conformance class:
37
+
38
+
-[STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search)
39
+
(`/search` endpoint),
40
+
-[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features)
41
+
(`/collections/{collectionId}/items` endpoint)
42
+
-[STAC API - Collection Search](https://github.com/stac-api-extensions/collection-search/tree/v1.0.0-rc.1)
43
+
(`/collections` endpoint)
40
44
41
45
Fields may be sorted in ascending or descending order. The syntax between GET requests and POST requests with a JSON
42
46
body vary. The `sortby` value is an array, so multiple sort fields can be defined which will be used to sort
43
47
the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`).
44
48
45
-
**NOTE**: *This specification may change, as our goal is to align with OGC API functionality, and sorting is currently being
46
-
worked on as part of OGC API - Records, see [this issue](https://github.com/opengeospatial/ogcapi-records/issues/22)
47
-
for the latest discussion.*
48
-
49
49
## HTTP GET
50
50
51
51
When calling a relevant endpoint using GET, a single parameter `sortby` with a comma-separated list of item field names must
@@ -103,3 +103,42 @@ The syntax for the `sortby` attribute is:
103
103
]
104
104
}
105
105
```
106
+
107
+
## Sortables
108
+
109
+
Additional endpoints that provide so called "Sortables" support clients that want to discover the list of resource
110
+
properties with their types and constraints that may be used to sort resources.
111
+
112
+
These Sortables endpoints return lists of properties (or aliases) that can be used in the `sortby` parameter.
113
+
It returns a JSON Schema that defines the properties allowed in `sortby`.
114
+
The precise definition of this can be found in the
115
+
[OGC API - Features - Part 5: Schemas](https://portal.ogc.org/files/108199#rc_sortables).
116
+
117
+
In particular:
118
+
119
+
- No property SHALL be of type "object" or "array".
120
+
- No property SHALL be a spatial property.
121
+
- If `additionalProperties` is not included or has the default value true, any property name is valid in a sorting expression on the collection that is evaluated by the server and the property reference SHALL evaluate to null, if the property does not exist for a resource.
122
+
- If `additionalProperties` is set to false, property references that are not explicitly declared in the sortables schema SHALL result in a 400 response.
123
+
124
+
All Sortables endpoints SHALL be referenced with a link with the link relation type
|`GET /...` (*Endpoint name to be chosen by implementation*) |`GET /collections`|`https://api.stacspec.org/v1.0.0-rc.1/collection-search#sortables`|`GET /collections/{collectionId}/items`|
132
+
133
+
An example for a link to the sortables endpoint could be:
Copy file name to clipboardExpand all lines: openapi.yaml
+117-1Lines changed: 117 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,113 @@ info:
9
9
license:
10
10
name: Apache License 2.0
11
11
url: 'http://www.apache.org/licenses/LICENSE-2.0'
12
-
paths: {}
12
+
tags:
13
+
- name: Sort Extension
14
+
description: |
15
+
An extension to the STAC API that allows sorting of results based on specified properties.
16
+
paths:
17
+
/sortables:
18
+
get:
19
+
summary: Sortables
20
+
operationId: getSortables
21
+
description: |-
22
+
This endpoint returns a list of properties (or aliases) that can be used in the `sortby` parameter
23
+
for the cross-collection item search (i.e. `GET /search` and `POST /search`).
24
+
It returns a JSON Schema that defines the properties allowed in `sortby`.
25
+
The precise definition of this can be found in the OGC API - Features - Part 5: Schemas.
26
+
tags:
27
+
- Sort Extension
28
+
responses:
29
+
"200":
30
+
$ref: "#/components/responses/Sortables"
31
+
default:
32
+
$ref: "#/components/responses/Error"
33
+
/collections/{collectionId}/sortables:
34
+
get:
35
+
summary: Sortables for Item lists of a specific Collection
36
+
operationId: getCollectionForCollection
37
+
description: |-
38
+
This endpoint returns a list of properties (or aliases) that can be used in the `sortby` parameter
39
+
for the item lists of a collection (i.e. `GET /collections/{collectionId}/items`).
40
+
It returns a JSON Schema that defines the properties allowed in `sortby`.
41
+
The precise definition of this can be found in the OGC API - Features - Part 5: Schemas.
42
+
tags:
43
+
- Sort Extension
44
+
parameters:
45
+
- in: path
46
+
name: collectionId
47
+
schema:
48
+
type: string
49
+
required: true
50
+
description: ID of Collection
51
+
responses:
52
+
"200":
53
+
$ref: "#/components/responses/Sortables"
54
+
default:
55
+
$ref: "#/components/responses/Error"
13
56
components:
57
+
responses:
58
+
Sortables:
59
+
description: A JSON Schema defining the properties allowed in `sortby`.
60
+
content:
61
+
application/schema+json:
62
+
schema:
63
+
type: object
64
+
properties:
65
+
$schema:
66
+
type: string
67
+
format: uri
68
+
enum:
69
+
- https://json-schema.org/draft/2020-12/schema
70
+
$id:
71
+
type: string
72
+
format: uri
73
+
type:
74
+
type: string
75
+
enum:
76
+
- object
77
+
properties:
78
+
type: object
79
+
additionalProperties:
80
+
type: object
81
+
required:
82
+
- type
83
+
properties:
84
+
type:
85
+
type: string
86
+
title:
87
+
type: string
88
+
description:
89
+
type: string
90
+
additionalProperties: true
91
+
additionalProperties:
92
+
description: |-
93
+
If `additionalProperties` is not included or has the default value `true`, any property name is valid in a sorting expression on the collection that is evaluated by the server and the property reference SHALL evaluate to `null`, if the property does not exist for a resource.
94
+
95
+
If `additionalProperties` is set to `false`, property references that are not explicitly declared in the sortables schema SHALL result in a 400 response.
0 commit comments