Merge pull request #72 from radiantearth/fragments

cholmes · web-flow · commit ae0d046da6b0 · 2020-12-04T11:18:26.000-08:00
Fragments
diff --git a/fragments/README.md b/fragments/README.md
@@ -1 +1,19 @@
 # STAC API - Fragments
+
+This directory contains reusable OpenAPI fragments that are used by other capabilities. They tend to 
+be common API components such as parameters that get mixed in to various endpoints.
+They are kept in this separate fragment directory as they are not specific to any extension and are meant 
+to be re-used when drafting new API extensions.
+
+For example '[sort](sort/)' introduces a parameter (`sortby`) that can be used by both [item-search](../item-search) 
+at the `/search` endpoint, and by [features](../ogcapi-features) in any of its `items` endpoints. To keep
+things clean we specify a conformance class for each, so clients can know exactly what to expect. Each
+conformance class is specified in the relevant folder as an 'extension' to the main capability. But their
+semantics are exactly the same, so we put the shared openapi definition in this `fragments` directory.
+
+| Fragment Name                          | Description                                                                |
+|----------------------------------------|----------------------------------------------------------------------------|
+| [Fields](fields/README.md)   | Adds parameter to control which fields are returned in the response.       |
+| [Query](query/README.md)     | Adds parameter to compare properties and only return the items that match  |
+| [Context](context/README.md) | Adds search related metadata (context) to GeoJSON Responses.               |
+| [Sort](sort/README.md)       | Adds Parameter to control sorting of returns results.                      | 
diff --git a/fragments/context/README.md b/fragments/context/README.md
@@ -8,7 +8,7 @@
 This extension is intended to augment the core ItemCollection
 object when the ItemCollection is the result of a search, for example, from calling the `/search` API endpoint.
 
-**Note**: *This extension is currently scoped to just the [STAC Item Search](../../item-search) functionality.
+**Note**: *This extension is currently only used by [STAC Item Search](../../item-search) functionality.
 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
diff --git a/fragments/fields/README.md b/fragments/fields/README.md
@@ -5,15 +5,15 @@
 - **Dependents:**
   - [Item Search](../../item-search)
 
-By default, the STAC search endpoint `/search` returns all attributes of each Item, as there is no way to specify 
-exactly those attributes that should be returned. The Fields API Extension adds new functionality that allows the 
-client to suggest to the server which Item attributes should be included or excluded in the response. 
+STAC API by default returns everything within an item. But Items can have hundreds of fields, or incredibly large
+geometries, and even smaller Items 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. 
 
-When calling `/search` using POST with`Content-Type: application/json`, this extension adds an attribute `fields` with 
+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 
 values, `include` and `exclude`.
 
-When calling `/search` using GET or POST with `Content-Type: application/x-www-form-urlencoded` or 
+When used with GET or POST with `Content-Type: application/x-www-form-urlencoded` or 
 `Content-Type: multipart/form-data`, the semantics are the same, except the syntax is a single parameter `fields` with 
 a comma-separated list of attribute names, where `exclude` values are those prefixed by a `-` and `include` values are 
 those with no prefix, e.g., `-geometry`, or `id,-geometry,properties`.
@@ -29,7 +29,7 @@ polygons can be very large when reprojected to EPSG:4326, as in the case of a hi
 Implementations are also not required to implement semantics for nested values whereby one can include an object, but
 exclude attributes of that object, e.g., include `properties` but exclude `properties.datetime`.
 
-No error should be returned if a specified field has no value for it in the catalog.  For example, if the attribute 
+No error should be returned if a specified field has no value for it in the catalog. For example, if the attribute 
 "properties.eo:cloud_cover" is specified but there is no cloud cover value for an Item or the API does not even 
 support the EO Extension, a successful HTTP response should be returned and the Item entities will not contain that 
 attribute. 
@@ -42,11 +42,6 @@ will not be a valid STAC Item.
 Implementations may return attributes not specified, e.g., id, but should avoid anything other than a minimal entity 
 representation. 
 
