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

Add text around when to include an extension in stac_extensions #1123

Merged
merged 8 commits into from
May 11, 2021
Merged

Add text around when to include an extension in stac_extensions #1123

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d87813d
Clarify when to include extensions in stac_extensions
lossyrob May 5, 2021
cd08d4a
Fix TOC ordering in extensions
lossyrob May 5, 2021
59a8cf4
Update CHANGELOG
lossyrob May 5, 2021
ea3ee26
reorg and edits
cholmes May 5, 2021
b24066e
update from PR review
cholmes May 10, 2021
c9323e4
line break for linting
cholmes May 10, 2021
bf02447
updates from PR review
cholmes May 11, 2021
90a2cbd
line break for linting
cholmes May 11, 2021
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 @@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090))
- Recommendation to include both `root` and `parent` relation types when they point at the same file. ([#1098](https://github.com/radiantearth/stac-spec/issues/1098))
- Overview section linking to various foundational standards. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111))
- Added clarification around when an extension should be included in `stac_extensions` ([#1123](https://github.com/radiantearth/stac-spec/pull/1123))

### Changed

Expand Down
60 changes: 49 additions & 11 deletions extensions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
# Extensions

- [Overview](#overview)
- [General Conventions](#general-conventions)
- [Using Extensions](#using-extensions)
- [Extension IDs in `stac_extensions`](#extension-ids-in-stac_extensions)
- [Stable STAC Extensions](#stable-stac-extensions)
- [Community Extensions](#community-extensions)
- [Extension Maturity](#extension-maturity)
- [Proposed extensions](#proposed-extensions)
- [Extending STAC](#extending-stac)
- [General Conventions](#general-conventions)
- [Proposing new extensions](#proposing-new-extensions)
- [Extension Maturity](#extension-maturity)
- [Prefixes](#prefixes)
- [Use of arrays and objects](#use-of-arrays-and-objects)

Expand All @@ -33,15 +35,37 @@ can be aware of it.

Each extension has at least one *owner*. You can find extension owners in each extension's README.

## General Conventions

1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object,
rather than directly in the Item object.
2. In general, additional attributes that apply to an Item Asset should also be allowed in Item Properties and vice-versa.
For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in
the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset.
3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or
[Collection](../collection-spec/collection-spec.md) should be added to the root of the object.
## Using Extensions

When deciding how to model data in STAC it is highly recommended to first look at the [list of
extensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version. This
increases interoperability, as users know that the meaning of your fields is the same as in other STAC
implementations. Many clients will also understand more mature extensions for better display and querying.

To incorporate an extension in STAC the 'extension ID' of the extension must be added to the `stac_extensions`
array of the STAC [Catalog](../catalog-spec/catalog-spec.md#stac_extensions),
[Collection](../collection-spec/collection-spec.md#stac_extensions) or [Item](../item-spec/item-spec.md#stac_extensions)
object. This identifier is a link to the JSON Schema URL that validates the fields in the extension, so STAC validators
can fetch the Schema to validate that the STAC object properly follows the extension. These JSON Schema URLs also act as
identifiers for specific version of the extension that the STAC object implements. The extension ID can be
cholmes marked this conversation as resolved.
Show resolved Hide resolved
found listed as the 'identifier' in the second line of the README of any extension made with the [extension
template](https://github.com/stac-extensions/template), and new ones get published automatically with any release made
with the template.

### Extension IDs in `stac_extensions`

The logic for when an object should list an extension ID in its `stac_extension` array is as follows:

- If the object directly implements the extension, the `stac_extensions` of that object should contain the extension ID.
m-mohr marked this conversation as resolved.
Show resolved Hide resolved
- If an Asset implements fields of the extension, then `stac_extensions` of the Item or Collection which holds that
Asset should contain the extension ID.
- If a Collection [summary](../collection-spec/collection-spec.md#summaries) contains Item fields that implement an extension, then
the `stac_extensions` array of that Collection should list the extension ID. For example, if a Collection `summaries` field
contains a summary of `eo:bands`, then that Collection should have the EO extension JSON Schema URL in the `stac_extensions` array.
- If an object implements an extension that results in fields from a separate extension to be referenced, then the latter extension
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add that this is usually the case, but extensions may specify otherwise (i.e. they say explicitly that stac_extensions should not be populated?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we don't yet have a case of this I think we should just leave as is. If an extension comes that has a good reason to do it in another way we can tweak this.

ID should be included in the `stac_extensions` array for that object. For example, if a Collection implements the
[item_assets](https://github.com/stac-extensions/item-assets) extension, and in the `item_assets` field there is an Asset Definition
which includes `eo:bands`, then the EO extension ID should be listed in that Collection's `stac_extensions`.

## Stable STAC Extensions

Expand Down Expand Up @@ -79,6 +103,20 @@ with existing extensions as well as possible and may even re-use fields and thei
into a new extension that combines commonly used fields across multiple extensions.
Best practices for extension proposals are still emerging in this section.

### General Conventions

Creating a new extension involves defining a set of logically grouped fields, and specifying what the allowed values
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not all extensions may define fields, some may just define behavior (e.g. formerly the Commons extension) or define e.g. just rel types or asset roles.

for those fields are. This should be done in the extension text and in JSON Schema, to provide validation. While one
can theoretically add fields anywhere in JSON there are some conventions as to where to add them in STAC objects.

1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object,
rather than directly in the Item object.
2. In general, additional attributes that apply to an Item Asset should also be allowed in Item Properties and vice-versa.
For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in
the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset.
3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or
[Collection](../collection-spec/collection-spec.md) should be added to the root of the object.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe as 4. point, extensions may also extend other extensions, e.g. to add new fields to eo:bands/raster:bands or so?

### Proposing new extensions

Extensions can be hosted anywhere, but should use the
Expand Down