Merge pull request #208 from philvarner/ccs-for-binding-sort-and-fiel…

…ds-to-features

support binding sort, fields, and context extension to STAC Features

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Support binding Sort, Fields, and Context Extensions to STAC Features items resource
+  endpoint (`/collections/{collection_id}/items`)
+
 ### Changed
 
 - The required Link Relations and endpoints for each conformance class now use the wording of 'shall' 

extensions.md

@@ -67,6 +67,7 @@ the service supports. This are listed at the top of each extension description,
 
 - [Fields](item-search/README.md#fields)
   - <https://api.stacspec.org/v1.0.0-beta.4/item-search#fields>
+  - <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#fields>
 - [Filter](item-search/README.md#filter)
   - <https://api.stacspec.org/v1.0.0-beta.4/item-search#filter:filter>
   - <https://api.stacspec.org/v1.0.0-beta.4/item-search#filter:simple-cql>
@@ -75,8 +76,10 @@ the service supports. This are listed at the top of each extension description,
   - <https://api.stacspec.org/v1.0.0-beta.4/item-search#filter:cql-json>
 - [Context](item-search/README.md#context)
   - <https://api.stacspec.org/v1.0.0-beta.4/item-search#context>
+  - <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#context>
 - [Sort](item-search/README.md#sort)
   - <https://api.stacspec.org/v1.0.0-beta.4/item-search#sort>
+  - <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#sort>
 - [Transaction](ogcapi-features/extensions/transaction/README.md)
   - <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features/extensions/transaction>
 - [Items and Collections API Version](ogcapi-features/extensions/version/README.md)

fragments/context/README.md

@@ -1,19 +1,24 @@
 # STAC API - Context Fragment
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml)
-- **Conformance Class:** <https://api.stacspec.org/v1.0.0-beta.4/item-search#context>
+- **Conformance Classes:** 
+  - Item Search binding: <https://api.stacspec.org/v1.0.0-beta.4/item-search#context>
+  - STAC Features binding: <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#context>
 - **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
 - **Dependents:**
   - [Item Search](../../item-search)
 
 This extension is intended to augment the core [ItemCollection](../itemcollection/README.md)
 object when the ItemCollection is the result of a search, for example, from calling the `/search` API endpoint.
 
-**Note**: *This fragment is currently scoped to just the STAC-specific functionality such as [STAC Item Search](../../item-search).
-OGC API has their own way returning `numberMatched` and `numberReturned` at the top level, instead of in a context
-object. We are hoping to [align](https://github.com/opengeospatial/ogcapi-common/issues/82), but until then it
-is recommended to use STAC Context in the cross-collection `search` endpoint, and follow the OGC API way when
-implementing OGC API - Features.*
+This fragment may be bound to either or both of 
+[Item Search](../../item-search) (`/search` endpoint) or
+[STAC Features](../../ogcapi-features) (`/collections/{collection_id}/items` endpoint) by
+advertising the relevant conformance class. 
+
+**Note**: OGC API Features - Part 1 has its own way returning `numberMatched` and `numberReturned` at the top level, instead of in a context
+object. We are hoping to [align](https://github.com/opengeospatial/ogcapi-common/issues/82), but until then, it
+is required to implement both when implementing STAC Features.
 
 - [Example](examples/example.json)
 - [JSON Schema](json-schema/schema.json)

fragments/fields/README.md

@@ -1,14 +1,22 @@
 # STAC API - Fields Fragment
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml)
-- **Conformance Class:** <https://api.stacspec.org/v1.0.0-beta.4/item-search#fields>
+- **Conformance Classes:** 
+  - Item Search binding: <https://api.stacspec.org/v1.0.0-beta.4/item-search#fields>
+  - STAC Features binding: <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#fields>
 - **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
 - **Dependents:**
   - [Item Search](../../item-search)
+  - [STAC Features](../../ogcapi-features)
 
-STAC API by default returns everything within an item. But Item objects can have hundreds of fields, or incredibly large
+STAC API by default returns every attribute in an item. However, Item objects can have hundreds of fields, or incredibly large
 geometries, and even smaller Item objects can get big when millions are requested but not all information is used. This
-fragment provides a mechanism for clients to request that servers to explicitly include or exclude certain fields. 
+fragment provides a mechanism for clients to request that servers to explicitly include or exclude certain fields.
+
+This fragment may be bound to either or both of 
+[Item Search](../../item-search) (`/search` endpoint) or
+[STAC Features](../../ogcapi-features) (`/collections/{collection_id}/items` endpoint) by
+advertising the relevant conformance class. 
 
 When used in a POST request with `Content-Type: application/json`, this adds an attribute `fields` with 
 an object value to the core JSON search request body. The `fields` object contains two attributes with string array 

fragments/sort/README.md

@@ -1,16 +1,24 @@
 # STAC API - Sort Fragment
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml)
-- **Conformance Class:** <https://api.stacspec.org/v1.0.0-beta.4/item-search#sort>
+- **Conformance Class:** 
+  - Item Search binding: <https://api.stacspec.org/v1.0.0-beta.4/item-search#sort>
+  - STAC Features binding: <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#sort>
 - **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
 - **Dependents:**
   - [Item Search](../../item-search)
+  - [STAC Features](../../ogcapi-features)
 
 This defines a new parameter, `sortby`, that allows the user to define 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. 
 
+This fragment may be bound to either or both of 
+[Item Search](../../item-search) (`/search` endpoint) or
+[STAC Features](../../ogcapi-features) (`/collections/{collection_id}/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`).

ogcapi-features/README.md

@@ -9,6 +9,9 @@
   - [Extensions](#extensions)
     - [Transaction](#transaction)
     - [Items and Collections API Version Extension](#items-and-collections-api-version-extension)
+    - [Fields](#fields)
+    - [Sort](#sort)
+    - [Context](#context)
 
 *based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)*
 
@@ -261,3 +264,39 @@ POST, PUT, PATCH, and DELETE methods. The full description of how this extension
 The core API only supports semantics for creating and accessing a single version of an Item or Collection.
 The Version Extension defines the API resources and semantics for creating and accessing versioned records.
 It is the STAC API equivalent of [OGC API - Features - Part 4: Create, Replace, Update and Delete](https://docs.ogc.org/DRAFTS/20-002.html).
+
+### Fields
+
+- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#fields>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Definition**: [STAC API - Fields Fragment](../fragments/fields/)
+
+By default, the Items resource `/collections/{collection_id}/items` returns all attributes 
+of each Item, as there is no way to specify 
+exactly those attributes that should be returned. The Fields extension to STAC Features adds new functionality that 
+allows the client to suggest to the server which Item attributes should be included or excluded in the response, 
+through the use of a `fields` parameter. The full description of how this extension works can be found in the 
+[fields fragment](../fragments/fields/). 
+
+### Sort
+
+- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#sort>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Definition**: [STAC API - Sort Fragment](../fragments/sort/)
+
+By default, the Items resource `/collections/{collection_id}/items` returns results in no specified order. Whatever order the results are in 
+is up to the implementor, and will typically default to an arbitrary order that is fastest for the underlying data store 
+to retrieve results. This extension adds a new parameter, `sortby`, that lets a user specify a comma separated list of
+field names to sort by, with an indication of direction. It uses '+' and
+'-' to indicate sort order of the list of fields. The full description of the semantics
+of this extension can be found in the [sort fragment](../fragments/sort).
+
+### Context
+
+- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.4/ogcapi-features#context>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Definition**: [STAC API - Context Fragment](../fragments/context/)
+
+This extension is intended to augment the core ItemCollection responses from the Items resource `/collections/{collection_id}/items`  with a
+JSON object called `context` that includes the number of items `matched`, `returned` and the `limit` requested.
+The full description and examples of this are found in the [context fragment](../fragments/context).