The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried. A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and time. The core STAC specifications live in the GitHub repository radiantearth/stac-spec.
A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC Catalog,
Collection, Item,
or a STAC API ItemCollection, depending on the endpoint.
Catalog and Collection objects are JSON, while Item and ItemCollection objects are GeoJSON-compliant entities with foreign members.
Typically, a Feature is used when returning a single Item object, and FeatureCollection when multiple Item objects (rather than a
JSON array of Item entities).
The API can be implemented in compliance with the OGC API - Features standard (OAFeat is a shorthand). In this case STAC API can be thought of as a specialized Features API
to search STAC catalogs, where the features returned are STAC Item objects, that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.
The specification for STAC API is provided as files that follow the OpenAPI 3.0 specification, rendered online into HTML at https://api.stacspec.org/v1.0.0-beta.5, in addition to human-readable documentation.
This specification has evolved over the past couple years, and is used in production in a variety of deployments. It is currently in a 'beta' state, with no major changes anticipated. For 1.0.0-beta.5, we remain fully aligned with OGC API - Features Version 1.0, and we are working to stay aligned as the additional OGC API components mature. This may result in minor changes as things evolve. The STAC API specification follows Semantic Versioning, so once 1.0.0 is reached any breaking change will require the spec to go to 2.0.0.
Conformance classes and extensions are meant to evolve to maturity, and thus may be in different states in terms of stability and number of implementations. All extensions must include a maturity classification, so that STAC API 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. Can generally count on an extension at this maturity level | Mostly stable, breaking changes require a new version and minor changes are unlikely. |
| 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. | Will not be updated and may be removed in an upcoming major release. |
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.
For any questions feel free to jump on our gitter channel or email our google group. The majority of communication about the evolution of the specification takes place in the issue tracker and in pull requests.
The Overview document describes all the various parts of the STAC API and how they fit together.
STAC API - Core Specification: The core folder describes the core STAC API specification that enables browsing catalogs and retrieving the API capabilities. This includes the OpenAPI schemas for STAC Item, Catalog and Collection objects.
STAC API - Collections: The collections folder describes how a STAC API Catalog can advertise the Collections it contains.
STAC API - Features:
The ogcapi-features folder describes how a STAC API can fully implement OGC API -
Features to expose individual items endpoints for search of
each STAC collection. It also includes extensions that can be used to further enhance OAFeat.
STAC API - Item Search Specification:
The item-search folder contains the Item Search specification, which enables
cross-collection search of STAC Item objects at a search endpoint, as well as a number of extensions.
STAC API - Children: The children folder describes how a STAC API Catalog can advertise the children (child catalogs or child collections) it contains.
STAC API - Browseable:
The browseable folder describes how a STAC API Catalog can advertise that all Items can be accessed
by following through child and item link relations.
Extensions: The extensions document describes how STAC incubates new functionality, and it links to the existing extensions that can be added to enrich the functionality of a STAC API. Each has an OpenAPI yaml, but some of the yaml documents live as fragments in the fragments/ folder.
Fragments: The fragments/ folder contains re-usable building blocks to be used in a STAC API, including common OpenAPI schemas and parameters for behavior like sorting and filtering. Most all of them are compatible with OGC API - Features, and the plan is to fully align the relevant functionality and have it be useful for all OAFeat implementations. OpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README.
STAC Specification: This repository includes a 'sub-module', which
is a copy of the STAC specification tagged at the latest stable version.
Sub-modules aren't checked out by default, so to get the directory populated
either use git submodule update --init --recursive if you've already cloned it,
or clone from the start with git clone --recursive git@github.com:radiantearth/stac-api-spec.git.
Implementation Recommendations: Recommendations for implementing a STAC API may be found here. These are mostly concerns that apply to an entire API implementation and are not part of the specification itself.
Anyone building software that catalogs imagery or other geospatial assets is welcome to collaborate. Beforehand, please review our guidelines for contributions and development process.