diff --git a/CHANGELOG.md b/CHANGELOG.md index d96c740e..7a0ad5f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/extensions/README.md b/extensions/README.md index 3b04a1f2..151983d0 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -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) @@ -33,15 +35,38 @@ 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 +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 (by following the specified requirements - usually by including +fields, but occasionally implementing alternate behaviors), the `stac_extensions` of that object should contain the extension ID. +- 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 + 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 @@ -79,6 +104,21 @@ 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 usually involves defining a set of logically grouped fields, and specifying what the allowed values +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. +4. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema. + ### Proposing new extensions Extensions can be hosted anywhere, but should use the