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 extensions to https://stac-api-extensions.github.io #376

Merged
merged 2 commits into from
Jan 29, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ the release branches above for a stable version of the specification.
**NOTE**: This means that if you are on github.com/radiantearth/stac-api-spec then you are looking at an unreleased,
unstable version of the specification. Use the first listed link on releases to read the current released, stable version
of the spec.

## About

The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried.
Expand Down Expand Up @@ -117,7 +118,8 @@ cross-collection search of STAC Item objects at a `search` endpoint, as well as
**Extensions:**
The *[extensions](extensions.md) 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/](fragments/) folder.
documents live as fragments in the [fragments/](fragments/) folder. The official list of STAC API Extensions
is maintained [here](https://stac-api-extensions.github.io).

**Fragments:**
The *[fragments/](fragments/)* folder contains re-usable building blocks to be used in a STAC API, including common OpenAPI
Expand Down
58 changes: 15 additions & 43 deletions extensions.md
Original file line number Diff line number Diff line change
@@ -1,62 +1,34 @@
# API Extensions
# STAC API Extensions

STAC API aims to define a 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.
STAC API aims to define a core of functionality, with richer capabilities enabled by extensions. The list of
STAC API Extensions is maintained at **<https://stac-api-extensions.github.io>**.

Anyone is welcome to create an extension (see [info on this](#creating-new-extensions) below), and is encouraged to at least
link to the extension from here.
The third-party / community 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.
This document explains the process of creating and maturing an extension.

Anyone is welcome to create an extension (see [info on this](#creating-new-extensions) below), and is encouraged
to add the extension to the [official list](https://stac-api-extensions.github.io) by creating an issue or PR
on <https://github.com/stac-api-extensions/stac-api-extensions.github.io>.

All extensions must include a [maturity classification](README.md#maturity-classification), so that STAC API
specification users can easily get a sense of how much they can count on the extension.
specification users can easily get a sense of how much they can count on the extension.

## Extensions and Conformance

Each extension has its own conformance class, which is specified with one or more **conformance URIs**
that are defined for the extension. These must be listed in the `conformsTo` JSON of the Landing Page,
as specified by [STAC API - Core](core/), to let clients know that they can use the functionality.
as specified by [STAC API - Core](core/), to let clients know that they can use the functionality.

A number of extensions define functionality that could be used easily in a number of endpoints, such
as additional parameters for search through either **STAC API - Item Search** or **STAC API - Features**.

## Official Extensions

This is the list of all official extensions that are contained in the
[stac-api-extensions](https://github.com/stac-api-extensions) GitHub organization.

| Extension Name | Scope | Description | Maturity |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------- |
| [Fields](https://github.com/stac-api-extensions/fields/blob/main/README.md) | [STAC API - Item Search](item-search/) and [STAC API - Features](ogcapi-features) | Adds parameter to control which fields are returned in the response. | Candidate |
| [Filter](https://github.com/stac-api-extensions/filter/blob/main/README.md) | [STAC API - Item Search](item-search/) and [STAC API - Features](ogcapi-features) | Adds parameter to search Item properties. | Pilot |
| [Context](https://github.com/stac-api-extensions/context/blob/main/README.md) | [STAC API - Item Search](item-search/) and [STAC API - Features](ogcapi-features) | Adds search related metadata (context) to ItemCollection. | Candidate |
| [Sort](https://github.com/stac-api-extensions/sort/blob/main/README.md) | [STAC API - Item Search](item-search/) and [STAC API - Features](ogcapi-features) | Adds parameter to control sorting of results. | Candidate |
| [Transaction](https://github.com/stac-api-extensions/transaction/blob/main/README.md) | [STAC API - Features](ogcapi-features) | Adds POST, PUT, and DELETE endpoints for the creation, editing, and deleting of Item objects. | Candidate |
| [Query](https://github.com/stac-api-extensions/query/blob/main/README.md) | [STAC API - Item Search](item-search/) and [STAC API - Features](ogcapi-features) | Adds parameter to search Item properties. | Candidate |
| [Children](https://github.com/stac-api-extensions/children/blob/main/README.md) | [STAC API - Core](core/) | Defines advertisement of the children (child catalogs or child collections) that a catalog contains. | Proposal |

## Community Extensions

The following extensions are community extensions. 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 | Maintainer(s) |
| -------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [Free-text Search](https://github.com/cedadev/stac-freetext-search) | [STAC API - Item Search](item-search/) request | Adds `q` parameter and free-text search against item properties | [CEDA, STFC, UKRI](https://github.com/cedadev) |
| [Context Collections](https://github.com/cedadev/stac-context-collections) | [STAC API - Item Search](item-search/) request | Adds a `collections` keyword to the [context](https://github.com/radiantearth/stac-api-spec/tree/main/fragments/context) extension response. | [CEDA, STFC, UKRI](https://github.com/cedadev) |

## Creating new extensions

Creating new extensions requires creating an OpenAPI fragment to define it, along with a README markdown file that gives
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 community 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.
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 official list, as described above. If it is of something
that the wider community may be interested in, then it may be added to the
[stac-api-extensions](https://github.com/stac-api-extensions) GitHub organization.