Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor link relation tables, make parent not a required field #407

Merged
merged 7 commits into from
Mar 20, 2023
Merged

refactor link relation tables, make parent not a required field #407

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5f08c7d
refactor link relation tables, make parent not a required field
philvarner Mar 14, 2023
ea2209e
changelog
philvarner Mar 14, 2023
16dc9fd
Update ogcapi-features/README.md
Mar 14, 2023
93c7965
lint
Mar 14, 2023
dfc6d54
Update ogcapi-features/README.md
Mar 14, 2023
57b924b
Update ogcapi-features/README.md
Mar 14, 2023
17be8aa
format
philvarner Mar 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Changed

- Browseable has been moved to an extension, now located at <https://github.com/stac-api-extensions/browseable>
- Link relation `parent` is no longer a required link for Collections or Items

## Added

Expand Down
24 changes: 9 additions & 15 deletions core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,16 @@ While the STAC definition of Link does not require the `type` field,
*STAC API - Core* requires all Links to have this field.
If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`.

The following Link relations must exist in the Landing Page (root).
The following Link relations are defined for the Landing Page (root).

| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------------- | -------- | ---------------- | --------------- | ---------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Core | The root URI |
| `self` | `/` | application/json | OAFeat | Self reference, same as root URI |
| `service-desc` | `/api` | various | OAFeat | The service description in a machine-readable format |
| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------------- | ----------- | -------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Core | **REQUIRED** The root URI |
| `self` | `/` | application/json | OAFeat | **REQUIRED** Self reference, same as root URI |
| `service-desc` | `/api` | various | OAFeat | **REQUIRED** The service description in a machine-readable format |
| `service-doc` | `/api.html` | text/html | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. |
| `child` | various | application/json | STAC API - Core | The child STAC Catalogs & Collections. |
| `item` | various | application/geo+json | STAC API - Core | The child STAC Items. |

The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be
OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML),
Expand All @@ -85,18 +88,9 @@ page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) inte
, but any format is allowed. The Link `type` field should correspond to whatever format or formats are
supported by this endpoint, e.g., `text/html`.

| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------- | ----------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `service-doc` | `/api.html` | text/html | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. |

Additionally, `child` relations may exist to child Catalogs and Collections and `item` relations to Items. These
relations form a directed graph that enables traversal from a root catalog or collection to items.

| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------- | -------- | -------------------- | --------------- | -------------------------------------- |
| `child` | various | application/json | STAC API - Core | The child STAC Catalogs & Collections. |
| `item` | various | application/geo+json | STAC API - Core | The child STAC Items. |

While it is valid to have `item` links from the landing page, most STAC API implementations
serve large numbers of features, so they will typically use several layers of intermediate `child` links to sub-catalogs and collections before
getting to Item objects. These relations form a directed graph
Expand Down
16 changes: 8 additions & 8 deletions item-search/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,23 +55,23 @@ If the target of a Link's `type` is unknown, `type` SHOULD be set to `applicatio

This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.

The following Link relations must exist in the Landing Page (root).
The following Link relations are defined for the Landing Page (root).

| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------- | --------- | -------------------- | ---------------------- | --------------------------- |
| `search` | `/search` | application/geo+json | STAC API - Item Search | URI for the Search endpoint |
| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------- | --------- | -------------------- | ---------------------- | ---------------------------------------- |
| `search` | `/search` | application/geo+json | STAC API - Item Search | **REQUIRED** URI for the Search endpoint |

This `search` link relation must have a `type` of `application/geo+json`. If no `method` attribute is
specified, it is assumed to represent a GET request. If the server supports both GET and POST requests, two links should be included, one with a `method` of `GET` one with a `method` of `POST`.

Other links with relation `search` may be included that advertise other content types the server may respond
with, but these other types are not part of the STAC API requirements.

The following Link relations must exist in the `/search` endpoint response.
The following Link relations are defined for the `/search` endpoint response.

| **rel** | **href** | **From** | **Description** |
| ------- | -------- | ---------------------- | --------------- |
| `root` | `/` | STAC API - Item Search | The root URI |
| **rel** | **href** | **From** | **Description** |
| ------- | -------- | ---------------------- | ------------------------- |
| `root` | `/` | STAC API - Item Search | **REQUIRED** The root URI |

## Endpoints

Expand Down
70 changes: 34 additions & 36 deletions ogcapi-features/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,37 +106,32 @@ If the target of a Link's `type` is unknown, `type` SHOULD be set to `applicatio

### Landing Page (/)

The following Link relations must exist in the Landing Page (root).
The following Link relations are defined for the Landing Page (root).

| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------- | -------------- | ---------------- | -------- | ------------------- |
| `conformance` | `/conformance` | application/json | OAFeat | Conformance URI |
| `data` | `/collections` | application/json | OAFeat | List of Collections |
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------- | -------------- | ---------------- | -------- | -------------------------------- |
| `conformance` | `/conformance` | application/json | OAFeat | **REQUIRED** Conformance URI |
| `data` | `/collections` | application/json | OAFeat | **REQUIRED** List of Collections |

### Collections (/collections)

