Skip to content

Commit

Permalink
Update extensions readme (#1205)
Browse files Browse the repository at this point in the history
  • Loading branch information
@m-mohr
m-mohr authored Jan 9, 2023
1 parent bdd391a commit a5c65d7
Showing 1 changed file with 75 additions and 78 deletions.
153 changes: 75 additions & 78 deletions extensions/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,13 @@

- [Overview](#overview)
- [Using Extensions](#using-extensions)
- [Extension IDs in `stac_extensions`](#extension-ids-in-stac_extensions)
- [Stable STAC Extensions](#stable-stac-extensions)
- [Extension identifiers in `stac_extensions`](#extension-identifiers-in-stac_extensions)
- [Community Extensions](#community-extensions)
- [Proposed extensions](#proposed-extensions)
- [Extension Maturity](#extension-maturity)
- [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 @@ -18,74 +17,74 @@
One of the most important aspects of the SpatioTemporal Asset Catalog specification is its extensibility. The core
STAC specification defines only a minimal core, but is designed for extension. It is expected that most real-world
implementations will use several 'extensions' to fully describe their data. This document describes how extensions
work, and links to the 'core' extensions included in this repo, as well as to a variety of 'community' extensions.
work.

**For the complete list of available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).**
**For a list of most available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).**
Please note the [extension maturity](#extension-maturity) for each extension.

Extensions to the core STAC specification provide additional JSON fields that can be used to better describe
Extensions to the core STAC specification provide additional fields that can be used to better describe
the data. Most tend to be about describing a particular domain or type of data, but some imply
functionality.

Extensions include a JSON Schema precisely describing the structure, a natural language description of the fields, and thorough examples.

Anybody can create an extension for their data, and data providers often work together to share
fields between them to create a shared community extensions. See the section below on '[Extending STAC](#extending-stac)')
for information on how to get started. And everyone is encouraged to link to the extension in the table below, so others
can be aware of it.
fields between them to create a shared community extension. See the section below on '[Extending STAC](#extending-stac)')
for information on how to get started. Everyone is encouraged to add their extensions to the
[STAC extensions overview page](https://stac-extensions.github.io/), so others can be aware of it.

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

## 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
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`
To incorporate an extension in STAC the 'Identifier' 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.
object. This identifier is a URL to the JSON Schema that allows to validate the fields in the extension.
These JSON Schema URLs also include the version number of the extension. The 'Identifier' can usually be
found in the first lines of the README of any extension made with the
[extension template](https://github.com/stac-extensions/template).

### Extension identifiers in `stac_extensions`

Generally, if an extension is implemented in a STAC file in a place where the extension scope applies to,
the extension identifier should be added to the `stac_extension` array. The scope of an extension is usually
explained in the README of an extension. Implementing an extension by following the specified requirements usually means including
fields, but occasionally also means implementing alternate behaviors.

There is no direct inheritance between children and parents though, so if for example an Item implements an extension,
but the Collection doesn't reflect the usage of the extension, the extension identifier must only be added to the
`stac_extension` array in the Item, but not to the Collection. If the Collection itself implements the extension though
or 'summarizies' a field in Collection Summaries or Item Asset Definitions, the extension identifier should be added to the
Collection.

**Examples**

- If the Catalog, Collection or Item object directly implements the extension,
the `stac_extensions` of that object should contain the extension Identifier.
- If an Asset object implements an extension, the `stac_extensions` of the Item or Collection which holds that
Asset should contain the extension identifier.
- 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
the `stac_extensions` array of that Collection should list the extension identifier. 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
identifier 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

These extensions are considered stable and are widely used in many production implementations. As additional extensions advance
through the [Extension Maturity](#extension-maturity) classification they, will be added here.

| Extension Title | Description |
|-----------------------------------------------------------------------|--------------------------------|
| [Electro-Optical](https://github.com/stac-extensions/eo/) | Covers electro-optical data that represents a snapshot of the Earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. |
| [Projection](https://github.com/stac-extensions/projection/) | Provides a way to describe Items whose assets are in a geospatial projection. |
| [Scientific Citation](https://github.com/stac-extensions/scientific/) | Metadata that indicate from which publication data originates and how the data itself should be cited or referenced. |
| [View Geometry](https://github.com/stac-extensions/view/) | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data |
which includes `eo:bands`, then the EO extension identifier should be listed in that Collection's `stac_extensions`.

## Community Extensions

There are many more extensions that are part of the broader STAC ecosystem. The center of activity for these is the
[stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories. For
an overview of all extensions with their [Extension Maturity](#extension-maturity) classification see the
[STAC extensions overview page](https://stac-extensions.github.io/).
Everyone is welcome to contribute extensions to the STAC ecosystem. The center of activity for these is the
[stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories.
Some of these, especially the [stable extensions](#extension-maturity), are observed by the STAC PSC.
The community can also host STAC extensions in other places, but we encourage the community to
at least list them in the [STAC extensions overview page](https://stac-extensions.github.io/) so that
everyone can be aware of all extensions at any time and a high level of interoperability is possible.

### Proposed extensions

Expand All @@ -96,18 +95,37 @@ These are ideas that others would likely use and potentially collaborate on. Any
ideas there, and see the section below on [proposing new extensions](#proposing-new-extensions) for the
workflow to advance ideas into full-fledged community extensions.

## Extension Maturity

There are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions
listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how
much they can count on the extension.

| Maturity Classification | Min Impl # | Description | Stability |
| ----------------------- | ----------- | ----------- | --------- |
| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback. |
| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. User can generally count on an extension at this maturity level. | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. |
| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. |
| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported |

Maturity mostly comes through diverse implementations, so the minimum number of implementations
column is the main gating function for an extension to mature. But extension authors can also
choose to hold back the maturity advancement if they don't feel they are yet ready to commit to
the less breaking changes of the next level.

## Extending STAC

Anyone is welcome to create an extension. There are several types of extensions, some just add additional fields,
Anyone is welcome to extend STAC and evolve the additions into a full STAC extension with a README, JSON Schema and examples.
There are several types of extensions, some just add additional fields,
some change the behavior of STAC and some introduce completely new functionality. New extensions should try to align
with existing extensions as well as possible and may even re-use fields and their definitions until they may get split
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
for those fields are. This should be done in the extension text (README) 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,
Expand All @@ -116,8 +134,9 @@ can theoretically add fields anywhere in JSON there are some conventions as to w
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.
[Collection](../collection-spec/collection-spec.md) should be added to the top-level of the object.
4. All other objects can generally also be extended, e.g. Link Objects, Provider Objects, Band Objects, etc.
5. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema.

### Proposing new extensions

Expand All @@ -126,38 +145,16 @@ Extensions can be hosted anywhere, but should use the
as a starting point. If you'd like to add a repository to the [stac-extensions](https://github.com/stac-extensions)
GitHub organization, just ask on [Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby)! This is fine for
work-in-progress extensions. You can also host the extension repository in your own GitHub account, and optionally
transfer it to the stac-extensions org later.
transfer it to the stac-extensions organization later.

For new extensions that require community discussion, we recommend the following workflow:

- Use the stac-extensions template to sketch out your proposed extension
- Open an issue on this repository with the prefix "New Extension: " and describe the extension. Include a link to the extension repository.
- Discussion can occur on that issue, or discussion can move to issues/pull requests on the extension repository directly.
Also post it in the Gitter chat for broader recognition.
- Discussion should take place as issues/pull requests on the extension repository directly, but can als occur on the issue created before.
- Once the extension has an initial release, the issue on stac-spec will be closed.

### Extension Maturity

There are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions
listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how
much they can count on the extension. Extension creators are encouraged to list their extensions here, even if it is just
an rough proposal, so others can potentially collaborate.

| Maturity Classification | Min Impl # | Description | Stability |
| ----------------------- | ----------- | ----------- | --------- |
| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback |
| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. Can generally count on an extension at this maturity level | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. |
| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. |
| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported |

Maturity mostly comes through diverse implementations, so the minimum number of implementations
column is the main gating function for an extension to mature. But extension authors can also
choose to hold back the maturity advancement if they don't feel they are yet ready to commit to
the less breaking changes of the next level.

A 'mature' classification level will likely be added once there are extensions that have been
stable for over a year and are used in twenty or more implementations.

### Prefixes

A STAC Item can combine schema information from several different sources - the core STAC Item information,
Expand Down

0 comments on commit a5c65d7

Please sign in to comment.