Skip to content

Commit

Permalink
Merge pull request #1279 from radiantearth/nomultiparents
Browse files Browse the repository at this point in the history 
No multiple parents
  • Loading branch information
Emmanuel Mathot committed Jul 17, 2024
2 parents 8976aed + 06445ab commit b71e6e9
Show file tree
Hide file tree
Showing 6 changed files with 100 additions and 77 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- New fields `method`, `headers` and `body` in the Link Object. ([#1198](https://github.com/radiantearth/stac-spec/issues/1198))
- The `license` field additionally supports SPDX expressions and the value `other`.
- The `roles` field known from Assets and Providers is available in common metadata. ([#1267](https://github.com/radiantearth/stac-spec/issues/1267))
- The `collection` relation type is added to the list of known relation types. ([#1236](https://github.com/radiantearth/stac-spec/issues/1236))
- The `item_assets` field in Collections are integrated from extension into the core Collection spec. ([#1275](https://github.com/radiantearth/stac-spec/issues/1275))
- Validation for absolute self link in item schema. ([#1281](https://github.com/radiantearth/stac-spec/issues/1281))
- Best practice: Link titles should exactly reflect the title of the corresponding entity ([#1168](https://github.com/radiantearth/stac-spec/issues/1168))
Expand All @@ -27,6 +28,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- All JSON Schema `$id` values no longer have `#` at the end.
- Two spatial bounding boxes in a Collection don't make sense and will be reported as invalid by the schema. ([#1243](https://github.com/radiantearth/stac-spec/issues/1243))
- Clarify in descriptions that start_datetime and end_datetime are inclusive bounds ([#1280](https://github.com/radiantearth/stac-spec/issues/1280))
- Moved the STAC structural relations in common metadata spec

### Deprecated

Expand All @@ -39,6 +41,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
### Fixed

- Several typos and minor language changes
- Clarification on unique parent link requirement ([#1279](https://github.com/radiantearth/stac-spec/pull/1279))
- Clarified that collection IDs should be unique across all collections in the corresponding root catalog
- Clarified that item IDs should be unique per collection
- Clarified which media types should be used for the hierarchical relation types
Expand Down
24 changes: 16 additions & 8 deletions best-practices.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -674,19 +674,27 @@ with the `type` field) to communicate the structure and content of related entit
Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) as much as possible. The following table describes
a number of the common official relations that are used in production STAC implementations.

| Type | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. |
| canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. |
| via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel metadata XML, etc) |
| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. |
| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. |
| preview | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#list-of-asset-roles) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. |
| Type | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. |
| canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. |
| via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel metadata XML, etc) |
| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. |
| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. |
| preview | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#list-of-asset-roles) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. |
| derived_from | URL to a STAC Entity that was used as input data in the creation of this Entity. |

Being liberal with the `links` also means that it's ok to have repeated links with the same `href`. For example the
`parent` and `root` relation types will point at the same file when the child is directly below the root, and it is
recommended to include both.

#### Derived from relation (`derived_from`)

A full provenance model is far beyond the scope of STAC,
and the goal is to align with any good independent spec that comes along for that.
But the `derived_from` field is seen as a way to encourage fuller specs and at least start a linking
structure that can be used as a jumping off point for more experiments in provenance tracking.

### Versioning for Catalogs

In the Item and Collection STAC JSON, versions and deprecation can be indicated with the
Expand Down
22 changes: 6 additions & 16 deletions catalog-spec/catalog-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,22 +72,12 @@ This object is described in the [STAC Common Metadata](../item-spec/common-metad

#### Relation types

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

| 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.

There are additional `rel` types in the [Using Relation Types](../best-practices.md#using-relation-types) best practice, but as
they are more typically used in Collections, as Catalogs tend to just be used to structure STAC organization, so tend to just use
the ones above.
All the [common relation types](../item-spec/common-metadata.md#relation-types) can be used in catalog.
A `self` and a `root` links are STRONGLY RECOMMENDED.
Non-root Catalogs SHOULD include a `parent` link to their parent.

> \[!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.
## Media Types

Expand Down
32 changes: 8 additions & 24 deletions collection-spec/collection-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -269,30 +269,14 @@ This object is described in the [STAC Common Metadata](../item-spec/common-metad

#### Relation types

STAC Collections use a variety of `rel` types in the link object,
to describe the exact nature of the link between this Collection and the entity it is linking to.
It is recommended to use the official
[IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible.
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 | 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.

**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog.
This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs,
it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection
with the [`collection` relation type](../item-spec/item-spec.md#relation-types).
All the [common relation types](../item-spec/common-metadata.md#relation-types) can be used in Collection.
A `self` and a `root` links are STRONGLY RECOMMENDED.
Non-root Collections SHOULD include a `parent` link to their parent.

> \[!NOTE] The STAC Catalog specification requires a link to at least one `item` or `child` Catalog.
> This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs,
> it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection
> with a link with the [`collection` relation type](../item-spec/item-spec.md#relation-types).
### Asset Object

Expand Down
Loading

0 comments on commit b71e6e9

Please sign in to comment.