-
Notifications
You must be signed in to change notification settings - Fork 44
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browseable recommendations and Children conformance class (#229)
* add children and browseable conformance classes
- Loading branch information
1 parent
b0e8995
commit 4f0ced2
Showing
10 changed files
with
669 additions
and
53 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| # 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. This conformance | ||
| class is used to signal to users that they can fully navigate to all available Items using a UI (like [STAC Browser](https://github.com/radiantearth/stac-browser), | ||
| and also makes it clear to crawlers that they can reach everything by following catalog links. | ||
|
|
||
| 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 resource (at the `/collections/{collectionId}` endpoint) to the items in | ||
| that collection (at the `/collections/{collectionId}/items` endpoint). Both of these endpoints are | ||
| [derived from OGC API - Features](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_). | ||
|
|
||
| ## 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`. Note that the | ||
| `conformsTo` array contains `https://api.stacspec.org/v1.0.0-beta.5/browseable` and the `links` array | ||
| contains `child` link relations. The semantics of this conformance class imply that the the catalogs | ||
| linked to by these `child` link relations then have further `child` or `item` link relations that | ||
| eventually reach all items in this catalog. | ||
|
|
||
| ```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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" | ||
| } | ||
| ] | ||
| } | ||
| ``` |
Oops, something went wrong.