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

Jump to bottom

No multiple parents #1279

Merged
merged 31 commits into from
Jul 17, 2024
Merged

No multiple parents #1279

Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
9c62de3
Clarify unique parent link requirement in STAC catalogs
May 7, 2024
de26fec
collection links for catalog/collection (#1236)
May 7, 2024
1234e80
Updated changelog
May 7, 2024
f9dd9f7
Clarify unique parent link requirement in spec
Jun 11, 2024
26b88b3
updated changelog
Jun 11, 2024
6cc9f7b
clarification
Jun 11, 2024
1e1ccd6
Update CHANGELOG.md
Jun 28, 2024
56dbc1f
updated changelog
emmanuelmathot Jul 4, 2024
06a672a
Clarify internal STAC link
emmanuelmathot Jul 4, 2024
29e0a92
Merge remote-tracking branch 'origin/dev' into nomultiparents
emmanuelmathot Jul 4, 2024
2b73fcc
Update catalog-spec/catalog-spec.md
Jul 9, 2024
194a137
Update collection-spec/collection-spec.md
Jul 9, 2024
441baed
Update item-spec/item-spec.md
Jul 9, 2024
9d862e0
Relation in common metadata
emmanuelmathot Jul 9, 2024
5a9a458
Update common-metadata.md and item-spec.md to reflect required link w…
emmanuelmathot Jul 11, 2024
ee5ec54
suggestion
emmanuelmathot Jul 11, 2024
dec5776
derived_from in bp
emmanuelmathot Jul 11, 2024
80dcd05
restored iri check
emmanuelmathot Jul 12, 2024
3d5f7fa
restored item-spec
emmanuelmathot Jul 12, 2024
665abf9
Update best-practices.md
Jul 12, 2024
04c3244
Update collection-spec/collection-spec.md
Jul 12, 2024
48cd8ac
table padding
emmanuelmathot Jul 12, 2024
3b66538
updated changelog
emmanuelmathot Jul 12, 2024
d8f5bb4
Update item-spec/common-metadata.md
Jul 12, 2024
f16e721
Update item-spec/common-metadata.md
Jul 12, 2024
1ece935
Update item-spec/common-metadata.md
Jul 12, 2024
f12d2d2
Update item-spec/common-metadata.md
Jul 12, 2024
0cfa0ba
Update item-spec/common-metadata.md
Jul 12, 2024
ce0ca8c
Update item-spec/item-spec.md
Jul 12, 2024
8f16ded
Update hierarchical relations in common-metadata.md
emmanuelmathot Jul 12, 2024
06445ab
Merge branch 'dev' into nomultiparents
Jul 17, 2024
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
3 changes: 2 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- The `keywords` field known from Collections is available in common metadata. ([#1187](https://github.com/radiantearth/stac-spec/issues/1187))
- 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))
- Validation for absolute self link in item schema. ([#1281](https://github.com/radiantearth/stac-spec/issues/1281))
- The `collection` relation type is added to the list of known relation types. ([#1236](https://github.com/radiantearth/stac-spec/issues/1236))
- Best practice: Link titles should exactly reflect the title of the corresponding entity ([#1168](https://github.com/radiantearth/stac-spec/issues/1168))

### Changed
Expand All @@ -37,6 +37,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 which media types should be used for the hierarchical relation types
- Clarified in the Markdown specification that GeometryCollections are not allowed as Item Geometry ([#1160](https://github.com/radiantearth/stac-spec/pull/1160))
Expand Down
46 changes: 27 additions & 19 deletions best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,17 +162,17 @@ To avoid issues it is recommended to consistently add a slash at the end of the

**Examples:**

| # | Base URL | Relative URL | Resolved URL |
| - | ----------------------------------------- | ------------------ | --------------------------------------------- |
| 1 | `https://example.com/folder/catalog.json` | `item.json` | `https://example.com/folder/item.json` |
| 2 | `https://example.com/folder` | `item.json` | `https://example.com/item.json` |
| 3 | `https://example.com/folder/` | `item.json` | `https://example.com/folder/item.json` |
| 4 | `https://example.com/folder` | `folder/item.json` | `https://example.com/folder/item.json` |
| 5 | `https://example.com/folder/` | `folder/item.json` | `https://example.com/folder/folder/item.json` |
| 6 | `https://example.com/another/folder` | `../item.json` | `https://example.com/item.json` |
| 7 | `https://example.com/another/folder/` | `../item.json` | `https://example.com/another/item.json` |
| 8 | `https://example.com` | `folder/item.json` | `https://example.com/folder/item.json` |
| 9 | `https://example.com/` | `folder/item.json` | `https://example.com/folder/item.json` |
| # | Base URL | Relative URL | Resolved URL |
| --- | ----------------------------------------- | ------------------ | --------------------------------------------- |
| 1 | `https://example.com/folder/catalog.json` | `item.json` | `https://example.com/folder/item.json` |
| 2 | `https://example.com/folder` | `item.json` | `https://example.com/item.json` |
| 3 | `https://example.com/folder/` | `item.json` | `https://example.com/folder/item.json` |
| 4 | `https://example.com/folder` | `folder/item.json` | `https://example.com/folder/item.json` |
| 5 | `https://example.com/folder/` | `folder/item.json` | `https://example.com/folder/folder/item.json` |
| 6 | `https://example.com/another/folder` | `../item.json` | `https://example.com/item.json` |
| 7 | `https://example.com/another/folder/` | `../item.json` | `https://example.com/another/item.json` |
| 8 | `https://example.com` | `folder/item.json` | `https://example.com/folder/item.json` |
| 9 | `https://example.com/` | `folder/item.json` | `https://example.com/folder/item.json` |

The relative URLs `folder/item.json` and `./folder/item.json` are equivalent.

Expand Down Expand Up @@ -673,19 +673,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*
emmanuelmathot marked this conversation as resolved.
Show resolved Hide resolved

### 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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,22 +83,12 @@ For a full discussion of the situations where relative and absolute links are re

#### 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
Loading