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

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 1 commit
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
9c62de3
Clarify unique parent link requirement in STAC catalogs
emmanuelmathot May 7, 2024
de26fec
collection links for catalog/collection (#1236)
emmanuelmathot May 7, 2024
1234e80
Updated changelog
emmanuelmathot May 7, 2024
f9dd9f7
Clarify unique parent link requirement in spec
emmanuelmathot Jun 11, 2024
26b88b3
updated changelog
emmanuelmathot Jun 11, 2024
6cc9f7b
clarification
emmanuelmathot Jun 11, 2024
1e1ccd6
Update CHANGELOG.md
emmanuelmathot 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
emmanuelmathot Jul 9, 2024
194a137
Update collection-spec/collection-spec.md
emmanuelmathot Jul 9, 2024
441baed
Update item-spec/item-spec.md
emmanuelmathot 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
emmanuelmathot Jul 12, 2024
04c3244
Update collection-spec/collection-spec.md
emmanuelmathot Jul 12, 2024
48cd8ac
table padding
emmanuelmathot Jul 12, 2024
3b66538
updated changelog
emmanuelmathot Jul 12, 2024
d8f5bb4
Update item-spec/common-metadata.md
emmanuelmathot Jul 12, 2024
f16e721
Update item-spec/common-metadata.md
emmanuelmathot Jul 12, 2024
1ece935
Update item-spec/common-metadata.md
emmanuelmathot Jul 12, 2024
f12d2d2
Update item-spec/common-metadata.md
emmanuelmathot Jul 12, 2024
0cfa0ba
Update item-spec/common-metadata.md
emmanuelmathot Jul 12, 2024
ce0ca8c
Update item-spec/item-spec.md
emmanuelmathot Jul 12, 2024
8f16ded
Update hierarchical relations in common-metadata.md
emmanuelmathot Jul 12, 2024
06445ab
Merge branch 'dev' into nomultiparents
emmanuelmathot 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
Prev Previous commit
Next Next commit
derived_from in bp
  • Loading branch information
@emmanuelmathot
emmanuelmathot committed Jul 11, 2024
commit dec5776320f5d3a7de4b093bb14fc2d387337043
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*

### Versioning for Catalogs

In the Item and Collection STAC JSON, versions and deprecation can be indicated with the
Expand Down
44 changes: 17 additions & 27 deletions item-spec/common-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ or [Collection Asset](../collection-spec/collection-spec.md#asset-object).
- [mission](#mission)
- [gsd](#gsd)
- [Relation types](#relation-types)
- [STAC Relation Types](#stac-relation-types)
- [STAC Structure relation](#stac-structure-relation)
- [Self relation](#self-relation)
- [Root and parent relation](#root-and-parent-relation)
- [Collection relation](#collection-relation)
- [Additional relations](#additional-relations)
- [Child relation](#child-relation)
- [Collection and item relation](#collection-and-item-relation)

Various *examples* are available in the folder [`examples`](../examples/).
*JSON Schemas* can be found in the folder [`json-schema`](json-schema/).
Expand Down Expand Up @@ -113,7 +113,11 @@ it is RECOMMENDED to supplement the STAC Item with the license text in a separat
If no link to a license is included and the `license` field is set to `other` (or one of the deprecated values),
the data is private, and consumers have not been granted any explicit right to use it.

The [license](#additional-relations) URL(s) for the resource SHOULD be specified if the `license` field is **not** a SPDX license identifier.
### License relation

| Type | Description |
| ------- | -------------------------------------------------------------------------------------------------------------------- |
| license | The license URL(s) for the resource SHOULD be specified if the `license` field is **not** a SPDX license identifier. |

## Provider

Expand Down Expand Up @@ -221,7 +225,7 @@ to describe the exact nature of the link between the STAC object and the entity
It is recommended to use the official
[IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible.

### STAC Relation Types
### STAC Structure relation

The following table lists the STAC-specific `rel` types that are used in the `links` object of a STAC entity
to link with other STAC entities in the same catalog.
Expand All @@ -231,8 +235,8 @@ to link with other STAC entities in the same catalog.
| self | *Absolute* URL to the location that the STAC file can be found online, if available. | application/json |
| root | URL to the root STAC entity ([Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md)). | application/json |
| parent | URL to the parent STAC entity ([Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md)). | application/json |
| collection | URL to the parent Collection. *Absolute* URLs should be used whenever possible. | application/json |
| child | URL to a child STAC entity ([Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md)). | application/json |
| collection | URL to the parent Collection. *Absolute* URLs should be used whenever possible. | application/json |
| item | URL to a STAC Item. | application/geo+json (preferred) or application/json |

#### Self relation
Expand All @@ -253,27 +257,13 @@ Different variations could be:
- a different encoding (see the `type` property), e.g. a HTML version in addition to JSON
- a different language (see the `hreflang` property). e.g. a German version in addition to English

#### Collection relation

The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Collection.

#### Item relation

All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](#collection-relation).

### Additional relations
#### Child relation

| Type | Description | Media Type |
| ------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------- |
| 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 Entity that was used as input data in the creation of this Entity. | application/json |
The `child` relation is **ONLY** used to link a catalog or collection to a child catalog or collection.

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.
#### Collection and item relation

#### 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*
The `collection` and `item` relations are used to link to the parent collection and a child Item, respectively.
It is RECOMMENDED to link an `item` from a collection and not directly from a catalog.
All Items linked from a Collection MUST refer back to its Collection with the `collection` relation type
The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Collection.
1 change: 0 additions & 1 deletion item-spec/item-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@
- [Additional Fields](#additional-fields)
- [Link Object](#link-object)
- [Relation types](#relation-types)
- [derived\_from](#derived_from)
- [Collections](#collections)
- [Asset Object](#asset-object)
- [Asset Media Type](#asset-media-type)
Expand Down