diff --git a/PRINCIPLES.md b/PRINCIPLES.md index 09504ed4..4e53b807 100644 --- a/PRINCIPLES.md +++ b/PRINCIPLES.md @@ -46,8 +46,8 @@ for data in a different projection. - **Working code required.** Proposed changes should be accompanied by working code (ideally with a link to an online service running the code). A reference implementation should be available -online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations -that cover the entire specification. Extensions have their own [Extention Maturity](extensions.md#extension-maturity) model. +online to power the interactive documentation. Both core conformance classes and extensions follow the +[Maturity Classification](README.md#maturity-classification) model. - **Design for scale.** The design should work great with more data than can be imagined right now. Ideally implementations are built with large test data sets to validate that they will work. diff --git a/README.md b/README.md index d9714029..5c8d39af 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ - [STAC API](#stac-api) - [About](#about) - [Stability Note](#stability-note) + - [Maturity Classification](#maturity-classification) - [Communication](#communication) - [In this repository](#in-this-repository) - [Contributing](#contributing) @@ -16,7 +17,6 @@ The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standard 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](https://github.com/radiantearth/stac-spec). - A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), [Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md), or a STAC API [ItemCollection](fragments/itemcollection/README.md), depending on the endpoint. @@ -36,11 +36,34 @@ rendered online into HTML at , in additi ## Stability Note 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-beta we remain fully aligned with [OGC API - +currently in a 'beta' state, with no major changes anticipated. For 1.0.0-beta.5, we remain fully aligned with [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) 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](https://semver.org/), so once 1.0.0 is reached any breaking change -will require the spec to go to 2.0.0. +will require the spec to go to 2.0.0. + +## Maturity Classification + +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. ## Communication diff --git a/collections/README.md b/collections/README.md index 2bfd997b..8849a96d 100644 --- a/collections/README.md +++ b/collections/README.md @@ -7,8 +7,10 @@ - [Example](#example) - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/collections)) -- **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Conformance URIs:** + - + - +- **[Maturity Classification](../README.md#maturity-classification):** Pilot - **Dependencies**: [STAC API - Core](../core) A STAC API can return information about all STAC [Collections](../stac-spec/collection-spec/collection-spec.md) available using a link @@ -24,37 +26,20 @@ aim to align with it. But it still seems to be in flux.* ## Link Relations -The following Link relations shall exist in the Landing Page (root). - -| **rel** | **href** | **From** | **Description** | -| -------------- | -------------- | --------- | ---------------------------------------------------- | -| `root` | `/` | STAC Core | The root URI | -| `self` | `/` | OAFeat | Self reference, same as root URI | -| `service-desc` | `/api` | OAFeat | The service description in a machine-readable format | -| `data` | `/collections` | OAFeat | List of Collections | - -The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be -OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), -`application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), or `application/vnd.oai.openapi+json;version=3.1` -(3.1 JSON). +This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. -A `service-doc` endpoint is recommended, but not required. This commonly returns an HTML -page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) interactive API -documentation, but any format is allowed. The Link `type` field should correspond to whatever format or formats are -supported by this endpoint, e.g., `text/html`. +The following Link relations shall exist in the Landing Page (root). -| **rel** | **href** | **From** | **Description** | -| ------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `service-doc` | `/api.html` | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. | +| **rel** | **href** | **From** | **Description** | +| ------- | -------------- | -------- | ------------------- | +| `data` | `/collections` | OAFeat | List of Collections | -Additionally, `child` relations may exist to individual catalogs and collections. +Additionally, `child` relations may exist to child Catalogs and Collections. | **rel** | **href** | **From** | **Description** | | ------- | -------- | --------- | -------------------------------------------------------------------------------------------------------- | | `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects | -`child` relations are useful for supporting browsing a STAC API as if it were a static catalog. - The following Link relations shall exist in the `/collections` endpoint response. | **rel** | **href** | **From** | **Description** | @@ -82,12 +67,12 @@ elsewhere. If this is done, it is recommended to include a `rel` of `canonical` ## Endpoints -| Endpoint | Returns | Description | -| ----------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- | -| `/` | Catalog | Landing Page and root Catalog | -| `/api` | any | The service description. The path for this endpoint is only recommended to be `/api`, but may be another path. | -| `/collections` | JSON | Object with a list of Collections contained in the catalog and links | -| `/collections/{collectionId}` | Collection | Returns single Collection JSON | +This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented. + +| Endpoint | Returns | Description | +| ----------------------------- | ---------- | -------------------------------------------------------------------- | +| `/collections` | JSON | Object with a list of Collections contained in the catalog and links | +| `/collections/{collectionId}` | Collection | Returns single Collection JSON | STAC API's implementing the Collections class must support HTTP GET operation at `/collections`, with the return JSON document consisting of an array of all STAC Collections and an array of Links. diff --git a/core/README.md b/core/README.md index b0c3ea1c..79aaf35f 100644 --- a/core/README.md +++ b/core/README.md @@ -7,10 +7,11 @@ - [Extensions](#extensions) - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/core)), - and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. -- **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Conformance URIs:** + - +- **[Maturity Classification](../README.md#maturity-classification):** Pilot - **Dependencies**: None + and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. The base of a STAC API is its landing page. This resource is the starting point to discover what behaviors the API supports via the `conformsTo` values and link relations. @@ -80,10 +81,12 @@ Additionally, `child` relations may exist to individual catalogs and collections It is also valid to have `item` links from the landing page, but most STAC API services are used to serve up a large number of features, so they typically use several layers of intermediate `child` links before getting to Item objects. Note that the `items` (plural) -link will be used by APIs implementing STAC API - Features to link from a Collection to the items in that collection. +link relation is used by APIs implementing `STAC API - Features` to link from a Collection to the items in that collection. ## Endpoints +This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented. + These endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml). | Endpoint | Returns | Description | diff --git a/extensions.md b/extensions.md index 2cda899d..a3d4846c 100644 --- a/extensions.md +++ b/extensions.md @@ -1,6 +1,6 @@ # API Extensions -STAC aims to define a small core of functionality, with richer capabilities enabled by extensions. This document +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. Anyone is welcome to create an extension (see [info on this](#creating-new-extensions) below), and is encouraged to at least @@ -9,30 +9,10 @@ The third-party / vendor extension section is for the sharing of extensions. As 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 +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. -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 +## 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](core/), to let clients @@ -52,24 +32,24 @@ This is the list of all extensions that are contained in the stac-api-spec repos | Extension Name | Scope* | Description | Maturity | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -| [Fields](item-search/README.md#fields) | [Item Search](item-search/) request | Adds parameter to control which fields are returned in the response. | *Pilot* | -| [Filter](item-search/README.md#filter) | [Item Search](item-search/) and [STAC API - Features](ogcapi-features) `/items` requests | Adds parameter to search Item and Collection properties. | *Pilot* | -| [Context](item-search/README.md#context) | [Item Search](item-search/) response ([ItemCollection](fragments/itemcollection/README.md)) | Adds search related metadata (context) to ItemCollection. | *Proposal* | -| [Sort](item-search/README.md#sort) | [Item Search](item-search/) request | Adds Parameter to control sorting of returns results. | *Pilot* | +| [Fields](item-search/README.md#fields-extension) | [Item Search](item-search/) request | Adds parameter to control which fields are returned in the response. | *Pilot* | +| [Filter](item-search/README.md#filter-extension) | [Item Search](item-search/) and [STAC API - Features](ogcapi-features) `/items` requests | Adds parameter to search Item and Collection properties. | *Pilot* | +| [Context](item-search/README.md#context-extension) | [Item Search](item-search/) response ([ItemCollection](fragments/itemcollection/README.md)) | Adds search related metadata (context) to ItemCollection. | *Proposal* | +| [Sort](item-search/README.md#sort-extension) | [Item Search](item-search/) request | Adds Parameter to control sorting of returns results. | *Pilot* | | [Transaction](ogcapi-features/extensions/transaction/README.md) | [STAC API - Features](ogcapi-features) 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](ogcapi-features/extensions/version/README.md) | [STAC API - Features](ogcapi-features) 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/README.md#query) | [Item Search](item-search/) request | Adds parameter to search Item and Collection properties. | *Pilot*, scheduled to be *Deprecated* | +| [Query](item-search/README.md#query-extension) | [Item Search](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. -- [Fields](item-search/README.md#fields) - - - - -- [Filter](item-search/README.md#filter) - - +- [Fields](item-search/README.md#fields-extension) + - + - +- [Filter](item-search/README.md#filter-extension) + - - - - @@ -82,17 +62,17 @@ the service supports. This are listed at the top of each extension description, - - - -- [Context](item-search/README.md#context) +- [Context](item-search/README.md#context-extension) - - -- [Sort](item-search/README.md#sort) +- [Sort](item-search/README.md#sort-extension) - - - [Transaction](ogcapi-features/extensions/transaction/README.md) - - [Items and Collections API Version](ogcapi-features/extensions/version/README.md) - -- [Query](item-search/README.md#query) +- [Query](item-search/README.md#query-extension) - ## Third-party / vendor extensions diff --git a/fragments/context/README.md b/fragments/context/README.md index 801339c7..71709b62 100644 --- a/fragments/context/README.md +++ b/fragments/context/README.md @@ -4,7 +4,7 @@ - **Conformance Classes:** - Item Search binding: - STAC Features binding: -- **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot +- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Pilot - **Dependents:** - [Item Search](../../item-search) diff --git a/fragments/fields/README.md b/fragments/fields/README.md index c257affb..dec09926 100644 --- a/fragments/fields/README.md +++ b/fragments/fields/README.md @@ -4,7 +4,7 @@ - **Conformance Classes:** - Item Search binding: - STAC Features binding: -- **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot +- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Pilot - **Dependents:** - [Item Search](../../item-search) - [STAC Features](../../ogcapi-features) diff --git a/fragments/filter/README.md b/fragments/filter/README.md index a9b363a4..6dfcc6bc 100644 --- a/fragments/filter/README.md +++ b/fragments/filter/README.md @@ -15,7 +15,7 @@ - Arithmetic Expressions: - Array Operators: - Property-Property Comparisons: -- **Extension [Maturity Classification](../../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../../README.md#maturity-classification):** Pilot - **Dependents:** - [Item Search](../../item-search) diff --git a/fragments/itemcollection/README.md b/fragments/itemcollection/README.md index db69a74c..f72e7cd2 100644 --- a/fragments/itemcollection/README.md +++ b/fragments/itemcollection/README.md @@ -27,7 +27,7 @@ This object describes a STAC ItemCollection. The fields `type` and `features` ar ## Extensions -- The [Context Extension](../../item-search/README.md#context) adds additional fields to STAC ItemCollection relevant +- The [Context Extension](../../item-search/README.md#context-extension) adds additional fields to STAC ItemCollection relevant to their use as search results. - The [Single File STAC Extension](https://github.com/stac-extensions/single-file-stac/blob/main/README.md) provides a set of Collection and Item objects as a single file catalog. diff --git a/fragments/query/README.md b/fragments/query/README.md index 7739fb39..d95cb9e8 100644 --- a/fragments/query/README.md +++ b/fragments/query/README.md @@ -2,7 +2,7 @@ - **OpenAPI specification:** [openapi.yaml](openapi.yaml) - **Conformance Class:** -- **Extension [Maturity Classification](../../extensions.md#extension-maturity):** Pilot, scheduled to be Deprecated in favor of the [Filter Extension](../filter/README.md) using [CQL](http://docs.opengeospatial.org/DRAFTS/19-079.html). +- **Extension [Maturity Classification](../../README.md#maturity-classification):** Pilot, scheduled to be Deprecated in favor of the [Filter Extension](../filter/README.md) using [CQL](http://docs.opengeospatial.org/DRAFTS/19-079.html). - **Dependents:** - [Item Search](../../item-search) diff --git a/fragments/sort/README.md b/fragments/sort/README.md index 4037a1ed..b6a3579f 100644 --- a/fragments/sort/README.md +++ b/fragments/sort/README.md @@ -4,7 +4,7 @@ - **Conformance Class:** - Item Search binding: - STAC Features binding: -- **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot +- **Fragment [Maturity Classification](../../README.md#maturity-classification):** Pilot - **Dependents:** - [Item Search](../../item-search) - [STAC Features](../../ogcapi-features) diff --git a/item-search/README.md b/item-search/README.md index d899cc9d..1c43abaa 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -14,14 +14,17 @@ - [PUT / PATCH / DELETE](#put--patch--delete) - [Example Landing Page for STAC API - Item Search](#example-landing-page-for-stac-api---item-search) - [Extensions](#extensions) - - [Fields](#fields) - - [Filter](#filter) - - [Sort](#sort) - - [Context](#context) - - [Query](#query) + - [Fields Extension](#fields-extension) + - [Sort Extension](#sort-extension) + - [Context Extension](#context-extension) + - [Filter Extension](#filter-extension) + - [Query Extension](#query-extension) - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/item-search)) -- **Conformance URI:** +- **Conformance URIs:** + - + - +- **[Maturity Classification](../README.md#maturity-classification):** Pilot - **Dependencies**: [STAC API - Core](../core) - **Examples**: [examples.md](examples.md) @@ -44,53 +47,24 @@ Implementing `GET /search` is **required**, `POST /search` is optional, but reco ## Link Relations -The following Link relations shall exist in the Landing Page (root). - -| **rel** | **href** | **From** | **Description** | -| -------------- | --------- | ---------------- | ---------------------------------------------------- | -| `root` | `/` | STAC Core | The root URI | -| `self` | `/` | OAFeat | Self reference, same as root URI | -| `service-desc` | `/api` | OAFeat | The service description in a machine-readable format | -| `search` | `/search` | STAC Item Search | URI for the Search endpoint | - -The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be -OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), -`application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), or `application/vnd.oai.openapi+json;version=3.1` -(3.1 JSON). - -A `service-doc` endpoint is recommended, but not required. This commonly returns an HTML -page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) interactive API -, but any format is allowed. The Link `type` field should correspond to whatever format or formats are -supported by this endpoint, e.g., `text/html`. - -| **rel** | **href** | **From** | **Description** | -| ------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `service-doc` | `/api.html` | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. | +This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. -It is **required** to add a Link to the root endpoint (`/`) with the `rel` type set to `search` -that refers to the search endpoint in the `href` property, -with a `type` of `application/geo+json` and a `method` of `GET`. -This link will look like: +The following Link relations shall exist in the Landing Page (root). -```json -{ - "href": "https://example.com/search", - "rel": "search", - "title": "Search", - "type": "application/geo+json", - "method": "GET" -} -``` +| **rel** | **href** | **From** | **Description** | +| -------- | --------- | ---------------------- | --------------------------- | +| `search` | `/search` | STAC API - Item Search | URI for the Search endpoint | -Implementations that support `POST` should add a second link with the same structure but with a `method` of `POST`. +The `search` link relation shall have a `type` of `application/geo+json` and a `method` of `GET`, and may also +a link with a `method` of `POST` if the server supports it. ## Endpoints -| Endpoint | Returns | Description | -| --------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `/` | Catalog | Landing Page and root Catalog | -| `/api` | any | The OpenAPI service description. The path for this endpoint is only recommended to be `/api`, but may be another path. | -| `/search` | Item Collection | Search endpoint | +This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented. + +| Endpoint | Returns | Description | +| --------- | --------------- | --------------- | +| `/search` | Item Collection | Search endpoint | ## Query Parameters and Fields @@ -299,7 +273,14 @@ the [overview](../overview.md#example-landing-page) document. { "rel": "search", "type": "application/geo+json", - "href": "https://stacserver.org/search" + "href": "https://stacserver.org/search", + "method": "GET" + }, + { + "rel": "search", + "type": "application/geo+json", + "href": "https://stacserver.org/search", + "method": "POST" } ] } @@ -312,10 +293,10 @@ These extensions provide additional functionality that enhances Item Search. All the `search` endpoint must include the relevant **conformance URI** in the `conformsTo` response at the root (`/`) landing page, to indicate to clients that they will respond properly to requests from clients. -### Fields +### Fields Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot - **Definition**: [STAC API - Fields Fragment](../fragments/fields/) By default, the STAC search endpoint `/search` returns all attributes of each Item, as there is no way to specify @@ -324,22 +305,10 @@ allows the client to suggest to the server which Item attributes should be inclu through the use of a `fields` parameter. The full description of how this extension works can be found in the [fields fragment](../fragments/fields/). -### Filter - -- **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot -- **Definition**: [STAC API - Filter Fragment](../fragments/filter/) - -The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results -by properties. The Filter extension adds a new parameter, `filter`, that can take a number of comparison operators to -match predicates between the fields requested and the values of Item objects. It can be used with both GET and POST and supports two -query formats, `cql-text` and `cql-json`. The full details on the JSON structure are specified in the [filter -fragment](../fragments/filter/). - -### Sort +### Sort Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot - **Definition**: [STAC API - Sort Fragment](../fragments/sort/) By default, the STAC search endpoint `/search` returns results in no specified order. Whatever order the results are in @@ -349,26 +318,38 @@ field names to sort by, with an indication of direction. It can be used with bot '-' to indicate sort order, and the latter including a 'direction' field in JSON. The full description of the semantics of this extension can be found in the [sort fragment](../fragments/sort). -### Context +### Context Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot - **Definition**: [STAC API - Context Fragment](../fragments/context/) This extension is intended to augment the core ItemCollection responses from the `search` API endpoint with a JSON object called `context` that includes the number of items `matched`, `returned` and the `limit` requested. The full description and examples of this are found in the [context fragment](../fragments/context). -### Query +### Filter Extension + +- **Conformance URI:** +- **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot +- **Definition**: [STAC API - Filter Fragment](../fragments/filter/) + +The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results +by properties. The Filter extension adds a new parameter, `filter`, that can take a number of comparison operators to +match predicates between the fields requested and the values of Item objects. It can be used with both GET and POST and supports two +query formats, `cql-text` and `cql-json`. The full details on the JSON structure are specified in the [filter +fragment](../fragments/filter/). + +### Query Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot, scheduled to be Deprecated +- **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot - **Definition**: [STAC API - Query Fragment](../fragments/query/) -**Note** - the Query Extension will be deprecated at some point in 1.x. Implementers -are encouraged to use the Filter Extension instead. +**Note**: It is recommended that implementers implement the [Filter Extension](#filter-extension) instead, as +it offers a more robust set of operators and uses the CQL2 standard. -The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results +The STAC API search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results by properties. The Query extension adds a new parameter, `query`, that can take a number of comparison operators to match predicates between the fields requested and the values of Item objects. It can be used with both GET and POST, though GET includes the exact same JSON. The full details on the JSON structure are specified in the [query diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 376553b6..113a99cf 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -9,29 +9,36 @@ - [Example Landing Page for STAC API - Features](#example-landing-page-for-stac-api---features) - [Example Collection for STAC API - Features](#example-collection-for-stac-api---features) - [Extensions](#extensions) - - [Transaction](#transaction) + - [Transaction Extension](#transaction-extension) - [Items and Collections API Version Extension](#items-and-collections-api-version-extension) - - [Fields](#fields) - - [Sort](#sort) - - [Context](#context) + - [Fields Extension](#fields-extension) + - [Sort Extension](#sort-extension) + - [Context Extension](#context-extension) + - [Filter Extension](#filter-extension) + - [Query Extension](#query-extension) *based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)* - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/ogcapi-features)) - uses all the OGC API - Features openapi fragments to describe returning STAC Item objects. - **Conformance URIs:** - - - - [Requirements Class Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_core)) - - - [Requirements Class OpenAPI 3.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30)) - - - [Requirements Class GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson)) + - + - + - - [Requirements Class Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_core) + - - [Requirements Class GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson) + - - [Requirements Class OpenAPI 3.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30) + (if used for `service-desc` endpoint) +- **[Maturity Classification](../README.md#maturity-classification):** Candidate - **Dependencies**: - [STAC API - Core](../core) + - [STAC API - Collections](../collections) - [OGC API - Features](https://www.ogc.org/standards/ogcapi-features) + uses all the OGC API - Features openapi fragments to describe returning STAC Item objects. -Adding OGC API - Features (OAFeat) to a STAC API means fully implementing all their requirements, and then returning STAC -[Item](../stac-spec/item-spec/README.md) objects from their `/items` endpoints. In OAFeat, GeoJSON is an optional +Adding OGC API - Features (OAFeat) to a STAC API means fully implementing all its requirements, and then returning STAC +[Item](../stac-spec/item-spec/README.md) objects from its `/items` endpoints. In OAFeat, GeoJSON is an optional conformance class, enabling flexibility. However, STAC requires the use of GeoJSON for OAFeat -endpoints. The full conformance class list is in the following table. +endpoints. Note that implementing OGC API - Features does not actually depend on [STAC API - Core](../core), but we include it as a dependency since this extension discusses using it in the context of STAC. One could implement an OAFeat service, returning STAC @@ -40,44 +47,29 @@ with OAFeat clients. But specialized STAC clients will likely display results be ## Link Relations -The following Link relations shall exist in the Landing Page (root). - -| **rel** | **href** | **From** | **Description** | -| -------------- | -------------- | --------- | ---------------------------------------------------- | -| `root` | `/` | STAC Core | The root URI | -| `self` | `/` | OAFeat | Self reference, same as root URI | -| `conformance` | `/conformance` | OAFeat | Conformance URI | -| `service-desc` | `/api` | OAFeat | The service description in a machine-readable format | -| `data` | `/collections` | OAFeat | List of Collections | +This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. -The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be -OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), -`application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), or `application/vnd.oai.openapi+json;version=3.1` -(3.1 JSON). - -A `service-doc` endpoint is recommended, but not required. This commonly returns an HTML -page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) interactive API -, but any format is allowed. The Link `type` field should correspond to whatever format or formats are -supported by this endpoint, e.g., `text/html`. +The following Link relations shall exist in the Landing Page (root). -| **rel** | **href** | **From** | **Description** | -| ------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `service-doc` | `/api.html` | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. | +| **rel** | **href** | **From** | **Description** | +| ------------- | -------------- | -------- | ------------------- | +| `conformance` | `/conformance` | OAFeat | Conformance URI | +| `data` | `/collections` | OAFeat | List of Collections | ## Endpoints -The core OGC API - Features endpoints are shown below, with details provided in an +This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented. + +The OGC API - Features endpoints are shown below, with details provided in an [OpenAPI specification document](openapi.yaml). -| Endpoint | Returns | Description | -| ----------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/` | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities | -| `/api` | any | Returns a machine-readable API description of the service from the `service-desc` link `rel`. The path for this endpoint is only recommended to be `/api`, but may be another path. | -| `/conformance` | JSON | Info about standards to which the API conforms | -| `/collections` | JSON | Object containing an array of Collection objects in the Catalog, and Link relations | -| `/collections/{collectionId}` | [Collection](../stac-spec/collection-spec/README.md) | Returns single Collection JSON | -| `/collections/{collectionId}/items` | [ItemCollection](../fragments/itemcollection/README.md) | GeoJSON FeatureCollection-conformant entity of Item objects in collection | -| `/collections/{collectionId}/items/{featureId}` | [Item](../stac-spec/item-spec/README.md) | Returns single Item (GeoJSON Feature) | +| Endpoint | Returns | Description | +| ----------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `/conformance` | JSON | Info about standards to which the API conforms | +| `/collections` | JSON | Object containing an array of Collection objects in the Catalog, and Link relations | +| `/collections/{collectionId}` | [Collection](../stac-spec/collection-spec/README.md) | Returns single Collection JSON | +| `/collections/{collectionId}/items` | [ItemCollection](../fragments/itemcollection/README.md) | GeoJSON FeatureCollection-conformant entity of Item objects in collection | +| `/collections/{collectionId}/items/{featureId}` | [Item](../stac-spec/item-spec/README.md) | Returns single Item (GeoJSON Feature) | The OGC API - Features is a standard API that represents collections of geospatial data. It defines a RESTful interface to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry @@ -251,6 +243,7 @@ the [overview](../overview.md#example-landing-page) document. "conformsTo" : [ "https://api.stacspec.org/v1.0.0-beta.5/core", "https://api.stacspec.org/v1.0.0-beta.5/ogcapi-features", + "https://api.stacspec.org/v1.0.0-beta.5/collections", "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core", "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30", "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson" @@ -330,18 +323,18 @@ as is typical with a static STAC Collection, there are no links here with rel va ## Extensions -These extensions provide additional functionality that enhances STAC API - Features. +These extensions provide additional functionality that enhances `STAC API - Features`. All are specified as [fragments](../fragments), as they are re-used by extensions to other STAC APIs. STAC APIs that offer the following capabilities must include the relevant **conformance URI** in the `conformsTo` response at the root (`/`) landing page, to indicate to clients that they will respond properly to requests from clients. -### Transaction +### Transaction Extension - **Conformance URIs:** - - -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate - **Definition**: [STAC API - Transaction Fragment](extensions/transaction/) The core STAC API only supports retrieving existing Items. @@ -352,17 +345,17 @@ POST, PUT, PATCH, and DELETE methods. The full description of how this extension ### Items and Collections API Version Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate - **Definition**: [STAC API - Version](extensions/version/) The core API only supports semantics for creating and accessing a single version of an Item or Collection. The Version Extension defines the API resources and semantics for creating and accessing versioned records. It is the STAC API equivalent of [OGC API - Features - Part 4: Create, Replace, Update and Delete](https://docs.ogc.org/DRAFTS/20-002.html). -### Fields +### Fields Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate - **Definition**: [STAC API - Fields Fragment](../fragments/fields/) By default, the Items resource `/collections/{collectionId}/items` returns all attributes @@ -372,10 +365,10 @@ allows the client to suggest to the server which Item attributes should be inclu through the use of a `fields` parameter. The full description of how this extension works can be found in the [fields fragment](../fragments/fields/). -### Sort +### Sort Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate - **Definition**: [STAC API - Sort Fragment](../fragments/sort/) By default, the Items resource `/collections/{collectionId}/items` returns results in no specified order. Whatever order the results are in @@ -385,12 +378,39 @@ field names to sort by, with an indication of direction. It uses '+' and '-' to indicate sort order of the list of fields. The full description of the semantics of this extension can be found in the [sort fragment](../fragments/sort). -### Context +### Context Extension - **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate - **Definition**: [STAC API - Context Fragment](../fragments/context/) This extension is intended to augment the core ItemCollection responses from the Items resource `/collections/{collectionId}/items` with a JSON object called `context` that includes the number of items `matched`, `returned` and the `limit` requested. The full description and examples of this are found in the [context fragment](../fragments/context). + +### Filter Extension + +- **Conformance URI:** +- **Extension [Maturity Classification](../README.md#maturity-classification):** Pilot +- **Definition**: [STAC API - Filter Fragment](../fragments/filter/) + +The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results +by properties. The Filter extension adds a new parameter, `filter`, that can take a number of comparison operators to +match predicates between the fields requested and the values of Item objects. It can be used with both GET and POST and supports two +query formats, `cql-text` and `cql-json`. The full details on the JSON structure are specified in the [filter +fragment](../fragments/filter/). + +### Query Extension + +- **Conformance URI:** +- **Extension [Maturity Classification](../README.md#maturity-classification):** Candidate +- **Definition**: [STAC API - Query Fragment](../fragments/query/) + +**Note**: It is recommended that implementers implement the [Filter Extension](#filter-extension) instead, as +it offers a more robust set of operators and uses the CQL2 standard. + +The STAC search endpoint, `/search`, by default only accepts a limited set of parameters to limit the results +by properties. The Query extension adds a new parameter, `query`, that can take a number of comparison operators to +match predicates between the fields requested and the values of Item objects. It can be used with both GET and POST, though +GET includes the exact same JSON. The full details on the JSON structure are specified in the [query +fragment](../fragments/query/). diff --git a/ogcapi-features/extensions/transaction/README.md b/ogcapi-features/extensions/transaction/README.md index a8f74cfc..6bf00758 100644 --- a/ogcapi-features/extensions/transaction/README.md +++ b/ogcapi-features/extensions/transaction/README.md @@ -6,7 +6,7 @@ - **Conformance URIs:** - - -- **Extension [Maturity Classification](../../../extensions.md#extension-maturity):** Pilot +- **Extension [Maturity Classification](../../../README.md#maturity-classification):** Pilot - **Dependencies**: [STAC API - Features](../../README.md) The core STAC API doesn't support adding, editing, or removing items. diff --git a/ogcapi-features/extensions/version/README.md b/ogcapi-features/extensions/version/README.md index 166dec79..9aef800b 100644 --- a/ogcapi-features/extensions/version/README.md +++ b/ogcapi-features/extensions/version/README.md @@ -2,7 +2,7 @@ - **OpenAPI specification:** [openapi.yaml](openapi.yaml) - **Conformance URI:** -- **Extension [Maturity Classification](../../../extensions.md#extension-maturity):** Proposal +- **Extension [Maturity Classification](../../../README.md#maturity-classification):** Proposal - **Dependencies**: [STAC API - Features](../../README.md) The core API doesn't support semantics to creating and accessing different versions of an Item or Collection.