Skip to content
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,8 @@ It includes things like the spatial and temporal extent of the data, the license
It enables discovery at a higher level than individual Item objects, providing a simple way to describe sets of data.
* **[Examples](examples/):** The *[examples/](examples/)* folder contains examples for all three specifications, linked together to form two
complete examples. Each spec and extension links in to highlight particular files that demonstrate key concepts.
* **[Extensions](extensions/):** The *[extensions/](extensions/)* folder is where extensions live. Extensions can extend the
functionality of the core spec or add fields for specific domains. Each extension has at least one *owner*. You can find extension owners in each extension's README or in the [`CODEOWNERS`](.github/CODEOWNERS) file.
* **[Extensions](extensions/README.md)** describe how STAC can use extensions that extend the functionality of the core spec or
add fields for specific domains. Extensions can be published anywhere, although the preferred location for public extensions is in the [GitHub `stac-extensions` organization](https://github.com/stac-extensions).
* **Additional documents:** The supporting documents include a complementary [best practices](best-practices.md)
document, and information on contributing (links in the next section). We also maintain a [changelog](CHANGELOG.md) of
what was modified in each version.
Expand Down
18 changes: 9 additions & 9 deletions best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,12 +247,12 @@ providing them at at the Asset level can prove to be very useful for using the d
- `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`, but an Asset is for one specific time.
- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets with different spatial resolution
than the overall best resolution.
- `eo:bands` ([EO extension](extensions/eo/)): Provide spectral band information, and order of bands, within an individual asset.
- `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](extensions/projection/)): Specify different projection for some assets. If the projection is different
- `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)): Provide spectral band information, and order of bands, within an individual asset.
- `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)): Specify different projection for some assets. If the projection is different
for all assets it should probably not be provided as an Item property. If most assets are one projection, and there is
a single reprojected version (such as a Web Mercator preview image), it is sensible to specify the main projection in the
Item and the alternate projection for the affected asset(s).
- `proj:shape`/`proj:transform` ([projection extension](extensions/projection/)): If assets have different spatial resolutions and slightly different exact bounding boxes, specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection.
- `proj:shape`/`proj:transform` ([projection extension](https://github.com/stac-extensions/projection/)): If assets have different spatial resolutions and slightly different exact bounding boxes, specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection.
- `sar:polarizations` ([sar extension](https://github.com/stac-extensions/sar)): Provide the polarization content and ordering of a specific asset, similar to `eo:bands`.
- `sar:product_type` ([sar extension](https://github.com/stac-extensions/sar)): If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset.

Expand Down Expand Up @@ -338,8 +338,8 @@ actual role requirements.
| land-water | Best Practice | Points to a file that indicates whether a pixel is assessed as being land or water. |
| water-mask | Best Practice | Points to a file that indicates whether a pixel is assessed as being water (e.g. flooding map). | iso-19139 | Best Practice | Points to an [ISO 19139](https://www.iso.org/standard/67253.html) metadata xml file |
| iso-19115 | Best Practice | Points to an [ISO 19115](https://www.iso.org/standard/53798.html) metadata file |
| reflectance, temperature, saturation, cloud, cloud-shadow | [EO Extension](extensions/eo/README.md#best-practices) | See the [table](extensions/eo/README.md#best-practices) in EO for more information, and the definitive list of roles related to EO. |
| incidence-angle, azimuth, sun-azimuth, sun-elevation, terrain-shadow, terrain-occlusion, terrain-illumination | [View Extension](extensions/view/README.md#best-practices) | See the [table](extensions/view/README.md#best-practices) in View for more information, and the definitive list of roles related to viewing angles. |
| reflectance, temperature, saturation, cloud, cloud-shadow | [EO Extension](https://github.com/stac-extensions/eo/README.md#best-practices) | See the [table](https://github.com/stac-extensions/eo/README.md#best-practices) in EO for more information, and the definitive list of roles related to EO. |
| incidence-angle, azimuth, sun-azimuth, sun-elevation, terrain-shadow, terrain-occlusion, terrain-illumination | [View Extension](https://github.com/stac-extensions/view/README.md#best-practices) | See the [table](https://github.com/stac-extensions/view/README.md#best-practices) in View for more information, and the definitive list of roles related to viewing angles. |
| local-incidence-angle, noise-power, amplitude, magnitude, sigma0, beta0, gamma0, date-offset, covmat, prd | [SAR Extension](https://github.com/stac-extensions/sar/README.md#best-practices) | See the [table](https://github.com/stac-extensions/sar/README.md#best-practices) in SAR for more information. , and the definitive list of roles related to SAR. |

Some of the particular asset roles also have some best practices:
Expand Down Expand Up @@ -489,7 +489,7 @@ Some general thinking on what to summarize is as follows:

* Any field that is a range of data (like numbers or dates) is a great candidate to summarize, to give people a sense what values
the data might be. For example in overhead imagery, a
[`view:off_nadir`](extensions/view/README.md#item-properties-and-item-asset-fields) with a range of 0 to 3 would tell people this
[`view:off_nadir`](https://github.com/stac-extensions/view/README.md#item-properties-and-item-asset-fields) with a range of 0 to 3 would tell people this
imagery is all pretty much straight down, while a value of 15 to 40 would tell them that it's oblique imagery, or 0 to 60 that it's
a Collection with lots of different look angles.

Expand All @@ -506,12 +506,12 @@ to include all the different location string values in a summary.

* Fields that consist of arrays are more of a judgement call. For example [`instruments`](item-spec/common-metadata.md#instrument)
is straightforward and recommended, as the elements of the array are a discrete set of options. On the other hand
[`proj:transform`](extensions/projection/README.md#projtransform) makes no sense to summarize, as the union of all the values
[`proj:transform`](https://github.com/stac-extensions/projection/README.md#projtransform) makes no sense to summarize, as the union of all the values
in the array are meaningless, as each Item is describing its transform, so combining them would just be a bunch of random numbers.
So if the values contained in the array are independently meaningful (not interconnected) and there aren't hundreds of potential
values then it is likely a good candidate to summarize.

We do highly recommend including an [`eo:bands`](extensions/eo/README.md#eobands) summary if your Items implement `eo:bands`,
We do highly recommend including an [`eo:bands`](https://github.com/stac-extensions/eo/README.md#eobands) summary if your Items implement `eo:bands`,
especially if it represents just one satellite or constellation. This should be a union of all the potential bands that you
have in assets. It is ok to only add the summary at the Collection level without putting an explicit `eo:bands` summary at the
`properties` level of an Item, since that is optional. This gives users of the Collection a sense of the sensor capabilities without
Expand Down Expand Up @@ -540,7 +540,7 @@ cases should utilize a catalog that follows the listed principles:
* **Only relative href's in structural `links`**: The full catalog structure of links down to sub-catalogs and Items, and their
links back to their parents and roots, should be done with relative URL's. The structural rel types include `root`, `parent`,
`child`, `item`, and `collection`. Other links can be absolute, especially if they describe a resource that makes less sense in
the catalog, like [sci:doi](extensions/scientific/README.md#item-and-collection-fields),
the catalog, like [sci:doi](https://github.com/stac-extensions/scientific/README.md#item-and-collection-fields),
`derived_from` or even `license` (it can be nice to include the license in the catalog, but some licenses live at a canonical
online location which makes more sense to refer to directly). This enables the full catalog to be downloaded or
copied to another location and to still be valid. This also implies no `self` link, as that link must be absolute.
Expand Down
45 changes: 14 additions & 31 deletions extensions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
- [Core STAC Extensions](#core-stac-extensions)
- [Community Extensions](#community-extensions)
- [Extension Maturity](#extension-maturity)
- [List of STAC Community Extensions](#list-of-stac-community-extensions)
- [Proposed extensions](#proposed-extensions)
- [Extending STAC](#extending-stac)
- [Proposing new extensions](#proposing-new-extensions)
Expand All @@ -31,6 +30,8 @@ fields between them to create a shared community extensions. See the section bel
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.

Each extension has at least one *owner*. You can find extension owners in each extension's README or in the [`CODEOWNERS`](../.github/CODEOWNERS) file.

## 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.
Expand All @@ -41,44 +42,26 @@ the Item Asset objects contained in the Item, but may also be used in an individ

## Core STAC Extensions

These extensions are considered stable, and are included directly in this repository.
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 | Identifier | Field Name Prefix | Scope | Description |
|---------------------------------------------|------------|-------------------|------------------|-------------|
| [Electro-Optical](eo/README.md) | eo | eo | Item | 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](projection/README.md) | projection | proj | Item | Provides a way to describe Items whose assets are in a geospatial projection. |
| [Scientific Citation](scientific/README.md) | scientific | sci | Item, Collection | Metadata that indicate from which publication data originates and how the data itself should be cited or referenced. |
| [View Geometry](view/README.md) | view | view | Item | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data |
| [Electro-Optical](https://github.com/stac-extensions/eo/) | eo | eo | Item | 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/) | projection | proj | Item | Provides a way to describe Items whose assets are in a geospatial projection. |
| [Scientific Citation](https://github.com/stac-extensions/scientific/) | scientific | sci | Item, Collection | 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 | view | Item | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data |

## Community Extensions

There are many more extensions that the broader STAC community is working on. These aren't included directly in the
main repository as many are still evolving through active usage. But they are listed here.

### List of STAC Community Extensions

This is a list of all known STAC Community extensions. It is currently more oriented to general domains, but it will include
more data provider specific extensions in the future as well. Any extension with documentation and a published schema
is encouraged to list here.

| Extension Title | Identifier | Field Name Prefix | Scope | Description |
| ------------------------------------------------ | ----------------- | ------------------- | ------------------------- | ----------- |
| [CARD4L](https://github.com/stac-extensions/card4l) | card4l | card4l | Item | How to comply to the CEOS CARD4L product family specifications (Optical and SAR) |
| [Data Cube](https://github.com/stac-extensions/datacube) | datacube | cube | Item, Collection | Data Cube related metadata, especially to describe their dimensions. |
| [File Info](https://github.com/stac-extensions/file) | file | file | Item, Collection | Provides a way to specify file details such as size, data type and checksum for assets in Items and Collections. |
| [Item Asset Definition](https://github.com/stac-extensions/item-assets) | item-assets | - | Collection | Provides a way to specify details about what assets may be found in Items belonging to a Collection. |
| [Label](https://github.com/stac-extensions/label) | label | label | Item, Collection | Items that relate labeled AOIs with source imagery |
| [Point Cloud](https://github.com/stac-extensions/pointcloud) | pointcloud | pc | Item, Collection | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. |
| [Processing](https://github.com/stac-extensions/processing) | processing | processing | Item, Collection | Indicates from which processing chain data originates and how the data itself has been produced. |
| [SAR](https://github.com/stac-extensions/sar) | sar | sar | Item, Collection | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. |
| [Single File STAC](https://github.com/stac-extensions/single-file-stac) | single-file-stac | - | Catalog | An extension to provide a set of Collections and Items within a single file STAC. |
| [Tiled Assets](https://github.com/stac-extensions/tiled-assets) | tiled-assets | tiles | Item, Catalog, Collection | Allows to specify numerous assets using asset templates via tile matrices and dimensions. |
| [Timestamps](https://github.com/stac-extensions/timestamps) | timestamps | - | Item, Collection | Allows to specify numerous timestamps for assets and metadata. |
| [Versioning Indicators](https://github.com/stac-extensions/version) | version | - | Item, Collection | Provides fields and link relation types to provide a version and indicate deprecation. |
There are many more extensions that are part of the broader STAC ecosystem. The center of activity for these is the
[stac-extensions GitHub org](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/).

### Proposed extensions

Beyond the list above there have been a number of extensions that people have proposed to the STAC community. These
Beyond the community extensions there have been a number of extensions that people have proposed to the STAC community. These
can be found in the STAC [Issue Tracker](https://github.com/radiantearth/stac-spec/issues) under the
[new extension](https://github.com/radiantearth/stac-spec/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+extension%22) label.
These are ideas that others would likely use and potentially collaborate on. Anyone is free to add new
Expand Down Expand Up @@ -192,7 +175,7 @@ This rules only applies to the fields defined directly for the Item's `propertie
A STAC extension can have references to additional schemas within the extension schema.
These files should be kept together in order to preserve relative `$ref` links.

See the [EO](eo/) extension file structure as an example.
See the [EO](https://github.com/stac-extensions/eo/) extension file structure as an example.
* Specification examples should be stored in an `examples` directory.
* The specification schema file(s) should be stored in a `json-schema` directory.

Expand Down
Loading