STAC 1.1.0-beta.1 released

It’s already been three years since the last release of the STAC specification and it’s time to improve the specification based on feedback from the STAC community that we received since the last release. After some intense time of discussions and document editing, we are proud to announce the release of STAC 1.1.0-beta.1.

The focus has been the addition of a common band construct to unify the fields eo:bands and raster:bands. Additionally, Item Asset Definition (field item_assets) - formerly a popular STAC extension - is now part of the core specification. Various additional fields have been made available via the common metadata mechanism, e.g. keywords, roles, data_type and unit. We collaborated closely with the editors of OGC API - Records to align better with STAC, which resulted, for example, in a change to the license field. The link object was extended to support additional HTTP mechanisms such as HTTP methods other than GET and HTTP headers. The best practices have evolved and various minor changes and clarifications were integrated throughout the specification.

This is a beta release with the option to make changes before a final 1.1.0 release if the feedback of the STAC community asks for it in the next weeks. At the time of this beta release, no further changes are planned. You can find the open issues for 1.1.0 in the GitHub issue tracker if any get submitted in the next weeks.

We’d appreciate it if the STAC community takes some time to implement the new version and give feedback via the GitHub issue tracker so that we can ensure the new version is mature and well-received by the community. We hope that the STAC ecosystem catches up with the changes in the specification in the next weeks and months, any help that you can provide is highly appreciated. If you want to fund the STAC work we do, please get in touch, too.

A shoutout to all the participants and sponsors of the last STAC sprint in Philadelphia, who laid a solid basis for this release. Emmanuel Mathot and I were then funded by the STAC PSC to finalize the work. Thank you to everyone who made this possible.

Please read the Changelog for all changes that have been made to the specification since v1.0.0. In the following sections, we’ll highlight the most important changes in the specification with some JSON snippets.

Bands

As of STAC 1.1, the bands array merges the similar but separate fields eo:bands and raster:bands, which was probably one of the most annoying things in STAC for historical reasons. The new bands field can be used in combination with property inheritance to provide users with more flexibility.

It should be relatively simple to migrate from STAC 1.0 (i.e. from eo:bands and/or raster:bands) to the new bands array. Usually, you can merge each object on a by-index basis. For some fields, you need to add the extension prefix of the eo or raster extension to the property name. Nevertheless, you should consider deduplicating properties with the same values across all bands to the Asset. Please also consider the Bands best practices when migrating from eo:bands and raster:bands. It also provides more specific examples.

STAC 1.0 example:

{
  "assets": {
    "example": {
      "href": "example.tif",
      "eo:bands": [
        {
          "name": "r",
          "common_name": "red"
        },
        {
          "name": "g",
          "common_name": "green"
        },
        {
          "name": "b",
          "common_name": "blue"
        },
        {
          "name": "nir",
          "common_name": "nir"
        }
      ],
      "raster:bands": [
        {
          "data_type": "uint16",
          "spatial_resolution": 10,
          "sampling": "area"
        },
        {
          "data_type": "uint16",
          "spatial_resolution": 10,
          "sampling": "area"
        },
        {
          "data_type": "uint16",
          "spatial_resolution": 10,
          "sampling": "area"
        },
        {
          "data_type": "uint16",
          "spatial_resolution": 30,
          "sampling": "area"
        }
      ]
    }
  }
}

After migrating to STAC 1.1 this is ideally provided as follows:

{
  "assets": {
    "example": {
      "href": "example.tif",
      "data_type": "uint16",
      "raster:sampling": "area",
      "raster:spatial_resolution": 10,
      "bands": [
        {
          "name": "r",
          "eo:common_name": "red",
        },
        {
          "name": "g",
          "eo:common_name": "green"
        },
        {
          "name": "b",
          "eo:common_name": "blue"
        },
        {
          "name": "nir",
          "eo:common_name": "nir",
          "raster:spatial_resolution": 30
        }
      ]
    }
  }
}

Apart from a much shorter and more readable list of bands, you’ll notice the following:

• The arrays have been merged into a single property bands.
• The properties common_name and spatial_resolution were renamed to include the extension prefixes.
• The properties data_type and raster:sampling (renamed from sampling) were deduplicated to the Asset as the values were the same across all bands.
• The spatial_resolution was also deduplicated, i.e. 10 is provided on the asset level, which is inherited by the bands unless explicitly overridden. Therefore, the nir band overrides the value 10 with a value of 30.

As a result, the new bands array is more lightweight and easier to handle.

To make all this possible there were corresponding changes and releases for the following two extensions:

• The Electro Optical (EO) extension was updated to v2.0.0-beta.1
• The Raster extension was also updated to v2.0.0-beta.1