-**NOTE**: *This extension is built to be compatible
-[OAFeat](https://github.com/opengeospatial/ogcapi-features) endpoints, but does not yet have a conformance
-class to use in that way. Our goal is to align with OGC API functionality, which looks to be prioritized currently as
-[future work](https://github.com/opengeospatial/ogcapi-features/issues/451)*
-
 ## Include/Exclude Semantics 
 
 1. If `fields` attribute is specified with an empty object, or with both `include` and `exclude` set to null or an 
diff --git a/fragments/query/README.md b/fragments/query/README.md
@@ -2,12 +2,11 @@
 
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml)
 - **Extension [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
-  Likely to get deprecated in the future in favor of CQL.
+  Likely to get deprecated in the future in favor of [CQL](http://docs.opengeospatial.org/DRAFTS/19-079.html).
 - **Dependents:**
   - [Item Search](../../item-search)
 
-The STAC search endpoint, `/search`, by default only accepts a limited set of core filter parameters.
-The Query API extension adds additional filters for searching on the properties of Items.
+The `query` parameter adds additional filters for searching on the properties of Items.
 
 The syntax for the `query` filter is:
 
diff --git a/fragments/sort/README.md b/fragments/sort/README.md
@@ -4,12 +4,8 @@
 - **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
 - **Dependents:**
   - [Item Search](../../item-search)
-
-By default, the STAC search endpoint `/search` 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.
  
-The Sort API Extension adds a new parameter, `sortby`, that allows the user to define fields by which to sort results. 
+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. 
@@ -18,13 +14,13 @@ Fields may be sorted in ascending or descending order.  The syntax between GET r
 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 extension is built to be compatible [OAFeat](../../ogcapi-features/README.md) endpoints,
-but does not yet have a conformance class to use in that way.
-Our goal is to align with OGC API functionality, which is currently being worked on as part of OGC API - Records.*
+**NOTE**: *This fragment 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 (or POST Form)
 
-When calling `/search` using GET (or POST with `Content-Type: application/x-www-form-urlencoded` or 
+When calling a relevant endpoint using GET (or POST with `Content-Type: application/x-www-form-urlencoded` or 
 `Content-Type: multipart/form-data)`, a single parameter `sortby` with a comma-separated list of item field names should 
 be provided. The field names may be prefixed with either "+" for ascending, or "-" for descending.  If no sign is 
 provided before the field name, it will be assumed to be "+". 
@@ -41,7 +37,7 @@ Note that examples 1 and 2 are symantically equivalent, as well as examples 3 an
 
 ## HTTP POST JSON Entity
 
-When calling `/search` using POST with`Content-Type: application/json`, this extension adds an attribute `sortby` with 
+When calling the relevant endpoint using POST with`Content-Type: application/json`, this adds an attribute `sortby` with 
 an object value to the core JSON search request body.
 
 The syntax for the `sortby` attribute is:
diff --git a/item-search/README.md b/item-search/README.md
@@ -4,6 +4,7 @@
 - **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search>
 - **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
 - **Dependencies**: [STAC API - Core](../core)
+- **Examples**: [examples.md](examples.md)
 
 A search endpoint, linked to from the STAC landing page, provides the ability to query STAC `Items` across collections.
 It retrieves a group of Items that match the provided parameters, wrapped in an ItemCollection (which is a 
@@ -28,32 +29,6 @@ This link should look like:
 }
 ```
 
-## Extensions
-
-### Context
-
-- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#context>**
-- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
-- **Dependencies**: [STAC API - Context Fragment](../fragments/context/)
-
-### Fields
-
-- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#fields>
-- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
-- **Dependencies**: [STAC API - Fields Fragment](../fragments/fields/)
-
-### Query
-
-- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#query>
-- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
-- **Dependencies**: [STAC API - Query Fragment](../fragments/query/)
-
-### Sort
-
-- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#sort>
-- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
-- **Dependencies**: [STAC API - Sort Fragment](../fragments/sort/)
-
 ## Query Parameters and Fields
 
 The following list of parameters is used to narrow search queries. They can all be represented as query string parameters 
@@ -75,6 +50,8 @@ GET /search?collections=landsat8,sentinel&bbox=-10.415,36.066,3.779,44.213&limit
 }
 ```
 
+For more examples see [examples.md](examples.md).
+
 ### Query Parameter Table
 
 The core parameters for STAC search are defined by OAFeat, and STAC adds a few parameters for convenience.
@@ -89,7 +66,7 @@ The core parameters for STAC search are defined by OAFeat, and STAC adds a few p
 | collections  | \[string]        | STAC         | Array of one or more Collection IDs to include in the search for items. Only Items in one of the provided Collections will be searched |
 
 Only one of either **intersects** or **bbox** should be specified.  If both are specified, a 400 Bad Request response 
-should be returned. See [examples](#examples) to see sample requests.
+should be returned. See [examples](examples.md) to see sample requests.
 
 ## Response
 
@@ -180,124 +157,61 @@ searching on specific Item properties.
 The other HTTP verbs are not supported in STAC Item Search. The [Transaction Extension](../ogcapi-features/extensions/transaction/README.md)
 does implement them, for STAC and OAFeat implementations that want to enable writing and deleting items.
 
-#### Examples
+## Extensions
 
-##### Simple GET based search
-Request:
-```http
-HTTP GET /search?bbox=-110,39.5,-105,40.5
-```
+These extensions provide additional functionality that enhances the core item search. All are specified as 
+[fragments](../fragments), as they are re-used by other extensions STAC API's that offer the following capabilities at
+the `search` endpoint must include the relevant **conformance URI** in the `conformsTo` response at
+the root (`/`) landing page, to indicate to clients that they will respond properly to requests from clients.
 
-Response with `200 OK`:
-```json
-{
-    "type": "FeatureCollection",
-    "features": [],
-    "links": [
-        {
-            "rel": "next",
-            "href": "http://api.cool-sat.com/search?page=2"
-        }
-    ]
-}
-```
-Following the link `http://api.cool-sat.com/search?page=2` will send the user to the next page of results.
+### Fields
 
-##### POST search with body and merge fields
-Request to `HTTP POST /search`:
-```json
-{
-    "bbox": [-110, 39.5, -105, 40.5]
-}
-```
+- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#fields>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Definition**: [STAC API - Fields Fragment](../fragments/fields/)
 
-Response with `200 OK`:
-```json
-{
-    "type": "FeatureCollection",
-    "features": [],
-    "links": [
-        {
-            "rel": "next",
-            "href": "http://api.cool-sat.com/search",
-            "method": "POST",
-            "body": {
-                "page": 2,
-                "limit": 10
-            },
-            "merge": true
-        }
-    ]
-}
-```
+By default, the STAC search endpoint `/search` returns all attributes of each Item, as there is no way to specify 
+exactly those attributes that should be returned. The Fields extension to Item Search 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/). 
 
-This tells the client to POST to the search endpoint using the original request with the `page` and `limit` fields 
-merged in to obtain the next set of results:
+### Query
 
-Request to `POST /search`:
-```json
-{
-    "bbox": [-110, 39.5, -105, 40.5],
-    "page": 2,
-    "limit": 10
-}
-```
+- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#query>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Definition**: [STAC API - Query Fragment](../fragments/query/)
 
-This can be even more effective when using continuation tokens on the server, as the entire request body need not be 
-repeated in the subsequent request:
+The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results
+by properties. The Query extension adds a new parameter, `query`, that can take a number of comparison operators to
+match predicates between the fields requested and the values of Items. It can be used with both GET and POST, though
+GET includes the exact same JSON. The full details on the JSON structure are specified in the [query 
+fragment](../fragments/query/).
 
-Response with `200 OK`:
-```json
-{
-    "rel": "next",
-    "href": "http://api.cool-sat.com/search",
-    "method": "POST",
-    "body": {
-        "next": "a9f3kfbc98e29a0da23"
-    }
-}
-```
-The above link tells the client not to merge (default of false) so it is only required to pass the next token in the body.
+### Sort
 
-Request to `POST /search`:
-```json
-{
-    "next": "a9f3kfbc98e29a0da23"
-}
-```
+- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#sort>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Definition**: [STAC API - Sort Fragment](../fragments/sort/)
 
-##### POST search using headers
-Request to `HTTP POST /search`:
-```json
-{
-    "bbox": [-110, 39.5, -105, 40.5],
-    "page": 2,
-    "limit": 10
-}
-```
+By default, the STAC search endpoint `/search` 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 can be used with both GET and POST, the former using '+' and
+'-' to indicate sort order, and the latter including a 'direction' field in JSON. The full description of the semantics
+of this extension can be found in the [sort fragment](../fragments/sort).
 
-Response with `200 OK`:
-```json
-{
-    "type": "FeatureCollection",
-    "features": [],
-    "links": [
-        {
-            "rel": "next",
-            "href": "http://api.cool-sat.com/search",
-            "method": "POST",
-            "headers": {
-                "Search-After": "LC81530752019135LGN00"
-            }
-        }
-    ]
-}
-```
+### Context
 
-This tells the client to POST to the search endpoint with the header `Search-After` to obtain the next set of results:
+- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#context>**
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Definition**: [STAC API - Context Fragment](../fragments/context/)
 
-Request:
-```http
-POST /search
-Search-After: LC81530752019135LGN00
-```
+This extension is intended to augment the core ItemCollection responses from the `search` API endpoint 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)
+
+STAC API's that support the context functionality must include the conformance class 
+<http://stacspec.org/spec/api/1.0.0-beta.1/extensions/item-search#context> in the `conformsTo` response at
+the root (`/`) landing page, to indicate to clients that they will to respond with a `context` JSON object in all
+responses from the `search` endpoint.
diff --git a/item-search/examples.md b/item-search/examples.md
diff --git a/overview.md b/overview.md
