Merge pull request #46 from radiantearth/dev

Merge dev
radiantearth · Oct 6, 2020 · dc40554 · dc40554
2 parents dc52575 + 8035776
commit dc40554
Show file tree

Hide file tree

Showing 7 changed files with 101 additions and 40 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,14 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 ### Changed
+- Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute
+- Added root endpoint Link `search` must have `type` of `application/geo+json`
+- Corrected the description of endpoint `/collections` to say it returns an object per OAFeat, instead of an array of Collection
 
 ### Deprecated
 
 ### Removed
 
 ### Fixed
 
-
 ## Older versions
 
 See the [stac-spec CHANGELOG](https://github.com/radiantearth/stac-spec/blob/v0.9.0/CHANGELOG.md) for STAC API releases prior to or equal to version 0.9.0.

diff --git a/STAC-extensions.yaml b/STAC-extensions.yaml
@@ -1644,9 +1644,12 @@ components:
         context:
           type: object
           required:
-            - next
             - returned
           properties:
+            returned:
+              type: integer
+              minimum: 0
+              example: 1
             limit:
               type: integer
               nullable: true
@@ -1655,11 +1658,7 @@ components:
             matched:
               type: integer
               minimum: 0
-              example: 1
-            returned:
-              type: integer
-              minimum: 0
-              example: 1
+              example: 314159
     item:
       description: >-
         A GeoJSON Feature augmented with foreign members that contain values

diff --git a/api-spec.md b/api-spec.md
@@ -90,31 +90,46 @@ The core OGC API - Features endpoints are shown below, with details provided in
 | `/collections/{collectionId}/items`             | ItemCollection | GeoJSON FeatureCollection-conformant entity of Items in collection |
 | `/collections/{collectionId}/items/{featureId}` | Item           | Returns single Item (GeoJSON Feature) |
 
+The `/collections` endpoint returns an object with a field `collections` that is an array of Collection objects.
+
 The `/collections/{collection_id}/items` endpoint accepts parameters for filtering the results (also called filters). 
 Items in the collection should match all filters to be returned when querying. This implies a logical AND operation. If 
 an OR operation is needed, it should be specified through an extension filter.
 
-## STAC Endpoints
+## STAC API Endpoints
 
-STAC provides some additional endpoints for the root Catalog itself, as well as the capability to search the Catalog. 
-Note that a STAC API does not need to implement OAFeat, in which case it would only support the endpoints given below. 
+STAC API provides additional attributes for the root Catalog endpoint and defines an endpoint to search the Catalog. 
+Note that a STAC API does not need to implement OAFeat, in which case it would support only the endpoints below. 
 See the [OpenAPI specification document](openapi/STAC.yaml).
 
 | Endpoint  | Returns                                                        | Description |
 | --------  | -------------------------------------------------------------- | ----------- |
 | `/`       | [Catalog](./stac-spec/catalog-spec/catalog-spec.md)            | Extends `/` from OAFeat to return a full STAC catalog. |
 | `/search` | [ItemCollection](./stac-spec/item-spec/itemcollection-spec.md) | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the `search` extension |
 
-The `/` endpoint should function as a complete `Catalog` representation of all the data contained in the API and linked 
-to in some way from root through `Collections` and `Items`.
+The root endpoint (`/`) is most useful when it presents a complete `Catalog` representation of all the data contained in the API, such that all `Collections` and `Items` can be navigated to by transitively traversing links from this root. This spec does not require any API endpoints from OAFeat or STAC API to be implemented, so these links may not exist if the endpoint has not been implemented.
+
+Links with these `rel` attributes should exist in the root endpoint if the reference API endpoint is implemented:
+- `data` with href to the OAFeat `/collections` endpoint
+- `child` (one or more) with href to a single `Collection` at the OAFeat `/collections/{collectionId}` endpoint
+- `search` with href to the `/search` endpoint (**required** if search endpoint is implemented)
 
-The `/search` endpoint is similar to the `/collections/{collectionId}/items` endpoint in OGC API - Features in that it 
-accepts parameters for filtering, however it performs the filtering across all collections. The parameters accepted are 
-the same as the Filter Parameters above, however the *[extensions](extensions/README.md)* also provide advanced querying 
+The `/search` endpoint is similar to the `/collections/{collectionId}/items` endpoint in OAFeat in that it 
+accepts parameters for filtering; however, it performs the filtering across all collections. The parameters accepted are 
+the same as the Filter Parameters above; however, the *[extensions](extensions/README.md)* also provide advanced querying 
 parameters.
 
-If the `/search` endpoint is implemented, it is **required** to add a link with the `rel` type set to `search` to the 
-`links` array in `/` that refers to the search endpoint in the `href` property.
+If the `/search` endpoint is implemented, it is **required** to add a Link to the root endpoint (`/`) with the `rel` type set to `search
+that refers to the search endpoint in the `href` property, with a `type` of `application/geo+json`.
+This Link should look like:
+```json
+{
+    "href": "https://example.com/search",
+    "rel": "search",
+    "title": "Search",
+    "type": "application/geo+json"
+}
+```
 
 ## Filter Parameters and Fields
 
@@ -210,7 +225,7 @@ The following fields have been added to the `link` object specification for the
 | method    | string  | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET` |
 | headers   | object  | A dictionary of header values that should be included in the next request |
 | body      | object  | A JSON object containing fields/values that should be included in the body of the next request |
-| merge     | boolean | If `true`, the headers/body fields in the `next` link should be merged into the original request and be sent combined in the next request. Defaults to `false` | 
+| merge     | boolean | If `true`, the headers/body fields in the `next` link should be merged into the original request and be sent combined in the next request. Defaults to `false` |
 
 The implementor has the freedom to decide exactly how to apply these extended fields for their particular pagination 
 mechanism.  The same freedom that exists for GET requests, where the actual URL parameter used to defined the next page 

diff --git a/extensions/context/README.md b/extensions/context/README.md
@@ -18,13 +18,13 @@ object when the ItemCollection is the result of a search, for example, from call
 
 | Element  | Type            | Description |
 | -------- | --------------- | ----------- |
-| returned | integer         | **REQUIRED** The count of results returned by this response. equal to the cardinality of features array |
-| limit    | integer \| null | The maximum number of results to which the result was limited |
-| matched  | integer         | The count of total number of results that match for this query, possibly estimated, particularly in the context of NoSQL data stores |
+| returned | integer         | **REQUIRED** The count of results returned by this response. Equal to the cardinality of features array. |
+| limit    | integer \| null | The maximum number of results to which the result was limited. |
+| matched  | integer         | The count of total number of results that match for this query, possibly estimated, particularly in the context of NoSQL data stores. |
 
   The default sort of query results should be stable, but may not be depending on the data store's sorting performance.
    It is recommended that the [Sort API Extension](../sort/README.md) be implemented in conjunction with this extension
-   and that fields conducive to stable sorting have sorting enabled over them.  
+   and that fields conducive to stable sorting have sorting enabled over them.
 
 **limit** - The maximum number of results requested explicitly, the default limit used by the service implementation
 if no parameter was provided, or the maximum limit used by the service implementation if the limit parameter was larger.
@@ -37,9 +37,9 @@ if no parameter was provided, or the maximum limit used by the service implement
   "type": "FeatureCollection",
   "features": [ ],
   "context": {
+    "returned": 9,
     "limit": 10, 
-    "matched": 1092873, 
-    "returned": 9
+    "matched": 1092873
   }
 }
 ```
diff --git a/extensions/context/context.fragment.yaml b/extensions/context/context.fragment.yaml
@@ -6,9 +6,12 @@ components:
         'context':
           type: object
           required:
-            - next
             - returned
           properties:
+            returned:
+              type: integer
+              minimum: 0
+              example: 1
             limit:
               type: integer
               nullable: true
@@ -17,8 +20,4 @@ components:
             matched:
               type: integer
               minimum: 0
-              example: 1
-            returned:
-              type: integer
-              minimum: 0
-              example: 1
+              example: 314159
diff --git a/extensions/context/examples/example.json b/extensions/context/examples/example.json
@@ -1,9 +1,55 @@
 {
   "type": "FeatureCollection",
-  "features": [ ],
   "context": {
-    "limit": 10,
-    "matched": 1092873,
-    "returned": 9
-  }
+    "returned": 1,
+    "limit": 1,
+    "matched": 1092873
+  },
+  "features": [
+      {
+        "stac_version": "0.9.0",
+        "stac_extensions": [],
+        "type": "Feature",
+        "id": "CS3-20160503_132131_05",
+        "bbox": [
+          -122.59750209,
+          37.48803556,
+          -122.2880486,
+          37.613537207
+        ],
+        "geometry": {
+          "type": "Polygon",
+          "coordinates": [
+            [
+              [
+                -122.308150179,
+                37.488035566
+              ],
+              [
+                -122.597502109,
+                37.538869539
+              ],
+              [
+                -122.576687533,
+                37.613537207
+              ],
+              [
+                -122.288048600,
+                37.562818007
+              ],
+              [
+                -122.308150179,
+                37.488035566
+              ]
+            ]
+          ]
+        },
+        "properties": {
+          "datetime": "2016-05-03T13:22:30.040Z"
+        },
+        "collection": "CS3",
+        "links": [ ],
+        "assets": { }
+      }
+  ]
 }
diff --git a/extensions/context/json-schema/schema.json b/extensions/context/json-schema/schema.json
@@ -3,7 +3,7 @@
   "$id": "schema.json#",
   "title": "Context Extension",
   "type": "object",
-  "description": "STAC search metadata",
+  "description": "STAC context metadata",
   "allOf": [
     {
       "$ref": "#/definitions/context"
@@ -22,17 +22,17 @@
             "returned"
           ],
           "properties": {
+            "returned": {
+              "type": "integer",
+              "minimum": 0
+            },
             "limit": {
               "type": ["integer", "null"],
               "minimum": 0
             },
             "matched": {
               "type": "integer",
               "minimum": 0
-            },
-            "returned": {
-              "type": "integer",
-              "minimum": 0
             }
           }
         }