Add sortables and collection search #7

CHANGELOG.md

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

README.md

@@ -4,6 +4,7 @@
   - [Overview](#overview)
   - [HTTP GET](#http-get)
   - [HTTP POST JSON Entity](#http-post-json-entity)
+  - [Sortables](#sortables)
 
 ## Overview
 
@@ -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
@@ -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
@@ -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).

openapi.yaml

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