Skip to content

Latest commit

 

History

History
121 lines (97 loc) · 12.5 KB

extensions.md

File metadata and controls

121 lines (97 loc) · 12.5 KB
Raw

API Extensions

STAC aims to define a small core of functionality, with richer capabilities enabled by extensions. This document lists the existing extensions, and explains the process of creating and maturing an extension.

Anyone is welcome to create an extension (see info on this below), and is encouraged to at least link to the extension from here. The third-party / vendor extension section is for the sharing of extensions. As third parties create useful extensions for their implementation it is expected that others will make use of it, and then evolve to make it a 'community extension', that several providers maintain together. For now anyone from the community is welcome to use the appropriate parts of the stac-api-spec repository to collaborate.

Extension Maturity

Extensions are meant to evolve to maturity, and thus may be in different states in terms of stability and number of implementations. All extensions 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. 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.

Extensions, Fragments and Conformance

Each extension has its own conformance class, which is specified with a 'conformance URI' that is defined for the extension, and listed in the table below. These must be listed in the conformsTo JSON of the landing page, as specified by STAC API Core, to let clients know that they can utilize the functionality.

Each extension is defined to work against only one of the main API spec's conformance classes. A number of extensions define functionality that could be used easily in a number of endpoints, such as additional parameters for search. For this repository we put those in the fragments directory. The main definition of the functionality lives there, but a fragment does not define a conformance class. Only extensions have conformance classes, as they define the functionality along with the scope - where it is used.

NOTE: Currently the fragments are only used in item-search, but in the next release we will define extensions for all the fragments that are scoped against ogcapi-features.

List of community extensions

This is the list of all extensions that are contained in the stac-api-spec repository.

Extension Name Scope* Description Maturity
Fields Item Search request Adds parameter to control which fields are returned in the response. Pilot
Filter Item Search and STAC - Features API /items requests Adds parameter to search Item and Collection properties. Pilot
Context Item Search response (ItemCollection) Adds search related metadata (context) to ItemCollection. Proposal
Sort Item Search request Adds Parameter to control sorting of returns results. Pilot
Transaction STAC - Features API POST on /items endpoint, DELETE/PUT on /items/{itemId} endpoint Adds PUT and DELETE endpoints for the creation, editing, and deleting of Item objects. Pilot
Items and Collections API Version STAC - Features API on /items endpoint Adds GET versions resource to Collection and Item endpoints and provides semantics for a versioning scheme for Collection and Item objects. Proposal
Query Item Search request Adds parameter to search Item and Collection properties. Pilot, scheduled to be Deprecated

Conformance classes of extensions

Each extension has its own conformance URI, which is used in the conformsTo response of the landing page to let clients know what capabilities the service supports. This are listed at the top of each extension description, but the full table is given here for ease of reference.

Third-party / vendor extensions

The following extensions are provided by third parties (vendors). They tackle very specific use-cases and may be less stable than the official extensions. Once stable and adopted by multiple parties, extensions may be made official and incorporated in the STAC repository.

Please contact a STAC maintainer or open a Pull Request to add your extension to this table.

Name Scope Description Vendor
Free-text Search Item Search request Adds q parameter and free-text search against item properties CEDA, STFC, UKRI
Context Collections Item Search request Adds a collections keyword to the context extension response. CEDA, STFC, UKRI

Creating new extensions

Creating new extensions requires creating an OpenAPI fragment to define it, along with a README markdown file that gives an overview of the functionality. In the README, a conformance URI should be provided, so clients can use it to tell if a service has the indicated functionality. It is also recommended to note the 'extension maturity', as defined above, so others can know how widely it is used.

The new extension can live anywhere online, with a recommendation of using a GitHub repository to be able to track changes. The first step in sharing the extension is to add it to the third-party / vendor extension table above. If it is of something that the wider community may be interested in then it should be added to the appropriate folder in the main repo as a pull request.