Skip to content

Commit

Permalink
Assign specific media types to relation types (#1259)
Browse files Browse the repository at this point in the history 
* Clarified which media types should be used for the hierarchical relation types
* Add notes about OGC APIs

Co-authored-by: Pete Gadomski <pete.gadomski@gmail.com>
Co-authored-by: Emmanuel Mathot <emmanuel.mathot@terradue.com>
  • Loading branch information
@m-mohr @gadomski @emmanuelmathot
3 people authored May 15, 2024
1 parent 48f143a commit 3961d47
Show file tree
Hide file tree
Showing 6 changed files with 64 additions and 58 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

- Several typos and minor language changes
- Clarified that collection IDs should be unique across all collections in the corresponding root catalog.
- Clarified which media types should be used for the hierarchical relation types

## [v1.0.0] - 2021-05-25

Expand Down
24 changes: 15 additions & 9 deletions best-practices.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
- [Unrectified Satellite Data](#unrectified-satellite-data)
- [Data that is not spatial](#data-that-is-not-spatial)
- [Representing Vector Layers in STAC](#representing-vector-layers-in-stac)
- **[Asset Best Practices](#asset-practices)**
- **[Asset (and Link) Best Practices](#asset-and-link-best-practices)**
- [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets)
- [Working with Media Types](#working-with-media-types)
- [Common Media Types in STAC](#common-media-types-in-stac)
Expand Down Expand Up @@ -270,7 +270,7 @@ that is not possible then the appropriate way to handle Collection-level search
[OGC API - Records](https://github.com/opengeospatial/ogcapi-records) standard, which is a 'brother' specification of STAC API.
Both are compliant with OGC API - Features, adding richer search capabilities to enable finding of data.

## Asset Practices
## Asset (and Link) Best Practices

### Common Use Cases of Additional Fields for Assets

Expand Down Expand Up @@ -305,8 +305,12 @@ providing them at the Asset level can prove to be very useful for using the data
[Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element that enables STAC to be a rich source of information for
clients. The best practice is to use as specific of a media type as possible (so if a file is a GeoJSON then don't use a JSON
media type), and to use [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) IANA types as much as possible.
The following table lists types that commonly show up in STAC assets. And the [section](#formats-with-no-registered-media-type)
past that gives recommendations on what to do if you have a format in your asset that does not have an IANA registered type.

For hierarchical links (e.g. relation types `root`, `parent`, `child`, `item`) it is important that
clients filter for the corresponding STAC media types
(e.g. `application/json` for all relation types and/or `application/geo+json` for relation type `item`).
Hierarchical links with other media types (e.g. `text/html`) may be present for hierarchical links,
especially in STAC implementations that are also implementing OGC API - Records.

#### Common Media Types in STAC

Expand All @@ -331,15 +335,17 @@ following table lists some of the most common ones you may encounter or use.

*Deprecation notice: GeoTiff previously used the media type `image/vnd.stac.geotiff` and
Cloud Optimized GeoTiffs used `image/vnd.stac.geotiff; profile=cloud-optimized`.
Both can still appear in old STAC implementations, but are deprecated and should be replaced. This will, unfortunately, likely shift in the future as
[OGC sorts out the media types](https://github.com/opengeospatial/geotiff/issues/34).*
Both can still appear in old STAC implementations, but are deprecated and should be replaced.

#### Formats with no registered media type

This section gives recommendations on what to do if you have a format in your links or assets
that does not have an IANA registered type.
Ideally every media type used is on the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml). If
you are using a format that is not on that list we recommend you use [custom content
type](https://restcookbook.com/Resources/using-custom-content-types/). These typically use the `vnd.` prefix, see [RFC 6838
section-3.2](https://tools.ietf.org/html/rfc6838#section-3.2). Ideally the format provider will actually
you are using a format that is not on that list we recommend you use
[custom content type](https://restcookbook.com/Resources/using-custom-content-types/).
These typically use the `vnd.` prefix, see [RFC 6838 section-3.2](https://tools.ietf.org/html/rfc6838#section-3.2).
Ideally the format provider will actually
register the media type with IANA, so that other STAC clients can find it easily. But if you are only using it internally it is
[acceptable to not register](https://stackoverflow.com/questions/29121241/custom-content-type-is-registering-with-iana-mandatory)
it. It is relatively easy to [register](https://www.iana.org/form/media-types) a `vnd` media type.
Expand Down
14 changes: 7 additions & 7 deletions catalog-spec/catalog-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,13 +85,13 @@ For a full discussion of the situations where relative and absolute links are re

The following types are commonly used as `rel` types in the Link Object of a STAC Catalog:

| Type | Description |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. |
| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. |
| child | URL to a child STAC entity (Catalog or Collection). |
| item | URL to a STAC Item. |
| Type | Description | Media Type |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json |
| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | application/json |
| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | application/json |
| child | URL to a child STAC entity (Catalog or Collection). | application/json |
| item | URL to a STAC Item. | application/geo+json (preferred) or application/json |

**Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are
allowed if there is an intent to populate it or its children were removed.
Expand Down
18 changes: 9 additions & 9 deletions collection-spec/collection-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -270,15 +270,15 @@ It is recommended to use the official
The following table explains places where custom STAC `rel` types are used for Collections.
This is done where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context.

| Type | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. |
| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. |
| child | URL to a child STAC entity (Catalog or Collection). |
| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). |
| license | The license URL(s) for the Item SHOULD be specified if the `license` field is **not** a SPDX license identifier. |
| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. |
| Type | Description | Media Type |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json |
| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | application/json |
| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | application/json |
| child | URL to a child STAC entity (Catalog or Collection). | application/json |
| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | application/geo+json (preferred) or application/json |
| license | The license URL(s) for the Item SHOULD be specified if the `license` field is **not** a SPDX license identifier. | Any |
| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | application/json |

A more complete list of possible `rel` types and their meaning in STAC can be found in the
[Using Relation Types](../best-practices.md#using-relation-types) best practice.
Expand Down
14 changes: 7 additions & 7 deletions item-spec/item-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -190,13 +190,13 @@ It is recommended to use the official
The following table explains places where STAC use custom `rel` types are used with Items.
This happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context.

| Type | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
| root | URL to the root STAC entity (Catalog or Collection). |
| parent | URL to the parent STAC entity (Catalog or Collection). |
| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. |
| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. |
| Type | Description | Media Type |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/geo+json (preferred) or application/json |
| root | URL to the root STAC entity (Catalog or Collection). | application/json |
| parent | URL to the parent STAC entity (Catalog or Collection). | application/json |
| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | application/json |
| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | application/geo+json (preferred) or application/json |

A more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation
Types](../best-practices.md#using-relation-types) best practice.
Expand Down
Loading

0 comments on commit 3961d47

Please sign in to comment.