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.

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

Move less mature extensions out of core repo #1024

Merged
merged 14 commits into from
Mar 3, 2021
12 changes: 0 additions & 12 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,7 @@
#
# https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-code-owners

/extensions/datacube/ @m-mohr
/extensions/eo/ @matthewhanson
/extensions/file/ @m-mohr
/extensions/item-assets/ @matthewhanson
/extensions/label/ @jisantuc
/extensions/pointcloud/ @matthewhanson
/extensions/processing/ @emmanuelmathot
/extensions/projection/ @matthewhanson
/extensions/sar/ @emmanuelmathot @m-mohr
/extensions/sat/ @emmanuelmathot
/extensions/scientific/ @m-mohr
/extensions/single-file-stac/ @matthewhanson
/extensions/tiled-assets/ @constantinius
/extensions/timestamps/ @m-mohr
/extensions/version/ @m-mohr
/extensions/view/ @matthewhanson
5 changes: 2 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- 'via' and 'canonical' rel types as options in items.
- Assets on Collections are now defined in the core Collection specification ([#1008](https://github.com/radiantearth/stac-spec/pull/1008))
- Added clarification about how collection-level asset object properties do not remove the need for item-level asset object properties in the `item-assets` extension ([#880](https://github.com/radiantearth/stac-spec/pull/880))
- Added [processing extension](extensions/processing/README.md)
- Added [file info extension](extensions/file/README.md) ([#879](https://github.com/radiantearth/stac-spec/pull/879), [#921](https://github.com/radiantearth/stac-spec/issues/921))
- Added additional acquisition parameters in the `sat` extension: sat:platform_international_designator, sat:absolute_orbit, sat:anx_datetime* ([#894](https://github.com/radiantearth/stac-spec/pull/894))
- Added reference to three new (non-core) extensions: [processing](https://github.com/stac-extensions/processing), [file info](https://github.com/stac-extensions/file) and [card4l](https://github.com/stac-extensions/card4l).
- 'summaries' are now available in the Catalog spec, so both catalogs and collections can make use of it. ([#903](https://github.com/radiantearth/stac-spec/issues/903))
- Recommendation to enable CORS
- A 'visual' option as an asset role.
Expand All @@ -40,6 +38,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

- Checksum extension (field `checksum:multihash`). Use File Info extension (field `file:checksum`) instead for assets. There's no replacement for links.
- Collection Assets extension, as the core construct of Assets in a Collection is now part of the core Collection spec. No change is required except removing `collection-assets` from the list of `stac_extensions`.
- Numerous extensions (Data Cube, Item Assets, Point Cloud, SAR, Single File STAC, Tiled Assets, Timestamps & Versioning) have been moved out of the core specification, into their own repos in the [stac-extensions](https://github.com/stac-extensions/) GitHub organization. They must now be referred to by their schemas directly - the name shortcuts for them are no longer valid.

### Fixed

Expand Down
20 changes: 13 additions & 7 deletions best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -251,8 +251,8 @@ than the overall best resolution.
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.
- `sar:polarizations` ([sar extension](extensions/sar/)): Provide the polarization content and ordering of a specific asset, similar to `eo:bands`.
- `sar:product_type` ([sar extension](extensions/sar/)): If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset.
- `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.

### Working with Media Types

Expand Down Expand Up @@ -338,7 +338,7 @@ actual role requirements.
| 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. |
| local-incidence-angle, noise-power, amplitude, magnitude, sigma0, beta0, gamma0, date-offset, covmat, prd | [SAR Extension](extensions/sar/README.md#best-practices) | See the [table](extensions/sar/README.md#best-practices) in SAR for more information. , and the definitive list of roles related to SAR. |
| 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 @@ -593,13 +593,19 @@ a number of the common official relations that are used in production STAC imple

### Versioning for Catalogs

In the Item and Collection STAC JSON, versions and deprecation can be indicated with the [Versioning Indicators Extension](./extensions/version).
In the Item and Collection STAC JSON, versions and deprecation can be indicated with the [Versioning Indicators Extension](https://github.com/stac-extensions/version).

The [Items and Collections API Version Extension](https://github.com/radiantearth/stac-api-spec/tree/master/extensions/version/README.md) provides endpoints and semantics for keeping and accessing previous versions of Collections and Items. The same semantics can be used in static catalogs to preserve previous versions of the documents and link them together.
The [Items and Collections API Version Extension](https://github.com/stac-extensions/version/) provides endpoints and
semantics for keeping and accessing previous versions of Collections and Items. The same semantics can be used in static
catalogs to preserve previous versions of the documents and link them together.

In order to achieve this, the static catalog must make sure that for every record created, a copy of the record is also created in a separate location and it is named with the version id adopted by the catalog. See [here](https://github.com/radiantearth/stac-api-spec/tree/master/extensions/version/README.md#version-id) for recommendations on versioning schema.
In order to achieve this, the static catalog must make sure that for every record created, a copy of the record is also
created in a separate location and it is named with the version id adopted by the catalog. See
[here](https://github.com/stac-extensions/version/README.md#version-id) for recommendations on versioning schema.

The main record should also provide a link to the versioned record following the linking patterns described [here](./extensions/version/README.md#relation-types). For every update to the record, the same cycle is repeated:
The main record should also provide a link to the versioned record following the linking patterns described
[here](https://github.com/stac-extensions/version/README.md#relation-types). For every update to the record, the same
cycle is repeated:

1. Add link from the updated record to the previous version
2. Create a copy of the updated record and name it correctly
Expand Down
2 changes: 1 addition & 1 deletion catalog-spec/catalog-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ also a valid STAC Catalog.

#### stac_extensions

A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the Catalog diverge, you can specify the URL of the JSON schema file.
A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For [core extensions](../extensions/README.md#core-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `view` for the View extension. If the versions of the extension and the Catalog diverge, you can specify the URL of the JSON schema file.
This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of extensions.

### Link Object
Expand Down
23 changes: 10 additions & 13 deletions collection-spec/collection-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,16 @@ it is a fairly unique name, or their name combined with the domain they operate

#### stac_extensions

A list of extensions the Collection implements. This does NOT declare the extensions of child Catalogs or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [extensions](../extensions/README.md#list-of-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `version` for the Versioning Indicators extension. If the versions of the extension and the Collection diverge, you can specify the URL of the JSON schema file.
This list must only contain extensions that extend the Collection itself, see the the 'Scope' column in the list of extensions. If an extension has influence on multiple parts of the whole STAC structure, it must be listed in all affected parts (e.g. Collection and Item for the `datacube` extension). If a structure such as the summaries extension provide fields in their JSON structure, these extensions must not be listed here as they don't extend the Collection itself. For example, if a Collection includes the field `sat:platform` in the summaries, the Collection still does not list the `sat` extension in the `stac_extensions` field.
A list of extensions the Collection implements. This does NOT declare the extensions of child Catalogs or Items. The list
contains URLs to the JSON Schema files it can be validated against. For official
[extensions](../extensions/README.md#core-stac-extensions), a "shortcut" can be used. This means you can specify the folder
name of the extension, for example `view` for the View extension. If the versions of the extension and
the Collection diverge, you can specify the URL of the JSON schema file. This list must only contain extensions that extend
the Collection itself, see the the 'Scope' column in the list of extensions. If an extension has influence on multiple parts
of the whole STAC structure, it must be listed in all affected parts (e.g. Collection and Item for the `datacube` extension).
If a structure such as the summaries extension provide fields in their JSON structure, these extensions must not be listed
here as they don't extend the Collection itself. For example, if a Collection includes the field `sat:platform` in the
summaries, the Collection still does not list the `sat` extension in the `stac_extensions` field.

#### license

Expand Down Expand Up @@ -84,7 +92,6 @@ There are a few guidelines for using the asset construct at the Collection level

* Collection-level assets SHOULD NOT list any files also available in Items.
* If possible, item-level assets are always the preferable way to expose assets.
* To list what assets are available in Items see the [Item Assets Definition Extension](../extensions/item-assets/README.md).

Collection-level assets can be useful in some scenarios, for example:
1. Exposing additional data that applies Collection-wide and you don't want to expose it in each Item. This can be Collection-level metadata or a thumbnail for visualization purposes.
Expand Down Expand Up @@ -223,13 +230,3 @@ STAC Collections which don't link to any Item are called **standalone Collection
To describe them with more fields than the Collection fields has to offer, it is allowed to re-use the metadata fields defined by extensions for Items in the `summaries` field.
This makes much sense for fields such as `platform` or `proj:epsg`, which are often the same for a whole Collection, but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection.
The data provider is free to decide, which fields are reasonable to be used.

## Extensions

Commonly used extensions for the STAC Collection specification:

* [Item Assets Definition](../extensions/item-assets/README.md): Allows to indicate the structure of the Item assets.
* [Scientific Citation extension](../extensions/scientific/README.md): Add fields to indicate citations and DOIs.
* [Versioning Indicators extension](../extensions/version/README.md): Allows versioning by adding the fields `version` and `deprecated`.

The [extensions page](../extensions/README.md) gives a full overview about relevant extensions for STAC Collections.
7 changes: 3 additions & 4 deletions examples/extended-item.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"stac_extensions": [
"eo",
"projection",
"sat",
"scientific",
"view"
],
"type": "Feature",
Expand Down Expand Up @@ -69,16 +69,15 @@
0,
1
],
"sat:orbit_state": "ascending",
"sat:relative_orbit": 34523,
"view:sun_elevation": 54.9,
"view:off_nadir": 3.8,
"view:sun_azimuth": 135.7,
"rd:type": "scene",
"rd:anomalous_pixels": 0.14,
"rd:earth_sun_distance": 1.014156,
"rd:sat_id": "cool_sat2",
"rd:product_level": "LV3A"
"rd:product_level": "LV3A",
"sci:doi": "10.5061/dryad.s2v81.2/27.2"
},
"collection": "simple-collection",
"links": [
Expand Down
Loading