License

To better align with OGC API - Records, we slightly changed the license field. The license field additionally supports SPDX expressions and the value other. At the same time, the values proprietary and various were deprecated in favor of SPDX expressions and other. The new value other also solves an issue many data providers reported with the term proprietary, which was misleading for open licenses that were just not listed in the SPDX database.

Common Metadata

The list of fields in the STAC common metadata model was extended, which partially was a result of the changes to the bands mentioned above.

The following fields were added:

• bands (see above)
• keywords (as formerly defined in Collections)
• roles (as formerly defined in Assets)
• data_type, nodata, statistics and unit (as formerly defined in the Raster extension)

Please also note that the specification was restructured a bit so that common elements such as Assets and Links are not defined in each specification (Catalog, Collection, Item) anymore, but instead, they are separately defined once in the commons folder.

Links

The Link Object used for the links field, has been extended to support more HTTP mechanisms. The additions were already specified in STAC API 1.0.0 but were forgotten to be added to STAC 1.0.0, so we are catching up now.

The following additional fields are available for links:

• method: The HTTP method (e.g. POST) to use for the links (defaults to GET)
• headers: The HTTP headers to send alongside the link request
• body: The request body to send for the link request (usually only applies to POST, PUT and PATCH methods)

In addition to the extended Link Object, various smaller changes were made to link-related subjects:

• Links with the relation type self are now validated and as such are required to be absolute.
• The best practice recommends that link titles should exactly reflect the title of the corresponding entity
• It was clarified how URL resolving mechanics (for links and assets) work, i.e. that trailing slashes in URLs are significant

For links with relation type parent and root a clarification was issued: Conceptually, STAC entities shall have no more than one parent entity. As such, STAC entities also can have no more than one root entity. So there’s usually just one link with root or parent relationship unless different variations of the same conceptual entity exist (identified by the ID). Different variations could be:

• a different encoding (see the type property), e.g. a HTML version in addition to JSON
• a different language (see the hreflang property). e.g. a German version in addition to English

Similarly, it was clarified that multiple collections can point to an Item, but an Item can only point back to a single collection.

Item Asset Defintions

The item_assets field that was previously an extension is now part of the STAC specification. It was probably the most commonly used extension and many extensions were defining schemas for it, so it is simpler to have it in the core specification.

No changes are required in the migration, although you can remove the schema URI of the extension (i.e. https://stac-extensions.github.io/item-assets/v1.0.0/schema.json) from the stac_extensions property. It doesn’t hurt to keep the schema URI though and although the extension was deprecated, the extension can still be used in STAC 1.0.0. It just won’t get any updates in the future, because any changes will be directly integrated into STAC itself.

Best Practices

The following best practices were introduced or have changed:

• Link titles should exactly reflect the title of the corresponding entity
• Explained URL resolving mechanics, e.g. that trailing slashes in URLs are significant
• Collection IDs should be unique across all collections in the corresponding root catalog and Item IDs should be unique per collection
• Subdirectories are not recommended for Items without sidecar files any longer
• Clarified the use of the roles thumbnail, overview and visual

Please consult the best practices document for details.

Other Extension

In addition to the changes in the core specification, we also updated some extensions. I already mentioned the deprecation of the Item Assets extension and the band-related changes in the EO and Raster extensions above.

An additional change in the raster extension is that the common band names have been extended, especially rededge was split into multiple common names (rededge071, rededge075 and rededge078) and green05 was added. This allows a direct mapping between the STAC common names and the Awesome Spectral Indices project.

We also released a significant change to the Projection extension.

The change allows to provide CRS codes for authorities other than EPSG, e.g. OGC or IAU. Previously only EPSG was supported via the proj:epsg field, e.g. "proj:epsg": 3857 for Web Mercator. The new version replaces the field with proj:code so that the authority is included in the code, e.g. "proj:code": "EPSG:3857".

Version 2.0.0 of the Projection extension removes and forbids the use of proj:epsg. If you want to migrate more gracefully, you can also migrate to the intermediate version 1.2.0 which deprecates proj:epsg and adds proj:code at the same time.

Other notable changes

• If a description is given, it can’t be empty
• Clarify in descriptions that start_datetime and end_datetime are inclusive bounds
• Two spatial bounding boxes in a Collection don’t make sense and will be reported as invalid
• Clarified which media types should be used for the hierarchical relation types
• Clarified in the Markdown specification that GeometryCollections are not allowed as Item Geometry
• Clarified that JSON Schema draft-07 is the default version for Collection summaries and other versions may not be supported

Our blog is open source. You can suggest edits on GitHub.