From 13381aa8b35c3751f0b39e1cf678c18233d3a035 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 12 Nov 2020 20:17:28 -0800 Subject: [PATCH 01/10] update stability note --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8aba7377..3ee53a7c 100644 --- a/README.md +++ b/README.md @@ -20,15 +20,14 @@ compatible and usable with any OGC API - Features clients. The STAC API can be t to search STAC Catalogs, where the features returned are STAC [Items](https://github.com/radiantearth/stac-spec/item-spec/item-spec.md), that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets. -## WARNING - -This specification is approaching maturity, but will likely have some minor changes as we approach the 1.0-beta release and -fully align with [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). This repo was also recently -split off from the main [stac-spec repository](https://github.com/radiantearth/stac-spec). Not all links and references have -been updated yet so should be considered a work in progress. To implement against a stable STAC API we recommend using -[STAC API Version 0.9.0](https://github.com/radiantearth/stac-spec/tree/v0.9.0/api-spec). This master branch will be -considered to be under active development until we release version 1.0-beta, at which time it will be stable, and a `dev` -branch will be created for active development. +## 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 - +Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) Version 1.0. We have further aligned STAC extensions +with OGC API - Features extensions, particularly [CQL](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/cql/) +and [Transactions](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/transactions). These are not +yet entirely stable, so if they change then STAC will update to remain in line. ## Communication From a4cc645fcd02592349dd09bbdca6899beb30c9d8 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 12 Nov 2020 21:28:12 -0800 Subject: [PATCH 02/10] added intro and section on compliance --- api-spec.md | 51 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/api-spec.md b/api-spec.md index a42bf89a..fe035cf5 100644 --- a/api-spec.md +++ b/api-spec.md @@ -1,17 +1,27 @@ # STAC API Specification -The STAC API is intended to be a superset of the *OGC API - Features - Part 1: Core* (OAFeat) standard. STAC API -currently is based on [OAFeat version 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), previously known as -OGC Web Feature Service (WFS). Future STAC API releases will align with -[upcoming versions](https://github.com/opengeospatial/ogcapi-features). +## About + +The STAC API defines a RESTful JSON-based server to query [SpatioTemporal Asset Catalogs](https://github.com/radiantearth/stac-spec/) +(STAC). While the core STAC specification provides a structure and language to describe assets, users usually want to access +a subset of the entire catalog, such as for a certain date range, in a particular area of interest, or matching properties +they care about. STAC API specifies those query parameters, and compliant servers return collections of STAC Items that +match the user's preferences. + +## STAC API and OGC API - Features + +The vast majority of what STAC API does is specified in the *[OGC API - Features](https://ogcapi.ogc.org/features/)* +standard ('OAFeat' for our shorthand). STAC API is fully compliant with [OAFeat - Part 1: Core, version +1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), and will be aligned with their additional extensions +when they are finalized. Future STAC API releases will align with [upcoming versions](https://github.com/opengeospatial/ogcapi-features). +STAC API adds certain requirements and extensions on top of the OAFeat core, to meet its community's use cases, detailed below. The OGC API - Features is a standard API that represents collections of geospatial data. It defines the RESTful interface to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry plus any number of properties. The core [STAC Item spec](https://github.com/radiantearth/stac-spec/item-spec/README.md) enhances the core `Feature` with additional requirements and options to enable cataloging of spatiotemporal 'assets' like satellite imagery. This STAC `Item` always links to an asset, and these assets always have a capture time, so it requires -fields for `datetime` and `assets`. The STAC API extends the OAFeat core with some key functionality to enable search of -geospatial assets, detailed below. +fields for `datetime` and `assets`. OAFeat also defines the concept of a Collection, which contains Features. In OAFeat Collections are the sets of data that can be queried ([7.11](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_)), and each describes basic @@ -21,15 +31,19 @@ information, along with other STAC specific fields to provide additional metadat thus are compliant with both OAFeat Collections and STAC Collections and are returned from the `/collections/{collection_id}` endpoint. -In OAFeat Features are the individual records within a Collection and are provided in GeoJSON format. -[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are analogous to OAFeat Features, -are in GeoJSON, and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint. +In OAFeat Features are the individual records within a Collection and are usually provided in GeoJSON format. +[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are compliant with the OAFeat Features [GeoJSON +requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the +`/collections/{collection_id}/items/{item_id}` endpoint. The return of other encodings +([html](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_html), [gml](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_gmlsf0)) +is outside the scope of STAC API, as the [STAC Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) is +specified in GeoJSON. A typical OAFeat will have multiple collections, and each will just offer simple search for its particular collection at `GET /collections/{collectionId}/items`. The main STAC endpoint specified beyond what OAFeat offers is `/search`, which offers cross-collection search. A primary use case of STAC is to search diverse imagery collections (like Landsat, Sentinel, MODIS) by location and cloud cover for any -relevant image. So the ability to do searches across Collections is required, and is not yet specified by OAFeat. Due to the +relevant image. So the ability to do searches across Collections is very important, and is not yet specified by OAFeat. Due to the limited parameter support in OGC API - Features, it is recommended to use the STAC API endpoint `POST /search` for advanced queries, as it supports richer options. The filtering is made to be compatible between STAC API and OGC API - Features whenever feasible, and the two specs seek @@ -40,6 +54,23 @@ Implementations may **optionally** provide support for the full superset of STAC where the collection ID in the path is equivalent to providing that single value in the `collections` query parameter in STAC API. +### STAC API Compliance + +To be a compliant STAC API an implementation must either: + +1) Fully implement [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) core, and have one or more +[Feature Collections](http://docs.ogc.org/is/17-069r3/17-069r3.html#_collections_) implement STAC +[Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md), with its returned +[Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) as valid STAC +[Items](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md). +2) Implement the [STAC API Endpoints](#stac-api-endpoints), with `/` returning valid STAC +[Catalogs](https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md) and `/search` returning valid +[Items](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md). + +The recommendation is to implement both, with `/search` providing cross-collection search and then having each +`/collections/{collectionId}` describe a homogeneous set of STAC Items, but only one of the two is required to be a +valid STAC API implementation. + ## HTTP Request Methods and Content Types The OAFeat and STAC APIs follow a RESTful model. A core principal of this is the use of HTTP Request Methods ("verbs") and From ae4b0f18fb9311588bd318cf39e0156298b407c2 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 12 Nov 2020 21:31:39 -0800 Subject: [PATCH 03/10] added info on compliance addition --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 939e1727..46a4d3dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added + - Clearer language on compliance requirements ### Changed - Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute From d223e4492ef32f9a65993b2fa6118f56f69b3b63 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Fri, 13 Nov 2020 10:47:11 -0800 Subject: [PATCH 04/10] better headings --- api-spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api-spec.md b/api-spec.md index fe035cf5..3974810b 100644 --- a/api-spec.md +++ b/api-spec.md @@ -226,7 +226,7 @@ with a single value array in JSON if the same functionality is desired. For filt query parameters should use comma-separated string values (with no outer brackets \[ or \]) and JSON entity attributes should use JSON Arrays. -### Examples +### Query Examples ```http GET /search?collections=landsat8,sentinel&bbox=-10.415,36.066,3.779,44.213&limit=200&datetime=2017-05-05T00:00:00Z @@ -241,6 +241,8 @@ GET /search?collections=landsat8,sentinel&bbox=-10.415,36.066,3.779,44.213&limit } ``` +### Query Parameter Table + | Parameter | Type | APIs | Description | | ----------- | ---------------- | ------------ | ----------- | | collectionId | string | OAFeat | **Path-only** Single Collection ID to include in the search for items. Only Items in one of the provided Collection will be searched | From 1dbdeced1719a4cdc6bbc7f04060668fd052d05e Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 17 Nov 2020 23:22:35 -0500 Subject: [PATCH 05/10] fix invalid markdown link due to split across lines --- api-spec.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api-spec.md b/api-spec.md index ab85fdb5..f8fe94b1 100644 --- a/api-spec.md +++ b/api-spec.md @@ -32,8 +32,7 @@ thus are compliant with both OAFeat Collections and STAC Collections and are ret endpoint. In OAFeat Features are the individual records within a Collection and are usually provided in GeoJSON format. -[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are compliant with the OAFeat Features [GeoJSON -requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the +[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are compliant with the OAFeat Features [GeoJSON requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint. The return of other encodings ([html](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_html), [gml](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_gmlsf0)) is outside the scope of STAC API, as the [STAC Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) is From fe8083010b2831fda9ca7d9d73ab4a4f8dde747a Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 17 Nov 2020 23:30:14 -0500 Subject: [PATCH 06/10] fix markdown warnings --- CHANGELOG.md | 2 +- api-spec.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ab71825f..d62a903b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## \[Unreleased\] ### Added - - Clearer language on compliance requirements +- Clearer language on compliance requirements ### Changed - Updated to STAC specification version 1.0.0-beta.2 diff --git a/api-spec.md b/api-spec.md index f8fe94b1..aaad3bfb 100644 --- a/api-spec.md +++ b/api-spec.md @@ -32,7 +32,8 @@ thus are compliant with both OAFeat Collections and STAC Collections and are ret endpoint. In OAFeat Features are the individual records within a Collection and are usually provided in GeoJSON format. -[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are compliant with the OAFeat Features [GeoJSON requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the +[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are compliant with the OAFeat Features +[GeoJSON requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint. The return of other encodings ([html](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_html), [gml](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_gmlsf0)) is outside the scope of STAC API, as the [STAC Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) is From 12f67c4213392c87ac42214485a6e278597a4c8d Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 18 Nov 2020 13:56:09 -0800 Subject: [PATCH 07/10] Update api-spec.md --- api-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-spec.md b/api-spec.md index aaad3bfb..78940449 100644 --- a/api-spec.md +++ b/api-spec.md @@ -43,7 +43,7 @@ A typical OAFeat will have multiple collections, and each will just offer simple `GET /collections/{collectionId}/items`. The main STAC endpoint specified beyond what OAFeat offers is `/search`, which offers cross-collection search. A primary use case of STAC is to search diverse imagery collections (like Landsat, Sentinel, MODIS) by location and cloud cover for any -relevant image. So the ability to do searches across Collections is very important, and is not yet specified by OAFeat. Due to the +matching item. So the ability to do searches across Collections is very important, and is not yet specified by OAFeat. Due to the limited parameter support in OGC API - Features, it is recommended to use the STAC API endpoint `POST /search` for advanced queries, as it supports richer options. The filtering is made to be compatible between STAC API and OGC API - Features whenever feasible, and the two specs seek From 858caebdee96dab68e4948c5e021608e2b8388c6 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 18 Nov 2020 14:01:06 -0800 Subject: [PATCH 08/10] took out compliance stuff, to put it in conformance PR --- api-spec.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/api-spec.md b/api-spec.md index 78940449..fa2f09b2 100644 --- a/api-spec.md +++ b/api-spec.md @@ -54,23 +54,6 @@ Implementations may **optionally** provide support for the full superset of STAC where the collection ID in the path is equivalent to providing that single value in the `collections` query parameter in STAC API. -### STAC API Compliance - -To be a compliant STAC API an implementation must either: - -1) Fully implement [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) core, and have one or more -[Feature Collections](http://docs.ogc.org/is/17-069r3/17-069r3.html#_collections_) implement STAC -[Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md), with its returned -[Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) as valid STAC -[Items](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md). -2) Implement the [STAC API Endpoints](#stac-api-endpoints), with `/` returning valid STAC -[Catalogs](https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md) and `/search` returning valid -[Items](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md). - -The recommendation is to implement both, with `/search` providing cross-collection search and then having each -`/collections/{collectionId}` describe a homogeneous set of STAC Items, but only one of the two is required to be a -valid STAC API implementation. - ## HTTP Request Methods and Content Types The OAFeat and STAC APIs follow a RESTful model. A core principal of this is the use of HTTP Request Methods ("verbs") and From ab3cc732688115e58af56a10721c08df3b99d028 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 18 Nov 2020 14:02:04 -0800 Subject: [PATCH 09/10] updated changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d62a903b..cb2457a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## \[Unreleased\] ### Added -- Clearer language on compliance requirements +- More intro text ### Changed - Updated to STAC specification version 1.0.0-beta.2 From c6b586bbf9a8c6e4d3fde8f5af27b848b6e7ae29 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 18 Nov 2020 14:24:23 -0800 Subject: [PATCH 10/10] took out changelog entry, as this is all minor stuff now --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cb2457a5..fb4168a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## \[Unreleased\] ### Added -- More intro text ### Changed - Updated to STAC specification version 1.0.0-beta.2