Browseable recommendations and Children conformance class

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added `STAC API - Browseable` conformance class
+- Added `STAC API - Children` conformance class
+- Added description of how to support both search and browse in an API.
 - The paging mechanism via a Link with rel `next` or `prev` as defined for Item Search can also be used
   for the STAC API - Features endpoint `/collections/{collection_id}/items`, as described in OAFeat.
 - The paging mechanism via a Link with rel `next` or `prev` as defined for items can also be used
@@ -56,7 +59,7 @@ 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`)
+  endpoint (`/collections/{collectionId}/items`)
 - In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints
 - In Item Search, added endpoint table
 

README.md

@@ -16,7 +16,6 @@ The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standard
 A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and 
 time. The core STAC specifications live in the GitHub repository [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).
 
-
 A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), 
 [Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md), 
 or a STAC API [ItemCollection](fragments/itemcollection/README.md), depending on the endpoint.
@@ -57,17 +56,25 @@ The **[Overview](overview.md)** document describes all the various parts of the
 The *[core](core/)* folder describes the core STAC API specification that enables browsing catalogs and 
 retrieving the API capabilities. This includes the OpenAPI schemas for STAC Item, Catalog and Collection objects.
 
-**STAC API - Item Search Specification:**
-The *[item-search](item-search)* folder contains the Item Search specification, which enables 
-cross-collection search of STAC Item objects at a `search` endpoint, as well as a number of extensions. 
+**STAC API - Collections:**
+The *[collections](collections)* folder describes how a STAC API Catalog can advertise the Collections it contains.
 
 **STAC API - Features:**
 The *[ogcapi-features](ogcapi-features)* folder describes how a STAC API can fully implement [OGC API - 
 Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) to expose individual `items` endpoints for search of
 each STAC collection. It also includes extensions that can be used to further enhance OAFeat.
 
-**STAC API - Collections:**
-The *[collections](collections)* folder describes how a STAC API can advertise the Collections it contains.
+**STAC API - Item Search Specification:**
+The *[item-search](item-search)* folder contains the Item Search specification, which enables 
+cross-collection search of STAC Item objects at a `search` endpoint, as well as a number of extensions. 
+
+**STAC API - Children:**
+The *[children](children)* folder describes how a STAC API Catalog can advertise the children (sub-catalogs or sub-collections)
+it contains.
+
+**STAC API - Browseable:**
+The *[browseable](browseable)* folder describes how a STAC API Catalog can advertise that all Items can be accessed
+by following through `child` and `item` link relations.
 
 **Extensions:**
 The *[extensions](extensions.md) document* describes how STAC incubates new functionality, and it links to the existing 

browseable/README.md

@@ -0,0 +1,101 @@
+# STAC API - Browseable Specification
+
+- [STAC API - Browseable Specification](#stac-api---browseable-specification)
+  - [Link Relations](#link-relations)
+  - [Endpoints](#endpoints)
+  - [Example Landing Page for STAC API - Browseable](#example-landing-page-for-stac-api---browseable)
+  - [Extensions](#extensions)
+
+- **OpenAPI specification:** none
+- **Conformance URIs:** 
+  - <https://api.stacspec.org/v1.0.0-beta.5/browseable>
+  - <https://api.stacspec.org/v1.0.0-beta.5/core>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Dependencies**: [STAC API - Core](../core)
+
+A STAC API conforming to the `STAC API - Browseable` conformance class must be structured such that all 
+all Items in the catalog can be accessed by following `child` and `item` link relations. This is a more significant
+constraint than a STAC API without this conformance class or a STAC Catalog that is available over HTTP but does not
+implement STAC API, neither of which have any guarantee regarding the reachability of Items.
+
+Recommendations for structuring Catalogs hierarchically can be found in
+[Structuring Catalog Hierarchies](../core/README.md#structuring-catalog-hierarchies) from the `STAC API - Core` specification.
+
+## Link Relations
+
+This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.
+
+Additionally, `child` relations must exist to child Catalogs and Collections and `item` relations to Items, such that
+every Item in the Catalog can be accessed by traversing these relations.
+
+| **rel** | **href** | **From**  | **Description**                        |
+| ------- | -------- | --------- | -------------------------------------- |
+| `child` | various  | STAC Core | The child STAC Catalogs & Collections. |
+| `item`  | various  | STAC Core | The child STAC Items.                  |
+
+Note that there is a different link relation `items` (plural)
+used by the `STAC API - Features` conformance class that links from a collection to the items in
+that collection.
+
+## Endpoints
+
+This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
+
+This conformance class adds no additional endpoints.
+
+## Example Landing Page for STAC API - Browseable
+
+This JSON is what would be expected from an API that implements `STAC API - Browseable`. 
+
+This particular catalog provides both the ability to browse down to child Catalog objects through its
+`child` links, which then will eventually reach Items through `item` link relations.
+
+```json
+{
+    "stac_version": "1.0.0",
+    "id": "example-stac",
+    "title": "A simple STAC API Example, implementing STAC API - Browseable",
+    "description": "This Catalog aims to demonstrate the a simple landing page",
+    "type": "Catalog",
+    "conformsTo" : [
+        "https://api.stacspec.org/v1.0.0-beta.5/core",
+        "https://api.stacspec.org/v1.0.0-beta.5/browseable"
+    ],
+    "links": [
+        {
+            "rel": "self",
+            "type": "application/json",
+            "href": "https://stacserver.org"
+        },
+        {
+            "rel": "root",
+            "type": "application/json",
+            "href": "https://stacserver.org"
+        },
+        {
+            "rel": "service-desc",
+            "type": "application/vnd.oai.openapi+json;version=3.0",
+            "href": "https://stacserver.org/api"
+        },
+        {
+            "rel": "service-doc",
+            "type": "text/html",
+            "href": "https://stacserver.org/api.html"
+        },
+        {
+            "rel": "child",
+            "type": "application/json",
+            "href": "https://stacserver.org/catalogs/sentinel-2",
+        },
+        {
+            "rel": "child",
+            "type": "application/json",
+            "href": "https://stacserver.org/catalogs/landsat-8",
+        }
+    ]
+}
+```
+
+## Extensions
+
+None.

children/README.md

@@ -0,0 +1,214 @@
+# STAC API - Children
+
+- [STAC API - Children](#stac-api---children)
+  - [Link Relations](#link-relations)
+  - [Endpoints](#endpoints)
+  - [Pagination](#pagination)
+  - [Example](#example)
+
+- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/children))
+- **Conformance URIs:** 
+  - <https://api.stacspec.org/v1.0.0-beta.5/children>
+  - <https://api.stacspec.org/v1.0.0-beta.5/core>
+- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
+- **Dependencies**: [STAC API - Core](../core)
+
+A STAC API Landing Page (a Catalog) can return information about the Catalog and Collection child objects
+it contains using the link relation `children` to an endpoint `/children`. The purpose of this endpoint is
+to present a single resource from which clients can retrieve
+all the immediate child objects of a Catalog, which may be Catalog or Collection objects.
+The `child` link relations in a Catalog already allow for describing these
+relationships, but require a client to retrieve each resource URL to find any information about the children
+(e.g., title, description), which can cause significant performance issues in user-facing applications.
+
+It is recommended that the Catalog and Collection objects returned by the `/children` endpoint are the same
+as those referenced by `child` link relations in the STAC API Landing Page. Following these semantics, it should
+return the immediate children of the root Catalog, rather than all descendant catalogs or collections.
+
+## Link Relations
+
+This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.
+
+The following Link relations shall exist in the Landing Page (root).
+
+| **rel**    | **href**    | **From**        | **Description**                  |
+| ---------- | ----------- | --------------- | -------------------------------- |
+| `children` | `/children` | STAC API - Children | List of children of this catalog |
+
+The following Link relations shall exist in the `/children` endpoint response.
+
+| **rel** | **href**    | **From**            | **Description** |
+| ------- | ----------- | ------------------- | --------------- |
+| `root`  | `/`         | STAC Core           | The root URI    |
+| `self`  | `/children` | STAC API - Children | Self reference  |
+
+## Endpoints
+
+This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
+
+| Endpoint    | Returns        | Description                                                                                                            |
+| ----------- | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `/children` | JSON           | Object with a list of child Catalogs and Collections                                                                   |
+
+STAC APIs implementing the `STAC API - Children` conformance class must support HTTP GET operation at
+`/children`, with the return JSON document consisting of an array of all child Catalogs and Collections in a field `children` and an 
+array of Links in a field `links`.
+
+## Pagination
+
+The `/children` endpoint supports a pagination mechanism that aligns with pagination as described in the 
+OGC API - Common - Part 2: Geospatial Data specification. This is described in detail in
+the [STAC - Features Collection Pagination section](../ogcapi-features/README.md#collection-pagination).
+To the greatest extent possible, the catalog should be structured such that all children can be
+retrieved from the endpoint in a single call.
+
+## Example
+
+Below is a minimal example, but captures the essence. Each object in the `children` array 
+must be a valid STAC [Collection](../stac-spec/collection-spec/README.md) or [Catalog](../stac-spec/catalog-spec/README.md),
+and each must have a `self` link that communicates its canonical location. And then 
+the links section must include a `self` link, and it must also link to alternate representations
+(like html) of the collection.
+
+The STAC API Landing Page should look like the following (note the `child` link relations):
+
+```json
+{
+    "stac_version": "1.0.0",
+    "id": "example-stac",
+    "title": "A simple STAC API Example, implementing STAC API - Children",
+    "description": "This Catalog aims to demonstrate the a simple landing page",
+    "type": "Catalog",
+    "conformsTo" : [
+        "https://api.stacspec.org/v1.0.0-beta.5/core",
+        "https://api.stacspec.org/v1.0.0-beta.5/children",
+        "https://api.stacspec.org/v1.0.0-beta.5/browseable"
+    ],
+    "links": [
+        {
+            "rel": "self",
+            "type": "application/json",
+            "href": "https://stacserver.org"
+        },
+        {
+            "rel": "root",
+            "type": "application/json",
+            "href": "https://stacserver.org"
+        },
+        {
+            "rel": "service-desc",
+            "type": "application/vnd.oai.openapi+json;version=3.0",
+            "href": "https://stacserver.org/api"
+        },
+        {
+            "rel": "service-doc",
+            "type": "text/html",
+            "href": "https://stacserver.org/api.html"
+        },
+        {
+            "rel": "children",
+            "type": "application/json",
+            "href": "https://stacserver.org/children",
+        },
+        {
+            "rel": "child",
+            "type": "application/json",
+            "href": "https://stacserver.org/catalogs/cool-data",
+        },
+        {
+            "rel": "child",
+            "type": "application/json",
+            "href": "https://stacserver.org/catalogs/some-other-data",
+        }
+    ]
+}
+```
+
+The `/children` endpoint response object should look as follows:
+
+```json
+{
+  "children": [
+    {
+      "stac_version": "1.0.0",
+      "stac_extensions": [ ],
+      "id": "cool-data",
+      "title": "Cool Data from X Satellite",
+      "description": "A lot of awesome words describing the data",
+      "type": "Catalog",
+      "license": "CC-BY",
+      "extent": {
+        "spatial": {
+          "bbox": [[-135.17, 36.83, -51.24, 62.25]]
+        },
+        "temporal": {
+          "interval": [["2009-01-01T00:00:00Z",null]]
+        }
+      },
+      "links": [
+        {
+          "rel": "root",
+          "type": "application/json",
+          "href": "https://stacserver.org"
+        },
+        {
+          "rel": "parent",
+          "type": "application/json",
+          "href": "https://stacserver.org"
+        },
+        {
+          "rel": "self",
+          "type": "application/json",
+          "href": "https://stacserver.org/catalogs/cool-data"
+        }
+      ],
+    },
+    {
+      "stac_version": "1.0.0",
+      "stac_extensions": [ ],
+      "id": "some-other-data",
+      "title": "Some Other Data from Y Satellite",
+      "description": "More awesome words describing the data",
+      "type": "Catalog",
+      "license": "CC-BY",
+      "extent": {
+        "spatial": {
+          "bbox": [[-135.17, 36.83, -51.24, 62.25]]
+        },
+        "temporal": {
+          "interval": [["2009-01-01T00:00:00Z",null]]
+        }
+      },
+      "links": [
+        {
+          "rel": "root",
+          "type": "application/json",
+          "href": "https://stacserver.org"
+        },
+        {
+          "rel": "parent",
+          "type": "application/json",
+          "href": "https://stacserver.org"
+        },
+        {
+          "rel": "self",
+          "type": "application/json",
+          "href": "https://stacserver.org/catalogs/some-other-data"
+        }
+      ],
+    }
+  ],
+  "links": [
+    {
+      "rel": "root",
+      "type": "application/json",
+      "href": "https://stacserver.org"
+    },
+    {
+      "rel": "self",
+      "type": "application/json",
+      "href": "https://stacserver.org/children"
+    }
+  ]
+}
+```