Skip to content

Add sortables and collection search #7 #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 4, 2025
Merged

Add sortables and collection search #7 #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be4ecec
Add sortables and collection search #7
m-mohr May 9, 2025
612cb92
Update README.md
m-mohr May 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,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]

### Added

- Sortables (e.g. endpoint `GET /sortables`)
- Sort for Collections (i.e. Collection Search)

## [v1.0.0] - 2023-09-28

### Changed
Expand Down
75 changes: 57 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
- [Overview](#overview)
- [HTTP GET](#http-get)
- [HTTP POST JSON Entity](#http-post-json-entity)
- [Sortables](#sortables)

## Overview

Expand All @@ -12,11 +13,13 @@
- **Conformance Classes:**
- **STAC API - Item Search** binding: <https://api.stacspec.org/v1.0.0/item-search#sort>
- **STAC API - Features** binding: <https://api.stacspec.org/v1.0.0/ogcapi-features#sort>
- **Scope:** STAC API - Features, STAC API - Item Search
- **STAC API - Collection Search** binding: <https://api.stacspec.org/v1.0.0-rc.1/collection-search#sort>
- **Scope:** STAC API - Features, STAC API - Item Search, STAC API - Collection Search
- **[Extension Maturity Classification](https://github.com/radiantearth/stac-api-spec/tree/main/README.md#maturity-classification):** Stable
- **Dependencies:**
- [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search)
- [STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search)
- [STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features)
- [STAC API - Collection Search](https://github.com/stac-api-extensions/collection-search/tree/v1.0.0-rc.1)
- **Owner**: @philvarner

This specification defines a new parameter, `sortby`, that allows the user to define the fields by which
Expand All @@ -25,27 +28,24 @@ Only string, numeric, and datetime attributes of Item (`id` and `collection` onl
may be used to sort results.

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/item-search) (`/search` endpoint) or
[STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features)
(`/collections/{collectionId}/items` endpoint) by advertising the relevant conformance class.
implementations should either implement Sortables or just return a 400 Bad Request status code
when attempting to sort over a field name that does not support sorting.
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 any of the following endpoints by advertising the relevant conformance class:

- [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/item-search)
(`/search` endpoint),
- [STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features)
(`/collections/{collectionId}/items` endpoint)
- [STAC API - Collection Search](https://github.com/stac-api-extensions/collection-search/tree/v1.0.0-rc.1)
(`/collections` endpoint)

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

## HTTP GET

When calling a relevant endpoint using GET, a single parameter `sortby` with a comma-separated list of item field names must
Expand Down Expand Up @@ -103,3 +103,42 @@ The syntax for the `sortby` attribute is:
]
}
```

## Sortables

Additional endpoints that provide so called "Sortables" support clients that want to discover the list of resource
properties with their types and constraints that may be used to sort resources.

These Sortables endpoints return lists of properties (or aliases) that can be used in the `sortby` parameter.
It returns a JSON Schema that defines the properties allowed in `sortby`.
The precise definition of this can be found in the
[OGC API - Features - Part 5: Schemas](https://portal.ogc.org/files/108199#rc_sortables).

In particular:

- No property SHALL be of type "object" or "array".
- No property SHALL be a spatial property.
- 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.
- If `additionalProperties` is set to false, property references that are not explicitly declared in the sortables schema SHALL result in a 400 response.

All Sortables endpoints SHALL be referenced with a link with the link relation type
`http://www.opengis.net/def/rel/ogc/1.0/sortables`.

| Sortables Endpoint | Endpoint linking to the Sortables Endpoint | Conformance class | Applicable `sortby` endpoints |
| ----------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------- |
| `GET /sortables` | `GET /` | `https://api.stacspec.org/v1.0.0/item-search#sortables` | `GET /search` and `POST /search` |
| `GET /collections/{collectionId}/sortables` | `GET /collections/{collectionId}` | `http://www.opengis.net/spec/ogcapi-features-5/1.0/conf/sortables` | `GET /collections/{collectionId}/items` |
| `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` |

An example for a link to the sortables endpoint could be:

```json
{
"href": "https://stac.example/sortables",
"type": "application/schema+json",
"rel": "http://www.opengis.net/def/rel/ogc/1.0/sortables",
"title": "Sortables"
}
```

For an example of a sortables endpoint response, please see the [openapi.yaml](openapi.yaml).
118 changes: 117 additions & 1 deletion openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,113 @@ info:
license:
name: Apache License 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0'
paths: {}
tags:
- name: Sort Extension
description: |
An extension to the STAC API that allows sorting of results based on specified properties.
paths:
/sortables:
get:
summary: Sortables
operationId: getSortables
description: |-
This endpoint returns a list of properties (or aliases) that can be used in the `sortby` parameter
for the cross-collection item search (i.e. `GET /search` and `POST /search`).
It returns a JSON Schema that defines the properties allowed in `sortby`.
The precise definition of this can be found in the OGC API - Features - Part 5: Schemas.
tags:
- Sort Extension
responses:
"200":
$ref: "#/components/responses/Sortables"
default:
$ref: "#/components/responses/Error"
/collections/{collectionId}/sortables:
get:
summary: Sortables for Item lists of a specific Collection
operationId: getCollectionForCollection
description: |-
This endpoint returns a list of properties (or aliases) that can be used in the `sortby` parameter
for the item lists of a collection (i.e. `GET /collections/{collectionId}/items`).
It returns a JSON Schema that defines the properties allowed in `sortby`.
The precise definition of this can be found in the OGC API - Features - Part 5: Schemas.
tags:
- Sort Extension
parameters:
- in: path
name: collectionId
schema:
type: string
required: true
description: ID of Collection
responses:
"200":
$ref: "#/components/responses/Sortables"
default:
$ref: "#/components/responses/Error"
components:
responses:
Sortables:
description: A JSON Schema defining the properties allowed in `sortby`.
content:
application/schema+json:
schema:
type: object
properties:
$schema:
type: string
format: uri
enum:
- https://json-schema.org/draft/2020-12/schema
$id:
type: string
format: uri
type:
type: string
enum:
- object
properties:
type: object
additionalProperties:
type: object
required:
- type
properties:
type:
type: string
title:
type: string
description:
type: string
additionalProperties: true
additionalProperties:
description: |-
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.

If `additionalProperties` is set to `false`, property references that are not explicitly declared in the sortables schema SHALL result in a 400 response.
type: boolean
default: true
example:
$schema: https://json-schema.org/draft/2020-12/schema
$id: https://example.com/sortables
title: Sortables
type: object
properties:
id:
type: string
title:
type: string
datetime:
type: string
format: date-time
eo:cloud_cover:
type: number
Error:
description: An error occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/exception"
parameters:
sortby:
name: sortby
Expand Down Expand Up @@ -62,3 +167,14 @@ components:
direction: asc
- field: id
direction: desc
exception:
type: object
description: |-
Information about the exception: an error code plus an optional description.
required:
- code
properties:
code:
type: string
description:
type: string