The following Link relations must exist in the `/collections` endpoint response.
The following Link relations are defined for the `/collections` endpoint response.

| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------- | -------------- | ---------------- | ------------------------------------------- | --------------- |
| `root` | `/` | application/json | STAC API - Features, STAC API - Collections | The root URI |
| `self` | `/collections` | application/json | OAFeat | Self reference |
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------- | -------------- | ---------------- | -------------------------------------------------------- | --------------------------- |
| `root` | `/` | application/json | **REQUIRED** STAC API - Features, STAC API - Collections | The root URI |
philvarner marked this conversation as resolved.
Show resolved Hide resolved
| `self` | `/collections` | application/json | OAFeat | **REQUIRED** Self reference |

### Collection (/collections/{collectionId})

The following Link relations must exist in the Collection object returned from the `/collections/{collectionId}` endpoint.
The following Link relations are defined for the Collection object returned from the `/collections/{collectionId}` endpoint.

| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------- | ----------------------------- | ---------------- | ------------------------------------------- | ------------------------------------------ |
| `root` | `/` | application/json | STAC API - Features, STAC API - Collections | The root URI |
| `parent` | `/` | application/json | OAFeat | Parent reference, usually the root Catalog |
| `self` | `/collections/{collectionId}` | application/json | OAFeat | Self reference |

Additionally, these relations may exist for the `/collections/{collectionId}` endpoint:

| **rel** | **href** | **Media Type** | **From** | **Description** |
| ----------- | -------- | -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `canonical` | various | various | STAC API - Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. |
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ----------- | ----------------------------- | ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Features, STAC API - Collections | **REQUIRED** The root URI |
| `self` | `/collections/{collectionId}` | application/json | OAFeat | **REQUIRED** Self reference |
| `parent` | `/` | application/json | OAFeat | Parent reference, usually the root Catalog |
philvarner marked this conversation as resolved.
Show resolved Hide resolved
| `canonical` | various | various | STAC API - Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. |

Usually, the `self` link in a Collection must link to the same URL that was used to request
it. However, implementations may choose to have the canonical location of the Collection be
Expand All @@ -147,26 +142,29 @@ of that Collection, rather than the API sub-path of `/collections`.

### Collection Items (/collections/{collectionId}/items)

The following Link relations must exist in the ItemCollection object returned from the `/collections/{collectionId}/items` endpoint.
The following Link relations are defined for the ItemCollection object returned from the `/collections/{collectionId}/items` endpoint.

| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------ | ----------------------------------- | -------------------- | ------------------- | -------------------- |
| `root` | `/` | application/json | STAC API - Features | The root URI |
| `self` | `/collections/{collectionId}/items` | application/geo+json | OAFeat | Self reference |
| `collection` | `/collections/{collectionId}` | application/json | OAFeat | Collection reference |
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------ | ----------------------------------- | -------------------- | -------------------------------- | --------------------------------- |
| `root` | `/` | application/json | **REQUIRED** STAC API - Features | The root URI |
philvarner marked this conversation as resolved.
Show resolved Hide resolved
| `self` | `/collections/{collectionId}/items` | application/geo+json | OAFeat | **REQUIRED** Self reference |
| `collection` | `/collections/{collectionId}` | application/json | OAFeat | **REQUIRED** Collection reference |

### Items (/collections/{collectionId}/items/{itemId})

The following Link relations must exist in the Item object returned from the `/collections/{collectionId}/items/{itemId}` endpoint.
The following Link relations are defined for the Item object returned from the `/collections/{collectionId}/items/{itemId}` endpoint.

| **rel** | **href** | **Media Type** | **From** | **Description** |
| -------- | -------------------------------------------- | -------------------- | ------------------- | --------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Features | The root URI |
| `collection` | `/collections/{collectionId}` | application/json | STAC Item | The containing Collection |
| `parent` | `/collections/{collectionId}` | application/json | STAC Item | Parent reference, usually the containing Collection |
| `self` | `/collections/{collectionId}/items/{itemId}` | application/geo+json | OAFeat | Self reference |
| **rel** | **href** | **Media Type** | **From** | **Description** |
| ------------ | -------------------------------------------- | -------------------- | ------------------- | --------------------------------------------------- |
| `root` | `/` | application/json | STAC API - Features | **REQUIRED** The root URI |
| `self` | `/collections/{collectionId}/items/{itemId}` | application/geo+json | OAFeat | **REQUIRED** Self reference |
| `collection` | `/collections/{collectionId}` | application/json | STAC Item | **REQUIRED** The containing Collection |
| `parent` | `/collections/{collectionId}` | application/json | STAC Item | Parent reference, usually the containing Collection |

The `parent` link for an Item may point to a Collection or a Catalog. The `collection` link for an Item will always point to the containing Collection. Links to a Collection must point to the `/collections/{collectionId}` endpoint, rather than the API sub-path of `/collections/{collectionId}/items/`.
The `parent` link for an Item may point to a Collection or a Catalog. The
`collection` link for an Item will always point to the containing Collection.
Links to a Collection must point to the `/collections/{collectionId}` endpoint,
rather than the API sub-path of `/collections/{collectionId}/items/`.

## Endpoints

Expand Down