diff --git a/CHANGELOG.md b/CHANGELOG.md index 93744fd8..bbb23fcb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,12 +5,21 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [v1.0.0-rc.4] - 2023-04-13 + +## Changed + +- Field `type` is no longer required for all Link objects, but is instead strongly + recommended. This was added as a requirement in 1.0.0-rc.3 based on a mis-reading + of the OGC Features spec, and is now removed as a requirement. + ## [v1.0.0-rc.3] - 2023-03-27 ## Changed - Browseable has been moved to an extension, now located at - Link relation `parent` is no longer a required link for Collections or Items +- Field `type` is now required for all Link objects ## Added diff --git a/CITATION.cff b/CITATION.cff index 914208cf..ee568121 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -8,9 +8,9 @@ preferred-citation: type: standard title: "SpatioTemporal Asset Catalog (STAC) API specification" abstract: "An API to make geospatial assets openly searchable and crawlable." - version: 1.0.0-rc.3 + version: 1.0.0-rc.4 year: 2023 - date-released: 2023-03-27 + date-released: 2023-04-13 license: Apache-2.0 url: https://stacspec.org repository: https://github.com/radiantearth/stac-api-spec diff --git a/README.md b/README.md index 6acd0849..6f3fc72e 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ ## Releases (stable) -- [v1.0.0-rc.3](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.3) (latest) +- [v1.0.0-rc.4](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.4) (latest) +- [v1.0.0-rc.3](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.3) - [v1.0.0-rc.2](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2) - [v1.0.0-rc.1](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1) - [v1.0.0-beta.5](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.5) @@ -58,13 +59,13 @@ to search STAC catalogs, where the features returned are STAC [Item](stac-spec/i 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](http://openapis.org/) 3.0 specification, -rendered online into HTML at , in addition to human-readable documentation. +rendered online into HTML at , in addition to human-readable documentation. ## 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. -As of v1.0.0-rc.3, we remain fully aligned with +As of v1.0.0-rc.4, 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 diff --git a/core/README.md b/core/README.md index 8e796913..1916a57c 100644 --- a/core/README.md +++ b/core/README.md @@ -11,9 +11,9 @@ ## Summary -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.3/core)), +- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.4/core)), - **Conformance URIs:** - - + - - **[Maturity Classification](../README.md#maturity-classification):** Candidate - **Dependencies**: None and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. @@ -21,7 +21,7 @@ ## Overview All STAC API implementations must implement the *STAC API - Core* conformance class -. This requires a server to return from a root endpoint a valid +. This requires a server to return from a root endpoint a valid [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) "landing page" that also includes a `conformsTo` attribute with a string array value. Any API implementing this is considered a minimal, valid STAC API. @@ -63,8 +63,8 @@ but sub-catalogs whose items are all in one database can support search. ## Link Relations -While the STAC definition of Link does not require the `type` field, -*STAC API - Core* requires all Links to have this field. +The STAC definition of Link does not require the `type` field, +but it is **STRONGLY RECOMMENDED** that this field exists. If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`. The following Link relations are defined for the Landing Page (root). @@ -149,7 +149,7 @@ different conformance classes and a different set of links. "description": "This Catalog aims to demonstrate a simple landing page", "type": "Catalog", "conformsTo" : [ - "https://api.stacspec.org/v1.0.0-rc.3/core" + "https://api.stacspec.org/v1.0.0-rc.4/core" ], "links": [ { diff --git a/core/commons.yaml b/core/commons.yaml index c4df3e2c..47b52bed 100644 --- a/core/commons.yaml +++ b/core/commons.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: The SpatioTemporal Asset Catalog API - Commons description: This is the OpenAPI version of the core STAC spec JSON Schemas. - version: 1.0.0-rc.3 + version: 1.0.0-rc.4 paths: {} components: responses: diff --git a/core/openapi.yaml b/core/openapi.yaml index ac9c1e60..3ede79a8 100644 --- a/core/openapi.yaml +++ b/core/openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: STAC API - Core - version: 1.0.0-rc.3 + version: 1.0.0-rc.4 description: >- This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Core specification. Any service that implements this endpoint to allow discovery of @@ -12,7 +12,7 @@ info: license: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' - x-conformance-classes: ['https://api.stacspec.org/v1.0.0-rc.3/core'] + x-conformance-classes: ['https://api.stacspec.org/v1.0.0-rc.4/core'] tags: - name: Core description: essential characteristics of a STAC API @@ -64,7 +64,7 @@ components: title: Copernicus Sentinel Imagery description: Catalog of Copernicus Sentinel 1 and 2 imagery. conformsTo: - - 'https://api.stacspec.org/v1.0.0-rc.3/core' + - 'https://api.stacspec.org/v1.0.0-rc.4/core' links: - href: 'http://data.example.org/' rel: self diff --git a/fragments/itemcollection/openapi.yaml b/fragments/itemcollection/openapi.yaml index 7236d9a1..c1e83e20 100644 --- a/fragments/itemcollection/openapi.yaml +++ b/fragments/itemcollection/openapi.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: The SpatioTemporal Asset Catalog API - Item Collection description: The specification for a set of items, e.g. returned by a search. - version: 1.0.0-rc.3 + version: 1.0.0-rc.4 paths: {} components: schemas: diff --git a/item-search/README.md b/item-search/README.md index 749eafff..31c91b1b 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -19,9 +19,9 @@ ## Summary -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.3/item-search)) +- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.4/item-search)) - **Conformance URIs:** - - + - - **[Maturity Classification](../README.md#maturity-classification):** Candidate - **Dependencies**: [STAC API - Core](../core) - **Examples**: [examples.md](examples.md) @@ -29,7 +29,7 @@ ## Overview The *STAC API - Item Search* specification defines the *STAC API - Item Search* -conformance class (), which +conformance class (), which provides the ability to search for STAC [Item](../stac-spec/item-spec/README.md) objects across collections. It retrieves a group of Item objects that match the provided parameters, wrapped in an @@ -49,8 +49,8 @@ Implementing `GET /search` is **required**, `POST /search` is optional, but reco ## Link Relations -While the STAC definition of Link does not require the `type` field, -*STAC API - Item Search* requires all Links to have this field. +The STAC definition of Link does not require the `type` field, +but it is **STRONGLY RECOMMENDED** that this field exists. If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`. This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. @@ -275,8 +275,8 @@ the [overview](../overview.md#example-landing-page) document. "description": "This Catalog aims to demonstrate the a simple landing page", "type": "Catalog", "conformsTo" : [ - "https://api.stacspec.org/v1.0.0-rc.3/core", - "https://api.stacspec.org/v1.0.0-rc.3/item-search" + "https://api.stacspec.org/v1.0.0-rc.4/core", + "https://api.stacspec.org/v1.0.0-rc.4/item-search" ], "links": [ { diff --git a/item-search/openapi.yaml b/item-search/openapi.yaml index 6b18f620..7be53aa9 100644 --- a/item-search/openapi.yaml +++ b/item-search/openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: STAC API - Item Search - version: 1.0.0-rc.3 + version: 1.0.0-rc.4 description: >- This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Item Search specification. @@ -14,7 +14,7 @@ info: tags: - name: Item Search description: essential characteristics of a STAC API -x-conformance-classes: ['https://api.stacspec.org/v1.0.0-rc.3/item-search'] +x-conformance-classes: ['https://api.stacspec.org/v1.0.0-rc.4/item-search'] paths: /search: get: diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index db53b133..c5a8837a 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -26,11 +26,11 @@ ## Summary - **OpenAPI specifications:** - - [STAC API - Features](openapi-features.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.3/ogcapi-features)) - - [STAC API - Collections](openapi-collections.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.3/collections)) + - [STAC API - Features](openapi-features.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.4/ogcapi-features)) + - [STAC API - Collections](openapi-collections.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.4/collections)) - **Conformance Class URIs:** - - - Features - - - Collections + - - Features + - - Collections - **[Maturity Classification](../README.md#maturity-classification):** Candidate - **Dependencies**: - [STAC API - Core](../core) @@ -51,19 +51,19 @@ entities. As these entities are also GeoJSON types, the GeoJSON conformance clas While OAFeat defines a single conformance class for its endpoints, STAC API divides these behaviors into two conformance classes -- Collections and Features. The STAC API - Features -() conformance class includes and extends the behavior -of OAFeat, while the STAC API - Collections () conformance +() conformance class includes and extends the behavior +of OAFeat, while the STAC API - Collections () conformance class is the subset of Features that pertains only to Collections. ### STAC API - Features -The *STAC API - Features* () conformance class +The *STAC API - Features* () conformance class encompasses all of the behavior described in this specification, as derived from OAFeat. ### STAC API - Collections -The *STAC API - Collections* () conformance class +The *STAC API - Collections* () conformance class requires only the subset of the behavior of Features that relates to Collections. This subset is: @@ -77,7 +77,7 @@ without needing to implement the entire *STAC API - Features* conformance class. ### OGC API - Features - Part 1: Core -A STAC API implementation that conforms to *STAC API - Features* () +A STAC API implementation that conforms to *STAC API - Features* () also conforms to [OGC API - Features - Part 1 Requirements Class Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_core) conformance class (). @@ -100,8 +100,8 @@ by *STAC API - Core*, the These conformance classes also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. -While the STAC definition of Link does not require the `type` field, this is required by OAFeat, -and is thereby required by the *STAC API - Features* conformance class. +The STAC definition of Link does not require the `type` field, +but it is **STRONGLY RECOMMENDED** that this field exists. If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`. ### Landing Page (/) @@ -355,9 +355,9 @@ the [overview](../overview.md#example-landing-page) document. "description": "This Catalog aims to demonstrate the a simple landing page", "type": "Catalog", "conformsTo" : [ - "https://api.stacspec.org/v1.0.0-rc.3/core", - "https://api.stacspec.org/v1.0.0-rc.3/ogcapi-features", - "https://api.stacspec.org/v1.0.0-rc.3/collections", + "https://api.stacspec.org/v1.0.0-rc.4/core", + "https://api.stacspec.org/v1.0.0-rc.4/ogcapi-features", + "https://api.stacspec.org/v1.0.0-rc.4/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" diff --git a/ogcapi-features/openapi-collections.yaml b/ogcapi-features/openapi-collections.yaml index 70bda198..743b41a3 100644 --- a/ogcapi-features/openapi-collections.yaml +++ b/ogcapi-features/openapi-collections.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: STAC API - Collections - version: 1.0.0-rc.3 + version: 1.0.0-rc.4 description: >- This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Collections specification. This is a subset of the STAC API - Features specification. @@ -11,7 +11,7 @@ info: license: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' - x-conformance-classes: ['https://api.stacspec.org/v1.0.0-rc.3/collections'] + x-conformance-classes: ['https://api.stacspec.org/v1.0.0-rc.4/collections'] tags: - name: Core description: essential characteristics of a STAC API @@ -46,7 +46,7 @@ paths: title: Copernicus Sentinel Imagery description: Catalog of Copernicus Sentinel 1 and 2 imagery. conformsTo: - - 'https://api.stacspec.org/v1.0.0-rc.3/core' + - 'https://api.stacspec.org/v1.0.0-rc.4/core' - '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' diff --git a/ogcapi-features/openapi-features.yaml b/ogcapi-features/openapi-features.yaml index fa66ec2e..aa60df34 100644 --- a/ogcapi-features/openapi-features.yaml +++ b/ogcapi-features/openapi-features.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: STAC API - Features - version: 1.0.0-rc.3 + version: 1.0.0-rc.4 description: >- This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Features specification. This extends OGC API - Features - Part 1: Core. @@ -12,7 +12,7 @@ info: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' x-conformance-classes: - ['https://api.stacspec.org/v1.0.0-rc.3/ogcapi-features'] + ['https://api.stacspec.org/v1.0.0-rc.4/ogcapi-features'] tags: - name: Features description: |- @@ -46,7 +46,7 @@ paths: title: Copernicus Sentinel Imagery description: Catalog of Copernicus Sentinel 1 and 2 imagery. conformsTo: - - 'https://api.stacspec.org/v1.0.0-rc.3/core' + - 'https://api.stacspec.org/v1.0.0-rc.4/core' - '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' diff --git a/overview.md b/overview.md index 53a341bf..8ae45484 100644 --- a/overview.md +++ b/overview.md @@ -20,7 +20,7 @@ point for the more powerful capabilities - it contains a list of URLs with link 'relationships' (`rel`) and descriptions to indicate their functionality. Note that the [STAC Core specification](stac-spec) provides most of the content of API responses - the STAC API is primarily concerned with the return of STAC [Item](stac-spec/item-spec/README.md) and [Collection](stac-spec/collection-spec/README.md) objects via a -web API. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0-rc.3/core) for more details. +web API. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0-rc.4/core) for more details. There are then two major sets of functionality that build on the core, [Item Search](item-search) and [Collection and Features](ogcapi-features) , which are designed to be complementary, letting @@ -33,7 +33,7 @@ located at a `/search` endpoint. It re-uses all of the OAFeat [query parameters](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) specified in their 'core', and adds a few more. It does not require a full implementation of OAFeat, but it is instead a simplified construct that can run a search across any group of STAC [`Item`](stac-spec/item-spec/README.md) objects. See the [rendered OpenAPI -document](https://api.stacspec.org/v1.0.0-rc.3/item-search) for more details. +document](https://api.stacspec.org/v1.0.0-rc.4/item-search) for more details. ### Collections and Features @@ -50,7 +50,7 @@ Full compliance involves splitting STAC `Item` objects into individual `/collections/{collectionId}/items` endpoints that expose querying single collections, as OAFeat does not currently support cross-collection search. It also adds a few other requirements, which are highlighted in the [features description](ogcapi-features/), in order to help STAC implementors understand OAFeat without having to -read the full specification from scratch. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0-rc.3/ogcapi-features) +read the full specification from scratch. See the [rendered OpenAPI document](https://api.stacspec.org/v1.0.0-rc.4/ogcapi-features) for more details. ### Extensions & Fragments @@ -118,10 +118,10 @@ conformance URIs serve up a rendered HTML version of the corresponding OpenAPI d | **Name** | **Specified in** | **Conformance URI** | **Description** | | ---------------------- | ------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | -| STAC API - Core | [Core](core) | | Specifies the STAC Landing page `/`, communicating conformance and available endpoints. | -| STAC API - Item Search | [Item Search](item-search) | | Enables search of all STAC Item objects on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. | -| STAC API - Features | [Collections and Features](ogcapi-features) | | Specifies the use of OGC API - Features to serve STAC Item and Collection objects | -| STAC API - Collections | [Collections and Features](ogcapi-features) | | Specifies the use of a subset of STAC API - Features to serve Collection objects | +| STAC API - Core | [Core](core) | | Specifies the STAC Landing page `/`, communicating conformance and available endpoints. | +| STAC API - Item Search | [Item Search](item-search) | | Enables search of all STAC Item objects on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. | +| STAC API - Features | [Collections and Features](ogcapi-features) | | Specifies the use of OGC API - Features to serve STAC Item and Collection objects | +| STAC API - Collections | [Collections and Features](ogcapi-features) | | Specifies the use of a subset of STAC API - Features to serve Collection objects | Additional conformance classes can be specified by [STAC API Extensions](extensions.md). @@ -143,10 +143,10 @@ The Landing Page will at least have the following `conformsTo` and `links`: "description": "This Catalog aims to demonstrate the a simple landing page", "type": "Catalog", "conformsTo" : [ - "https://api.stacspec.org/v1.0.0-rc.3/core", - "https://api.stacspec.org/v1.0.0-rc.3/collections", - "https://api.stacspec.org/v1.0.0-rc.3/ogcapi-features", - "https://api.stacspec.org/v1.0.0-rc.3/item-search", + "https://api.stacspec.org/v1.0.0-rc.4/core", + "https://api.stacspec.org/v1.0.0-rc.4/collections", + "https://api.stacspec.org/v1.0.0-rc.4/ogcapi-features", + "https://api.stacspec.org/v1.0.0-rc.4/item-search", "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" diff --git a/package-lock.json b/package-lock.json index c68fc775..15c775d8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "api-spec", - "version": "1.0.0-rc.3", + "version": "1.0.0-rc.4", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "api-spec", - "version": "1.0.0-rc.3", + "version": "1.0.0-rc.4", "license": "Apache-2.0", "dependencies": { "@redocly/openapi-cli": "^1.0.0-beta.94", @@ -4575,6 +4575,15 @@ "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" }, + "node_modules/redoc-cli/node_modules/@types/mkdirp": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@types/mkdirp/-/mkdirp-1.0.1.tgz", + "integrity": "sha512-HkGSK7CGAXncr8Qn/0VqNtExEE+PHMWb+qlR1faHMao7ng6P3tAaoWWBMdva0gL5h4zprjIO89GJOLXsMcDm1Q==", + "extraneous": true, + "dependencies": { + "@types/node": "*" + } + }, "node_modules/redoc-cli/node_modules/@types/node": { "version": "15.12.2", "resolved": "https://registry.npmjs.org/@types/node/-/node-15.12.2.tgz", @@ -13042,6 +13051,14 @@ "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" }, + "@types/mkdirp": { + "version": "https://registry.npmjs.org/@types/mkdirp/-/mkdirp-1.0.1.tgz", + "integrity": "sha512-HkGSK7CGAXncr8Qn/0VqNtExEE+PHMWb+qlR1faHMao7ng6P3tAaoWWBMdva0gL5h4zprjIO89GJOLXsMcDm1Q==", + "extraneous": true, + "requires": { + "@types/node": "*" + } + }, "@types/node": { "version": "15.12.2", "resolved": "https://registry.npmjs.org/@types/node/-/node-15.12.2.tgz", diff --git a/package.json b/package.json index 1ad9c7ff..4ab5918c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "api-spec", - "version": "1.0.0-rc.3", + "version": "1.0.0-rc.4", "description": "STAC API helpers to generate, serve and check the API spec.", "repository": "https://github.com/radiantearth/stac-api-spec", "license": "Apache-2.0", @@ -100,4 +100,4 @@ ] ] } -} +} \ No newline at end of file