From 47dc3a77a9d34bd92b0fe0d72ae9e6e919466626 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 25 Oct 2019 18:47:14 +0200 Subject: [PATCH 1/4] First draft to update `GET /collections` and `GET /collections/{collectionId}` to STAC version 0.8.1 #185, #204. Removes optional STAC extensions from the API specification #176. --- CHANGELOG.md | 2 +- docs/collections.md | 4 +- openapi.json | 1081 +++++++++++++++---------------------------- 3 files changed, 384 insertions(+), 703 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index efab0b06..5deacf25 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Unsupported endpoints are not forced to return a `FeatureUnsupported` (501) error and can return a simple `NotFound` (404) instead. -- `GET /collections/{collectionId}`: Band names are required. +- `GET /collections` and `GET /collections/{collectionId}`: Updated STAC to version 0.8.1 ([#185](https://github.com/Open-EO/openeo-api/issues/185), [#204](https://github.com/Open-EO/openeo-api/issues/204)) and removed optional STAC extensions from the API specification ([#176](https://github.com/Open-EO/openeo-api/issues/176)). - If `currency` returned by `GET /` is null, `costs` and `budget` are unsupported. `costs` and `budget` fields in various endpoints can be set to null (default). - The default type for Process Graph Variables is not string, but any data type. Default values can be of any type. - Official support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html). [#203](https://github.com/Open-EO/openeo-api/issues/203) diff --git a/docs/collections.md b/docs/collections.md index d0903884..f0598bd1 100644 --- a/docs/collections.md +++ b/docs/collections.md @@ -7,7 +7,7 @@ Therefore, it is very likely that further changes and adjustments will be made i ## Extensions -STAC has several [extensions](https://github.com/radiantearth/stac-spec/tree/v0.6.2/extensions) that can be used to better describe your data. Clients and server are not required to implement all of them, so be aware that some clients may not be able to read all your meta data. +STAC has several [extensions](https://github.com/radiantearth/stac-spec/tree/v0.8.1/extensions) that can be used to better describe your data. Clients and server are not required to implement all of them, so be aware that some clients may not be able to read all your meta data. Some commonly used extensions that are integrated in the openEO API specification are: @@ -67,4 +67,4 @@ As of now, STAC has two more required endpoints that need to be implemented: ## Provide data for download -If you'd like to provide your data for download in addition to offering the cloud processing service, you can implement the full STAC API. Therefore you can implement the endpoints `GET /collections/{collectionId}/items` and `GET /collections/{collection-name}/items/{featureId}` to support retrieval of individual items. To benefit from the STAC ecosystem it is also recommended to implement the `GET /stac` endpoint. To allow searching for items you can also implement `POST /stac/search`. Further information can be found in the [STAC API respository](https://github.com/radiantearth/stac-spec/tree/v0.6.2/api-spec) and in the corresponding [OpenAPI specification](https://app.swaggerhub.com/apis/cholmesgeo/STAC_WFS-example/0.6.2). \ No newline at end of file +If you'd like to provide your data for download in addition to offering the cloud processing service, you can implement the full STAC API. Therefore you can implement the endpoints `GET /collections/{collectionId}/items` and `GET /collections/{collection-name}/items/{featureId}` to support retrieval of individual items. To benefit from the STAC ecosystem it is also recommended to implement the `GET /stac` endpoint. To allow searching for items you can also implement `POST /stac/search`. Further information can be found in the [STAC API respository](https://github.com/radiantearth/stac-spec/tree/v0.8.1/api-spec) and in the corresponding [OpenAPI specification](https://stacspec.org/STAC-api.html). \ No newline at end of file diff --git a/openapi.json b/openapi.json index 4a1f387e..f76c59db 100644 --- a/openapi.json +++ b/openapi.json @@ -545,7 +545,7 @@ "/collections": { "get": { "summary": "Basic metadata for all datasets.", - "description": "Lists available collections with basic information. To retrieve domain specific information (e.g. SAR) request all information for a specific collection using `GET /collections/{collection_id}`.\n\nThis endpoint is compatible with [STAC 0.8.0](https://stacspec.org) and [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). [STAC API](https://github.com/radiantearth/stac-spec/tree/master/api-spec) features / extensions and [STAC content extensions](https://github.com/radiantearth/stac-spec/tree/master/extensions#list-of-content-extensions) can be implemented in addition to what is documented here.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/draft/collections/), including common relation types for links, are available in the documentation.", + "description": "Lists available collections with basic information. To retrieve data cube (property `cube:dimensions`) and domain specific information (property `summaries`, e.g. SAR-specific information) request all information for a specific collection using `GET /collections/{collection_id}`.\n\nThis endpoint is compatible with [STAC 0.8.1](https://stacspec.org) and [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). [STAC API](https://github.com/radiantearth/stac-spec/tree/master/api-spec) features / extensions and [STAC content extensions](https://github.com/radiantearth/stac-spec/tree/master/extensions#list-of-content-extensions) can be implemented in addition to what is documented here.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/draft/collections/), including common relation types for links, are available in the documentation.", "tags": [ "EO Data Discovery" ], @@ -557,7 +557,7 @@ ], "responses": { "200": { - "description": "A list of collections (basic information only) and related links.", + "description": "A list of collections and related links.", "content": { "application/json": { "schema": { @@ -571,51 +571,7 @@ "collections": { "type": "array", "items": { - "title": "Simple STAC Collection", - "type": "object", - "required": [ - "stac_version", - "id", - "description", - "license", - "extent", - "links" - ], - "properties": { - "stac_version": { - "$ref": "#/components/schemas/stac_version" - }, - "id": { - "$ref": "#/components/schemas/collection_id" - }, - "title": { - "$ref": "#/components/schemas/collection_title" - }, - "description": { - "$ref": "#/components/schemas/collection_description" - }, - "keywords": { - "$ref": "#/components/schemas/collection_keywords" - }, - "version": { - "$ref": "#/components/schemas/collection_version" - }, - "deprecated": { - "$ref": "#/components/schemas/collection_deprecated" - }, - "license": { - "$ref": "#/components/schemas/collection_license" - }, - "providers": { - "$ref": "#/components/schemas/collection_providers" - }, - "extent": { - "$ref": "#/components/schemas/collection_extent" - }, - "links": { - "$ref": "#/components/schemas/collection_links" - } - } + "$ref": "#/components/schemas/collection" } }, "links": { @@ -629,22 +585,33 @@ "example": { "collections": [ { - "stac_version": "0.6.2", + "stac_version": "0.8.1", + "stac_extensions": [ + "datacube" + ], "id": "Sentinel-2A", "title": "Sentinel-2A MSI L1C", "description": "Sentinel-2A is a wide-swath, high-resolution, multi-spectral imaging mission supporting Copernicus Land Monitoring studies, including the monitoring of vegetation, soil and water cover, as well as observation of inland waterways and coastal areas.", "license": "proprietary", "extent": { - "spatial": [ - 180, - -56, - -180, - 83 - ], - "temporal": [ - "2015-06-23T00:00:00Z", - "2019-01-01T00:00:00Z" - ] + "spatial": { + "bbox": [ + [ + 180, + -56, + -180, + 83 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2015-06-23T00:00:00Z", + "2019-01-01T00:00:00Z" + ] + ] + } }, "keywords": [ "copernicus", @@ -681,22 +648,33 @@ ] }, { - "stac_version": "0.6.2", + "stac_version": "0.8.1", + "stac_extensions": [ + "datacube" + ], "id": "MOD09Q1", "title": "MODIS/Terra Surface Reflectance 8-Day L3 Global 250m SIN Grid V006", "description": "The MOD09Q1 Version 6 product provides an estimate of the surface spectral reflectance of Terra MODIS Bands 1-2 corrected for atmospheric conditions such as gasses, aerosols, and Rayleigh scattering. Provided along with the two 250 m MODIS bands is one additional layer, the Surface Reflectance QC 250 m band. For each pixel, a value is selected from all the acquisitions within the 8-day composite period. The criteria for the pixel choice include cloud and solar zenith. When several acquisitions meet the criteria the pixel with the minimum channel 3 (blue) value is used. Validation at stage 3 has been achieved for all MODIS Surface Reflectance products.", "license": "proprietary", "extent": { - "spatial": [ - 180, - -90, - -180, - 90 - ], - "temporal": [ - "2000-02-01T00:00:00Z", - null - ] + "spatial": { + "bbox": [ + [ + 180, + -90, + -180, + 90 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2000-02-01T00:00:00Z", + null + ] + ] + } }, "links": [ { @@ -749,7 +727,7 @@ ], "get": { "summary": "Full metadata for a specific dataset", - "description": "Lists all information about a specific collection specified by the identifier `collection_id`.\n\nThis endpoint is compatible with STAC 0.6.2 and all features and extensions of [STAC](https://github.com/radiantearth/stac-spec) can be used here.\n\n**Note:** openEO strives for compatibility with [STAC](https://github.com/radiantearth/stac-spec) and [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) as far as possible. STAC, as well as openEO, is still under development. Therefore, it is likely that further changes and adjustments will be made in the future.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/draft/collections/), including common relation types for links, are available in the documentation.", + "description": "Lists **all** information about a specific collection specified by the identifier `collection_id`.\n\nThis endpoint is compatible with [STAC 0.8.1](https://stacspec.org) and [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). [STAC API](https://github.com/radiantearth/stac-spec/tree/master/api-spec) features / extensions and [STAC content extensions](https://github.com/radiantearth/stac-spec/tree/master/extensions#list-of-content-extensions) can be implemented in addition to what is documented here.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/draft/collections/), including common relation types for links, are available in the documentation.", "tags": [ "EO Data Discovery" ], @@ -765,112 +743,15 @@ "content": { "application/json": { "schema": { - "title": "STAC Collection", - "type": "object", - "required": [ - "stac_version", - "id", - "description", - "license", - "extent", - "links", - "properties", - "other_properties" - ], - "properties": { - "stac_version": { - "$ref": "#/components/schemas/stac_version" + "allOf": [ + { + "$ref": "#/components/schemas/collection" }, - "id": { - "$ref": "#/components/schemas/collection_id" - }, - "title": { - "$ref": "#/components/schemas/collection_title" - }, - "description": { - "$ref": "#/components/schemas/collection_description" - }, - "keywords": { - "$ref": "#/components/schemas/collection_keywords" - }, - "version": { - "$ref": "#/components/schemas/collection_version" - }, - "deprecated": { - "$ref": "#/components/schemas/collection_deprecated" - }, - "license": { - "$ref": "#/components/schemas/collection_license" - }, - "providers": { - "$ref": "#/components/schemas/collection_providers" - }, - "extent": { - "$ref": "#/components/schemas/collection_extent" - }, - "links": { - "$ref": "#/components/schemas/collection_links" - }, - "other_properties": { - "title": "STAC Varying Collection Properties", - "description": "A list of all metadata properties, which don't have common values across the whole collection. Therefore it allows to specify a summary of the values as extent or set of values.", - "type": "object", - "additionalProperties": { - "type": "object", - "properties": { - "extent": { - "title": "STAC Varying Collection Property Extent", - "description": "If the dimension consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-dimensional array. Strings are only allowed for temporal extents, which are formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). Use `null` for open intervals.", - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "nullable": true, - "anyOf": [ - { - "type": "number", - "nullable": true - }, - { - "type": "string", - "format": "date-time" - } - ] - } - }, - "values": { - "title": "STAC Varying Collection Property Values", - "description": "If the property consists of [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level), a set of all potential values can be specified. Only primitive data types allowed.", - "type": "array", - "items": { - "nullable": true, - "anyOf": [ - { - "type": "number", - "nullable": true - }, - { - "type": "string" - }, - { - "type": "string", - "format": "date-time" - }, - { - "type": "boolean" - } - ] - } - } - } - } - }, - "properties": { - "title": "STAC Collection Properties", - "description": "A list of all metadata properties, which are common across the whole collection.", + { "type": "object", "required": [ - "cube:dimensions" + "cube:dimensions", + "summaries" ], "properties": { "cube:dimensions": { @@ -1085,29 +966,59 @@ } ] } - } - }, - "anyOf": [ - { - "title": "STAC Other Extensions", - "description": "Any other extension from STAC or even custom extensions can be used to describe the collection better.", - "type": "object", - "additionalProperties": true - }, - { - "$ref": "#/components/schemas/collection_eo" - }, - { - "$ref": "#/components/schemas/collection_sar" }, - { - "$ref": "#/components/schemas/collection_sci" + "summaries": { + "title": "STAC Summaries (Collection Properties)", + "description": "Collection properties from STAC extensions (e.g. EO, SAR or Scientific) or even custom extensions.\n\nSummaries are either a unique set of all available values *or* statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range can specify the potential range of values, but it is recommended to be as precise as possible. The set of values must contain at least one element and it is strongly recommended to list all values. It is recommended to list as many properties as reasonable so that consumers get a full overview of the Collection. Properties that are covered by the Collection specification (e.g. `providers` and `license`) may not be repeated in the summaries.", + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "array", + "title": "Set of values", + "items": { + "description": "A value of any type." + } + }, + { + "type": "object", + "title": "Statistics", + "description": "By default, only ranges with a minimum and a maximum value can be specified. Ranges can be specified for ordinal values only, which means they need to have a rank order. Therefore, ranges can only be specified for numbers and some special types of strings. Examples: grades (A to F), dates or times. Implementors are free to add other derived statistical values to the object, for example `mean` or `stddev`.", + "required": [ + "min", + "max" + ], + "properties": { + "min": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + } + ] + }, + "max": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + } + ] + } + } + } + ] + } } - ] + } } - }, + ], "example": { - "stac_version": "0.6.2", + "stac_version": "0.8.1", "id": "Sentinel-2", "title": "Sentinel-2 MSI L2A", "description": "Sentinel-2A is a wide-swath, high-resolution, multi-spectral imaging mission supporting Copernicus Land Monitoring studies.", @@ -1128,7 +1039,7 @@ "url": "https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi" }, { - "name": "openEO", + "name": "Google", "roles": [ "host" ], @@ -1136,16 +1047,24 @@ } ], "extent": { - "spatial": [ - 180, - -56, - -180, - 83 - ], - "temporal": [ - "2015-06-23T00:00:00Z", - null - ] + "spatial": { + "bbox": [ + [ + 180, + -56, + -180, + 83 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2015-06-23T00:00:00Z", + null + ] + ] + } }, "links": [ { @@ -1162,207 +1081,147 @@ "title": "ESA Sentinel-2 MSI Level-1C User Guide" } ], - "properties": { - "cube:dimensions": { - "x": { - "type": "spatial", - "axis": "x", - "extent": [ - -180, - 180 - ], - "reference_system": 32632 - }, - "y": { - "type": "spatial", - "axis": "y", - "extent": [ - -56, - 83 - ], - "reference_system": 32632 - }, - "temporal": { - "type": "temporal", - "extent": [ - "2015-06-23T00:00:00Z", - null - ], - "step": null - }, - "spectral": { - "type": "bands", - "values": [ - "B1", - "B2", - "B3", - "B4", - "B5", - "B6", - "B7", - "B8", - "B8A", - "B9", - "B10", - "B11", - "B12" - ] - } + "cube:dimensions": { + "x": { + "type": "spatial", + "axis": "x", + "extent": [ + -180, + 180 + ], + "reference_system": 4326 }, - "sci:citation": "Copernicus Sentinel data [Year]", - "eo:constellation": "Sentinel-2", - "eo:instrument": "MSI", - "eo:bands": [ - { - "name": "B1", - "common_name": "coastal", - "center_wavelength": 0.4439, - "gsd": 60 - }, - { - "name": "B2", - "common_name": "blue", - "center_wavelength": 0.4966, - "gsd": 10 - }, - { - "name": "B3", - "common_name": "green", - "center_wavelength": 0.56, - "gsd": 10 - }, - { - "name": "B4", - "common_name": "red", - "center_wavelength": 0.6645, - "gsd": 10 - }, - { - "name": "B5", - "center_wavelength": 0.7039, - "gsd": 20 - }, - { - "name": "B6", - "center_wavelength": 0.7402, - "gsd": 20 - }, - { - "name": "B7", - "center_wavelength": 0.7825, - "gsd": 20 - }, - { - "name": "B8", - "common_name": "nir", - "center_wavelength": 0.8351, - "gsd": 10 - }, - { - "name": "B8A", - "center_wavelength": 0.8648, - "gsd": 20 - }, - { - "name": "B9", - "center_wavelength": 0.945, - "gsd": 60 - }, - { - "name": "B10", - "center_wavelength": 1.3735, - "gsd": 60 - }, - { - "name": "B11", - "common_name": "swir16", - "center_wavelength": 1.6137, - "gsd": 20 - }, - { - "name": "B12", - "common_name": "swir22", - "center_wavelength": 2.2024, - "gsd": 20 - } - ] - }, - "other_properties": { - "eo:platform": { - "values": [ - "Sentinel-2A", - "Sentinel-2B" - ] + "y": { + "type": "spatial", + "axis": "y", + "extent": [ + -56, + 83 + ], + "reference_system": 4326 }, - "eo:epsg": { + "temporal": { + "type": "temporal", + "extent": [ + "2015-06-23T00:00:00Z", + null + ], + "step": null + }, + "spectral": { + "type": "bands", "values": [ - 32601, - 32602, - 32603, - 32604, - 32605, - 32606, - 32607, - 32608, - 32609, - 32610, - 32611, - 32612, - 32613, - 32614, - 32615, - 32616, - 32617, - 32618, - 32619, - 32620, - 32621, - 32622, - 32623, - 32624, - 32625, - 32626, - 32627, - 32628, - 32629, - 32630, - 32631, - 32632, - 32633, - 32634, - 32635, - 32636, - 32637, - 32638, - 32639, - 32640, - 32641, - 32642, - 32643, - 32644, - 32645, - 32646, - 32647, - 32648, - 32649, - 32650, - 32651, - 32652, - 32653, - 32654, - 32655, - 32656, - 32657, - 32658, - 32659, - 32660 + "B1", + "B2", + "B3", + "B4", + "B5", + "B6", + "B7", + "B8", + "B8A", + "B9", + "B10", + "B11", + "B12" + ] + } + }, + "sci:citation": "Copernicus Sentinel data [Year]", + "summaries": { + "eo:constellation": [ + "Sentinel-2" + ], + "eo:instrument": [ + "MSI" + ], + "eo:bands": [ + [ + { + "name": "B1", + "common_name": "coastal", + "center_wavelength": 0.4439, + "gsd": 60 + }, + { + "name": "B2", + "common_name": "blue", + "center_wavelength": 0.4966, + "gsd": 10 + }, + { + "name": "B3", + "common_name": "green", + "center_wavelength": 0.56, + "gsd": 10 + }, + { + "name": "B4", + "common_name": "red", + "center_wavelength": 0.6645, + "gsd": 10 + }, + { + "name": "B5", + "center_wavelength": 0.7039, + "gsd": 20 + }, + { + "name": "B6", + "center_wavelength": 0.7402, + "gsd": 20 + }, + { + "name": "B7", + "center_wavelength": 0.7825, + "gsd": 20 + }, + { + "name": "B8", + "common_name": "nir", + "center_wavelength": 0.8351, + "gsd": 10 + }, + { + "name": "B8A", + "center_wavelength": 0.8648, + "gsd": 20 + }, + { + "name": "B9", + "center_wavelength": 0.945, + "gsd": 60 + }, + { + "name": "B10", + "center_wavelength": 1.3735, + "gsd": 60 + }, + { + "name": "B11", + "common_name": "swir16", + "center_wavelength": 1.6137, + "gsd": 20 + }, + { + "name": "B12", + "common_name": "swir22", + "center_wavelength": 2.2024, + "gsd": 20 + } ] + ], + "eo:platform": [ + "Sentinel-2A", + "Sentinel-2B" + ], + "eo:epsg": { + "min": 32601, + "max": 32660 }, "eo:cloud_cover": { - "extent": [ - 0, - 100 - ] + "min": 0, + "max": 100 } } } @@ -3725,13 +3584,6 @@ "description": "Specifies whether the implementation is ready to be used in production use (`true`) or not (`false`).\nClients SHOULD only connect to non-production implementations if the user explicitly confirmed to use a non-production implementation.", "default": true }, - "collection_links": { - "description": "Additional links related to this collection. Could reference to other meta data formats with additional information or a preview image.", - "type": "array", - "items": { - "$ref": "#/components/schemas/link" - } - }, "list_links": { "description": "Additional links related to this list of resources. Could reference to alternative formats such as a rendered HTML version.\n\nThe links could also be used for pagination using the [rel types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) `first`, `prev`, `next` and `last`. Pagination is currently OPTIONAL and clients may not support it. Therefore it MUST be implemented in a way that clients not supporting pagination get all resources regardless.", "type": "array", @@ -3802,275 +3654,167 @@ "description": "The billing plan to process and charge the job with. The plans can be retrieved by calling `GET /`. Billing plans MUST be accepted *case insensitive*.", "example": "free" }, - "collection_eo": { - "title": "STAC EO (Electro-Optical)", + "collection": { + "title": "STAC Collection", "type": "object", "required": [ - "eo:gsd", - "eo:platform", - "eo:instrument", - "eo:bands" + "stac_version", + "id", + "description", + "license", + "extent", + "links" ], "properties": { - "eo:gsd": { - "type": "number", - "description": "The nominal Ground Sample Distance for the data, as measured in meters on the ground. Since GSD can vary across a scene depending on projection, this should be the average or most commonly used GSD in the center of the image. If the data includes multiple bands with different GSD values, this should be the value for the greatest number or most common bands. For instance, Landsat optical and short-wave IR bands are all 30 meters, but the panchromatic band is 15 meters. The eo:gsd should be 30 meters in this case since those are the bands most commonly used." + "stac_version": { + "$ref": "#/components/schemas/stac_version" }, - "eo:platform": { - "type": "string", - "description": "Unique name of the specific platform the instrument is attached to. For satellites this would be the name of the satellite (e.g., landsat-8, sentinel-2A), whereas for drones this would be a unique name for the drone." + "stac_extensions": { + "$ref": "#/components/schemas/stac_extensions" }, - "eo:constellation": { - "type": "string", - "description": "The name of the group of satellites that have similar payloads and have their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and radiometric characteristics. Examples are the Sentinel-2 constellation, which has S2A and S2B and RapidEye. This field allows users to search for Sentinel-2 data, for example, without needing to specify which specific platform the data came from." + "id": { + "$ref": "#/components/schemas/collection_id" }, - "eo:instrument": { + "title": { "type": "string", - "description": "The name of the sensor used, although for Items which contain data from multiple sensors this could also name multiple sensors. For example, data from the Landsat-8 platform is collected with the OLI sensor as well as the TIRS sensor, but the data is distributed together and commonly referred to as OLI_TIRS." + "description": "A short descriptive one-line title for the collection." }, - "eo:epsg": { - "type": "number", - "format": "epsg-code", - "description": "EPSG code of the datasource, `null` if no EPSG code.\n\nA Coordinate Reference System (CRS) is the native reference system (sometimes called a 'projection') used by the data, and can usually be referenced using an [EPSG code](http://epsg.io). If the data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points, `eo:epsg` should be set to `null`. It should also be set to `null` if a CRS exists, but for which there is no valid EPSG code.", - "nullable": true + "description": { + "type": "string", + "description": "Detailed multi-line description to fully explain the collection.\n\n[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation." }, - "eo:bands": { + "keywords": { "type": "array", - "description": "This is a list of the available bands where each item is a Band Object.", + "description": "List of keywords describing the collection.", "items": { - "title": "STAC EO Band", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "The name of the band (e.g., \"B01\", \"B02\", \"B1\", \"B5\", \"QA\")." - }, - "common_name": { - "type": "string", - "description": "Not required, but **STRONGLY RECOMMENDED**! The name commonly used to refer to the band to make it easier to search for bands across instruments. See the \"[Common Band Names](https://github.com/radiantearth/stac-spec/tree/master/extensions/eo#common-band-names)\" for a list of accepted common names." - }, - "description": { - "$ref": "#/components/schemas/collection_band_description" - }, - "gsd": { - "type": "number", - "description": "Ground Sample distance, the nominal distance between pixel centers available, in meters. See eo:gsd for more information. Defaults to eo:gsd if not provided." - }, - "accuracy": { - "type": "number", - "description": "The expected error between the measured location and the true location of a pixel, in meters on the ground." - }, - "center_wavelength": { - "type": "number", - "description": "The center wavelength of the band, in micrometers (μm)." - }, - "full_width_half_max": { - "type": "number", - "description": "Full width at half maximum (FWHM) is a common way to describe the size of a spectral band. It is the width, in micrometers (μm), of the bandpass measured at a half of the maximum transmission. Thus, if the maximum transmission of the bandpass was 80%, the FWHM is measured as the width of the bandpass at 40% transmission." - } - } + "type": "string" } - } - } - }, - "collection_sar": { - "title": "STAC SAR", - "type": "object", - "required": [ - "sar:platform", - "sar:instrument", - "sar:instrument_mode", - "sar:frequency_band", - "sar:polarization", - "sar:type" - ], - "properties": { - "sar:platform": { - "description": "Unique name of the specific platform the instrument is attached to. For satellites this would be the name of the satellite (e.g., landsat-8, sentinel-2A), whereas for drones this would be a unique name for the drone.", - "type": "string" }, - "sar:constellation": { - "description": "sar:constellation is the name of the group of satellites that have similar payloads and have their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and radiometric characteristics. Examples are the Sentinel-1 constellation, which has S1A, S1B, S1C and S1D and RADARSAT, which has RADARSAT-1 and RADARSAT-2. This field allows users to search for Sentinel-1 data, for example, without needing to specify which specific platform the data came from.", - "type": "string" + "version": { + "type": "string", + "description": "Version of the collection." }, - "sar:instrument": { - "description": "Name of the sensor used, although for Items which contain data from multiple sensors this could also name multiple sensors.", - "type": "string" + "deprecated": { + "type": "boolean", + "description": "Specifies that the collection is deprecated with the potential to be removed in any of the next versions. It should be transitioned out of usage as soon as possible and users should refrain from using it in new implementations.\n\nA link with relation type `successor-version` SHOULD be added to the `links` and MUST refer to the collection that can be used instead.", + "default": false }, - "sar:instrument_mode": { - "description": "The name of the sensor acquisition mode that is commonly used. This should be the short name, if available. For example, WV for \"Wave mode\" of Sentinel-1 and Envisat ASAR satellites.", - "type": "string", - "example": "WV" + "license": { + "$ref": "#/components/schemas/stac_license" }, - "sar:frequency_band": { - "description": "The common name for the frequency band to make it easier to search for bands across instruments. See section \"[Common Frequency Band Names](https://github.com/radiantearth/stac-spec/tree/master/extensions/sar/README.md#common-frequency-band-names)\" for a list of accepted names.", - "type": "string", - "enum": [ - "P", - "L", - "S", - "C", - "X", - "Ku", - "K", - "Ka" - ] - }, - "sar:center_wavelength": { - "description": "The center wavelength of the instrument, in centimeters (cm).", - "type": "number" - }, - "sar:center_frequency": { - "description": "The center frequency of the instrument, in gigahertz (GHz).", - "type": "number" - }, - "sar:polarization": { - "description": "A single polarization or a polarization combinations specified as array. For single polarized radars one of `HH`, `VV`, `HV` or `VH` must be set. Fully polarimetric radars add all four polarizations to the array. Dual polarized radars and alternating polarization add the corresponding polarizations to the array, for instance for `HH+HV` add both `HH` and `HV`.", - "type": "array", - "minItems": 1, - "maxItems": 4, - "items": { - "type": "string", - "enum": [ - "HH", - "VV", - "HV", - "VH" - ] - } + "providers": { + "$ref": "#/components/schemas/stac_providers" }, - "sar:bands": { - "description": "This is a list of the available bands where each item is a Band Object.", - "type": "array", - "items": { - "title": "STAC SAR Band", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "description": "The name of the band.", - "type": "string" - }, - "description": { - "$ref": "#/components/schemas/collection_band_description" - }, - "data_type": { - "description": "Specifies the type of the data contained in the band, for example `amplitude`, `intensity`, `phase`, `angle`, `sigma0`, `gamma0`.", - "type": "string" - }, - "unit": { - "description": "The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/).", - "type": "string" - }, - "polarization": { - "description": "The polarization of the band, either `HH`, `VV`, `HV`, `VH` or `null` if not applicable.", - "type": "string", - "nullable": true, - "enum": [ - "HH", - "VV", - "HV", - "VH" - ] + "extent": { + "type": "object", + "title": "STAC Collection Extent", + "description": "The extent of the features in the collection. Additional members MAY be added to represent other extents, for example, thermal or pressure ranges.", + "required": [ + "spatial", + "temporal" + ], + "properties": { + "spatial": { + "description": "The *potential* spatial extent of the features in the collection.", + "type": "object", + "properties": { + "bbox": { + "description": "One or more bounding boxes that describe the spatial extent of the dataset.\nIf multiple areas are provided, the union of the bounding\nboxes describes the spatial extent.", + "type": "array", + "minItems": 1, + "items": { + "description": "Each bounding box is provided as four or six numbers, depending on\nwhether the coordinate reference system includes a vertical axis\n(height or depth):\n\n* West (lower left corner, coordinate axis 1)\n* South (lower left corner, coordinate axis 2)\n* Base (optional, minimum value, coordinate axis 3)\n* East (upper right corner, coordinate axis 1)\n* North (upper right corner, coordinate axis 2)\n* Height (optional, maximum value, coordinate axis 3)\n\nThe coordinate reference system of the values is WGS 84 longitude/latitude\n(http://www.opengis.net/def/crs/OGC/1.3/CRS84).\n\nFor WGS 84 longitude/latitude the values are in most cases the sequence of\nminimum longitude, minimum latitude, maximum longitude and maximum latitude.\nHowever, in cases where the box spans the antimeridian the first value\n(west-most box edge) is larger than the third value (east-most box edge).\n\nIf the vertical axis is included, the third and the sixth number are\nthe bottom and the top of the 3-dimensional bounding box.\n\nIf a feature has multiple spatial geometry properties, it is the decision of the\nserver whether only a single spatial geometry property is used to determine\nthe extent or all relevant geometries.", + "type": "array", + "minItems": 4, + "maxItems": 6, + "items": { + "type": "number" + }, + "example": [ + -180, + -90, + 180, + 90 + ] + } + } + } + }, + "temporal": { + "description": "The *potential* temporal extent of the features in the collection.", + "type": "object", + "properties": { + "interval": { + "description": "One or more time intervals that describe the temporal extent of the dataset.\nThe value `null` is supported and indicates an open time intervall.\nIn the Core only a single time interval is supported. Extensions may support\nmultiple intervals. If multiple intervals are provided, the union of the\nintervals describes the temporal extent.", + "type": "array", + "minItems": 1, + "items": { + "description": "Begin and end times of the time interval. The coordinate reference system is the Gregorian calendar.", + "type": "array", + "minItems": 2, + "maxItems": 2, + "items": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "example": [ + "2011-11-11T12:22:11Z", + null + ] + } + } } } } }, - "sar:type": { - "description": "The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1.", - "type": "string" - }, - "sar:resolution": { - "description": "The maximum ability to distinguish two adjacent targets, in meters (m). The first element of the array is the range resolution, the second element is the azimuth resolution.", - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "type": "number", - "minimum": 0 - } - }, - "sar:pixel_spacing": { - "description": "The distance between adjacent pixels, in meters (m). The first element of the array is the range pixel spacing, the second element is the azimuth pixel spacing. Strongly RECOMMENDED to be specified for products of type `GRD`.", - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "type": "number", - "minimum": 0 - } - }, - "sar:looks": { - "description": "The number of groups of signal samples (looks). The first element of the array must be the number of range looks, the second element must be the number of azimuth looks, the optional third element is the equivalent number of looks (ENL).", + "links": { + "description": "Additional links related to this collection. Could reference to other meta data formats with additional information or a preview image.", "type": "array", - "minItems": 2, - "maxItems": 3, "items": { - "type": "number", - "minimum": 0 + "$ref": "#/components/schemas/link" } } } }, - "collection_sci": { - "title": "STAC Scientific", - "type": "object", - "properties": { - "sci:doi": { - "type": "string", - "description": "The DOI name of the collection, e.g. `10.1000/xyz123`. This MUST NOT be a DOIs link. For all DOI names respective DOI links SHOULD be added to the links section of the collection with relation type `cite-as`.", - "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" - }, - "sci:citation": { - "type": "string", - "description": "The recommended human-readable reference (citation) to be used by publications citing this collection. No specific citation style is suggested, but the citation should contain all information required to find the publication distinctively." - }, - "sci:publications": { - "type": "array", - "title": "STAC Scientific Publications", - "description": "A list of publications which describe and reference the collection.", - "items": { - "type": "object", - "properties": { - "doi": { - "type": "string", - "description": "The DOI name of a publication which describes and references the collection. The publications should include more information about the collection and how it was processed. This MUST NOT be a DOIs link. For all DOI names respective DOI links SHOULD be added to the links section of the collection with relation type `cite-as`.", - "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" - }, - "citation": { - "type": "string", - "description": "Human-readable reference (citation) of a publication which describes and references the collection. The publications should include more information about the collection and how it was processed. No specific citation style is suggested, but a citation should contain all information required to find the publication distinctively." - } - } - } - } - } + "stac_version": { + "type": "string", + "description": "The STAC version implemented.", + "enum": [ + "0.8.1" + ] }, - "collection_keywords": { + "stac_extensions": { "type": "array", - "description": "List of keywords describing the collection.", + "description": "A list of implemented STAC extensions. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a \"shortcut\" can be used. This means you can specify the folder name of the extension in the STAC repository, for example `sar` for the SAR extension. If the versions of the extension and the collection diverge, you can specify the URL of the JSON schema file.", + "uniqueItems": true, "items": { - "type": "string" + "anyOf": [ + { + "title": "Reference to a JSON Schema", + "type": "string", + "format": "uri", + "example": "https://www.example.com/stac/custom-extemsion/v1.0/schema.json" + }, + { + "title": "Reference to a core extension", + "type": "string", + "example": "eo" + } + ] } }, - "collection_version": { + "stac_license": { "type": "string", - "description": "Version of the collection." - }, - "collection_deprecated": { - "type": "boolean", - "description": "Specifies that the collection is deprecated with the potential to be removed in any of the next versions. It should be transitioned out of usage as soon as possible and users should refrain from using it in new implementations.\n\nA link with relation type `successor-version` SHOULD be added to the `links` and MUST refer to the collection that can be used instead.", - "default": false + "description": "License(s) of the data as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the `license` link relation type.\n\nNon-SPDX licenses SHOULD add a link to the license text with the `license` relation in the links section. The license text MUST NOT be provided as a value of this field. If there is no public license URL available, it is RECOMMENDED to host the license text and link to it.", + "example": "Apache-2.0" }, - "collection_providers": { + "stac_providers": { "type": "array", "description": "A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list.", "items": { + "type": "object", + "title": "Provider", "required": [ "name" ], @@ -4104,55 +3848,9 @@ } } }, - "collection_license": { - "type": "string", - "description": "Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60), or `proprietary` if the license is not on the SPDX license list. Proprietary licensed data SHOULD add a link to the license text with the `license` relation in the links section. The license text MUST NOT be provided as a value of this field. If there is no public license URL available, it is RECOMMENDED to host the license text independently and link to it.", - "example": "Apache-2.0" - }, - "collection_extent": { - "type": "object", - "title": "STAC Collection Extent", - "description": "The object describes the spatio-temporal extents of the Collection. Both spatial and temporal extents are required to be specified.", - "required": [ - "spatial", - "temporal" - ], - "properties": { - "spatial": { - "description": "Potential *spatial extent* covered by the collection. The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth):\n\n- West (lower left corner, coordinate axis 1)\n- South (lower left corner, coordinate axis 2)\n- Base (optional, lower left corner, coordinate axis 3)\n- East (upper right corner, coordinate axis 1)\n- North (upper right corner, coordinate axis 2)\n- Height (optional, upper right corner, coordinate axis 3)\n\nThe coordinate reference system of the values is WGS84 longitude/latitude.", - "type": "array", - "minItems": 4, - "maxItems": 6, - "items": { - "type": "number" - }, - "example": [ - -180, - -90, - 180, - 90 - ] - }, - "temporal": { - "type": "array", - "description": "Potential *temporal extent* covered by the collection. The temporal extent specified by a start and an end time, each formatted as a [RFC 3339](https://www.ietf.org/rfc/rfc3339) date-time. Open date ranges are supported and can be specified by setting one of the times to null. Setting both entries to null is not allowed. Only the Gregorian calendar is supported.", - "example": [ - "2016-01-01T00:00:00Z", - null - ], - "minItems": 2, - "maxItems": 2, - "items": { - "type": "string", - "format": "date-time", - "nullable": true - } - } - } - }, "collection_id": { "type": "string", - "description": "Identifier for the collection that is unique across the provider.\n\nMUST match the specified pattern.", + "description": "A unique identifier for the collection, which MUST match the specified pattern.", "pattern": "^[A-Za-z0-9_\\-\\.~\\/]+$", "example": "Sentinel-2A" }, @@ -4209,11 +3907,6 @@ } ] }, - "stac_version": { - "type": "string", - "description": "The STAC version the collection implements.", - "example": "0.6.2" - }, "variable": { "title": "Process Graph Variable", "description": "Process graphs can hold a variable, which can be filled in later. For shared process graphs this can be useful to make them more portable, e.g in case a back-end specific product name would be stored with the process graph.\n\nIf a process graph with a variable is about to be executed and neither a value nor a default value is specified, the back-end MUST reject the request with an error of type `VariableValueMissing`. The values are usually defined when loading the process graph with the `run_process_graph` process.\n\nInvalid variable types MUST be rejected with error `VariableTypeInvalid`. If the default value is not compatible to the specified type an `VariableDefaultValueTypeInvalid` error MUST be sent. Invalid variable ids MUST be rejected with error `VariableIdInvalid`. ", @@ -4809,18 +4502,6 @@ "description": "Detailed description to fully explain the entity.\n\n[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. In addition to the CommonMark syntax, clients can convert process IDs that are formatted as in the following example into links instead of code blocks: ``` ``process_id()`` ```", "type": "string" }, - "collection_title": { - "description": "A short descriptive one-line title for the collection.", - "type": "string" - }, - "collection_description": { - "description": "Detailed multi-line description to fully explain the collection.\n\n[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation.", - "type": "string" - }, - "collection_band_description": { - "description": "Description to fully explain the band, should include processing information.\n\n[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation.", - "type": "string" - }, "service_type": { "description": "Definition of the service type to access result data. All available service types can be retrieved via `GET /service_types`. Service types MUST be accepted *case insensitive*.", "type": "string", From 793ac4550b139da330b01e1285338da927e31950 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 25 Oct 2019 18:54:30 +0200 Subject: [PATCH 2/4] Fixed build --- tests/test_examples.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/test_examples.py b/tests/test_examples.py index 56bd7510..2fe2e9a7 100644 --- a/tests/test_examples.py +++ b/tests/test_examples.py @@ -81,7 +81,6 @@ def test_schema_example(api_spec, path, schema_with_example): """ if path[-1] == "properties": pytest.skip("This is probably not a schema example but an 'example' property") - assert "type" in schema_with_example assert "example" in schema_with_example example = schema_with_example['example'] OpenApiValidator(api_spec=api_spec, schema=schema_with_example).validate(example) From 5e4a0913712876363760d7f543a34c4129cd8b0d Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 29 Oct 2019 12:04:03 +0100 Subject: [PATCH 3/4] Added a Data Cube Dimension of type `bands` to the `cube:dimensions` property (#208), more clarifications and simplifications. --- CHANGELOG.md | 8 ++++--- openapi.json | 67 ++++++++++++++++++++++++++-------------------------- 2 files changed, 38 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e5039e9..6c12ba87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,16 +11,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `GET /`: - Field `production` added to response. [#184](https://github.com/Open-EO/openeo-api/issues/184) - Links with relation types `terms-of-service` and `privacy-policy` explicitly documented. Clients must handle them properly if present. [#212](https://github.com/Open-EO/openeo-api/issues/212) -- `GET /collections` and `GET /collections/{collectionId}`: New field `deprecated` can be used to indicate outdated collections. Links with relation type `successor-version` can point to a newer version. [#226]( https://github.com/Open-EO/openeo-api/issues/226) +- `GET /collections` and `GET /collections/{collectionId}`: + - New field `deprecated` can be used to indicate outdated collections. Links with relation type `successor-version` can point to a newer version. [#226]( https://github.com/Open-EO/openeo-api/issues/226) + - Added a Data Cube Dimension of type `bands` to the `cube:dimensions` property. [#208](https://github.com/Open-EO/openeo-api/issues/208) ### Changed - Unsupported endpoints are not forced to return a `FeatureUnsupported` (501) error and can return a simple `NotFound` (404) instead. - -- `GET /collections` and `GET /collections/{collectionId}`: Updated STAC to version 0.8.1 ([#185](https://github.com/Open-EO/openeo-api/issues/185), [#204](https://github.com/Open-EO/openeo-api/issues/204)) and removed optional STAC extensions from the API specification ([#176](https://github.com/Open-EO/openeo-api/issues/176)). - If `currency` returned by `GET /` is `null`, `costs` and `budget` are unsupported. `costs` and `budget` fields in various endpoints can be set to `null` (default). - The default type for Process Graph Variables is not `string`, but no specific (any) data type. Default values can be of any type. - Official support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html). [#203](https://github.com/Open-EO/openeo-api/issues/203) +- `GET /collections` and `GET /collections/{collectionId}`: Updated STAC to version 0.8.1. [#185](https://github.com/Open-EO/openeo-api/issues/185), [#204](https://github.com/Open-EO/openeo-api/issues/204). - `GET /credentials/oidc`: Changed response to support multiple OpenID Connect identity providers ([#201](https://github.com/Open-EO/openeo-api/issues/201)) and clarified workflow overall. - Bearer token are built from the authentication method, an optional provider id and the token itself. [#219](https://github.com/Open-EO/openeo-api/issues/219) - `GET /udf_runtimes`: `description` fields don't allow `null` values any longer. @@ -36,6 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Metalink XML encoding has been removed. [#205](https://github.com/Open-EO/openeo-api/issues/205) - `Expires` header has been removed, use `expires` property in the response body instead. - `GET /credentials/basic` doesn't return a `user_id`. Instead request it from `GET /me`. +- `GET /collections/{collectionId}`: Removed optional STAC extensions from the API specification. Inform yourself about useful [STAC extensions](https://github.com/radiantearth/stac-spec/tree/master/extensions#list-of-content-extensions) instead. [#176](https://github.com/Open-EO/openeo-api/issues/176) ### Fixed diff --git a/openapi.json b/openapi.json index 664ee167..0dc88a97 100644 --- a/openapi.json +++ b/openapi.json @@ -762,7 +762,7 @@ "x-additionalPropertiesName": "Dimension Name", "anyOf": [ { - "title": "Additional Dimension Object", + "title": "Additional Dimension", "description": "An additional dimension that is not `spatial`.", "type": "object", "required": [ @@ -782,27 +782,10 @@ ] } ], - "not": { - "required": [ - "axis" - ] - }, "properties": { "type": { - "description": "Custom type of the dimension, never `spatial`.", - "allOf": [ - { - "type": "string" - }, - { - "not": { - "type": "string", - "enum": [ - "spatial" - ] - } - } - ] + "description": "Custom type of the dimension, MUST NOT be `spatial`.", + "type": "string" }, "extent": { "$ref": "#/components/schemas/collection_dimension_extent_open" @@ -823,7 +806,28 @@ } }, { - "title": "Horizontal Spatial Dimension Object", + "title": "Band Dimension", + "description": "A dimension for the bands.\n\nThe band dimension only specifies the band names as dimension values. Further information to the bands are available in either `sar:bands` or `eo:bands` in the `summaries` property.", + "type": "object", + "required": [ + "type", + "values" + ], + "properties": { + "type": { + "description": "Type of the dimension, always `bands`.", + "type": "string", + "enum": [ + "bands" + ] + }, + "values": { + "$ref": "#/components/schemas/collection_dimension_values" + } + } + }, + { + "title": "Horizontal Spatial Dimension", "description": "A spatial dimension in one of the horizontal (x or y) directions.", "type": "object", "required": [ @@ -869,7 +873,7 @@ } }, { - "title": "Vertical Spatial Dimension Object", + "title": "Vertical Spatial Dimension", "description": "A spatial dimension in vertical (z) direction.", "type": "object", "required": [ @@ -919,18 +923,13 @@ } }, { - "title": "Temporal Dimension Object", + "title": "Temporal Dimension", "description": "A temporal dimension based on the ISO 8601 standard. The temporal reference system for the data is expected to be ISO 8601 compliant (Gregorian calendar / UTC). Data not compliant with ISO 8601 can be represented as an *Additional Dimension Object* with `type` set to `temporal`.", "type": "object", "required": [ "type", "extent" ], - "not": { - "required": [ - "axis" - ] - }, "properties": { "type": { "description": "Type of the dimension, always `temporal`.", @@ -3030,7 +3029,7 @@ ], "get": { "summary": "Download results for a completed batch job", - "description": "After finishing processing, this request will provide signed URLs to the processed files of the batch job with some additional metadata. The response is a [STAC Item (version 0.6.2)](https://github.com/radiantearth/stac-spec/tree/master/item-spec) if it has spatial and temporal references.\n\nURL signing is a way to protect files from unauthorized access with a key in the URL instead of HTTP header based authorization. The URL signing key is similar to a password and its inclusion in the URL allows to download files using simple GET requests supported by a wide range of programs, e.g. web browsers or download managers. Back-ends are responsible to generate the URL signing keys and to manage their appropriate expiration. The back-end MAY indicate an expiration time by setting the `expires` property.\n\nIf processing has not finished yet requests to this endpoint MUST be rejected with openEO error `JobNotFinished`.", + "description": "After finishing processing, this request will provide signed URLs to the processed files of the batch job with some additional metadata. The response is a [STAC Item (version 0.8.1)](https://github.com/radiantearth/stac-spec/tree/master/item-spec) if it has spatial and temporal references included.\n\nURL signing is a way to protect files from unauthorized access with a key in the URL instead of HTTP header based authorization. The URL signing key is similar to a password and its inclusion in the URL allows to download files using simple GET requests supported by a wide range of programs, e.g. web browsers or download managers. Back-ends are responsible to generate the URL signing keys and to manage their appropriate expiration. The back-end MAY indicate an expiration time by setting the `expires` property.\n\nIf processing has not finished yet requests to this endpoint MUST be rejected with openEO error `JobNotFinished`.", "tags": [ "Batch Job Management" ], @@ -3574,7 +3573,7 @@ "properties": { "datetime": { "title": "Date and Time", - "description": "The searchable date/time of the data, in UTC. Formatted as a [RFC 3339](https://www.ietf.org/rfc/rfc3339) date-time. For timeseries: The center date and time for the data.\n\nIt is NOT RECOMMENDED to set this field to `null` as this field is required in a STAC Item.", + "description": "The searchable date/time of the data, in UTC. Formatted as a [RFC 3339](https://www.ietf.org/rfc/rfc3339) date-time. For timeseries: The center date and time for the data.\n\nIt is NOT RECOMMENDED to set this field to `null` as this field is required for the answer to be a valid STAC Item.", "type": "string", "format": "date-time", "nullable": true @@ -3609,7 +3608,7 @@ "assets": { "type": "object", "title": "Item Assets", - "description": "Dictionary of asset objects that can be downloaded, each with a unique key.", + "description": "Dictionary of asset objects that can be downloaded, each with a unique key. The keys MAY be used by clients as file names.", "additionalProperties": { "type": "object", "required": [ @@ -3631,11 +3630,11 @@ } }, "example": { - "1": { + "1.tif": { "href": "https://openeo.org/api/download/583fba8b2ce583fba8b2ce/1.tif", "type": "image/tiff; application=geotiff" }, - "2": { + "2.tif": { "href": "https://openeo.org/api/download/583fba8b2ce583fba8b2ce/2.tif", "type": "image/tiff; application=geotiff" } @@ -3643,7 +3642,7 @@ }, "links": { "type": "array", - "description": "List of related URLs. This MUST NOT be the processed and downloadable data, specify it in the `assets` property instead.", + "description": "List of related URLs. This MUST NOT be the processed and downloadable data, specify it in the `assets` property instead. Clients MUST NOT download the data referenced in the links by default.", "items": { "$ref": "#/components/schemas/link" } From 831cc2784fa73234e16a6d0fdac6f3ad221ecbef Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 29 Oct 2019 12:18:16 +0100 Subject: [PATCH 4/4] Added a recommendation for dimension names. #208 --- openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.json b/openapi.json index 0dc88a97..c7bb9688 100644 --- a/openapi.json +++ b/openapi.json @@ -756,7 +756,7 @@ "properties": { "cube:dimensions": { "title": "STAC Collection Cube Dimensions", - "description": "Uniquely named dimensions of the data cube.", + "description": "Uniquely named dimensions of the data cube.\n\nThe keys of the object are the dimension names. For interoperability, it is RECOMMENDED to use the following dimension names if there is only a single dimension with the specified criteria:\n* `x` for the dimension of type `spatial` with the axis set to `x`\n* `y` for the dimension of type `spatial` with the axis set to `y`\n* `z` for the dimension of type `spatial` with the axis set to `z`\n* `temporal` for the dimension of type `temporal`\n* `spectral` for the dimension of type `bands` if the data IS multi-spectral\n* `bands` for dimensions of type `bands` if the data IS NOT multi-spectral.", "type": "object", "additionalProperties": { "x-additionalPropertiesName": "Dimension Name",