diff --git a/CHANGELOG.md b/CHANGELOG.md index ffcef205..b648b378 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Recommendation to add media types and titles to links for a better user experience. - Allow the relation type `canonical` to be used generally for (shared) resources (e.g. UDPs or batch jobs) without requiring Bearer authentication. [#405](https://github.com/Open-EO/openeo-api/issues/405) - Recommendation for UDF runtime names. [#409](https://github.com/Open-EO/openeo-api/issues/409) +- Processes: Added `dimensions` schema for subtype `datacube` +- Collections: Added `vector` dimension type to `cube:dimensions` ### Changed @@ -50,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Clarify the fields `plan` (for processing requests) and `billing_plan` (in `GET /` and `GET /me`). [#425](https://github.com/Open-EO/openeo-api/issues/425) [#426](https://github.com/Open-EO/openeo-api/issues/426) - Reflect that the `debug` process has been renamed to `inspect`. - Clarified uniqueness constraints for identifiers. [#449](https://github.com/Open-EO/openeo-api/issues/449) [#454](https://github.com/Open-EO/openeo-api/issues/454) +- Clarified schematically the applicability of JSON Schema extensions (`parameters`, `returns`, `dimensions`) and their relation to the subtypes - `GET /`: Removed the superfluous default value for `currency`. [#423](https://github.com/Open-EO/openeo-api/issues/423) - `GET /credentials/oidc`: Clarify that clients may add additional scopes - `GET /me`: Clarify the behavior of the field `budget`. diff --git a/openapi.yaml b/openapi.yaml index 6d4037a4..f8bad098 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -267,10 +267,11 @@ info: Each process parameter and the return values of a process define a schema that the value MUST comply to. The schemas are based on [JSON Schema draft-07](http://json-schema.org/). - Three custom keywords have been defined: + Multiple custom keywords have been defined: * `subtype` for more fine-grained data-types than JSON Schema supports. - * `parameters` to specify the parameters of a process graph (object with subtype `process-graph`). - * `returns` to describe the return value of a process graph (object with subtype `process-graph`). + * `dimensions` to further define the dimension types required if the `subtype` is `datacube`. + * `parameters` to specify the parameters of a process graph if the `subtype` is `process-graph`. + * `returns` to describe the return value of a process graph if the `subtype` is `process-graph`. ### Subtypes @@ -280,7 +281,7 @@ info: and standardizes a number of openEO related data types that extend the native data types, for example: `bounding-box` (object with at least `west`, `south`, `east` and `north` properties), `date-time` (string representation of date and time following RFC 3339), - `raster-cube` (the type of data cubes), etc. + `datacube` (a datacube with dimensions), etc. The subtypes should be re-used in process schema definitions whenever suitable. If a general data type such as `string` or `number` is used in a schema, all subtypes with the same parent data type can be passed, too. @@ -1394,7 +1395,7 @@ paths: example: stac_version: 1.0.0 stac_extensions: - - https://stac-extensions.github.io/datacube/v2.0.0/schema.json + - https://stac-extensions.github.io/datacube/v2.2.0/schema.json type: Collection id: Sentinel-2 title: Sentinel-2 MSI L2A @@ -1627,7 +1628,7 @@ paths: description: A data cube. schema: type: object - subtype: raster-cube + subtype: datacube - name: process description: 'A unary process to be applied on each value, may consist of multiple sub-processes.' schema: @@ -1642,7 +1643,7 @@ paths: description: 'A data cube with the newly computed values. The resolution, cardinality and the number of dimensions are the same as for the original data cube.' schema: type: object - subtype: raster-cube + subtype: datacube - id: multiply summary: Multiplication of two numbers description: |- @@ -2471,7 +2472,7 @@ paths: description: List of parameters made available to user-defined processes. type: array items: - $ref: '#/components/schemas/parameter' + $ref: '#/components/schemas/process_parameter' links: description: |- Links related to this service type, e.g. more @@ -3809,6 +3810,12 @@ components: default: finished batch_job_result: title: Batch Job Results Response as STAC Item + description: + The STAC specification should be the main guidance for implementing this. + + Specifying the `bbox` is strongly RECOMMENDED for STAC compliance, + but can be omitted if the result is unlocated and the `geometry` + is set to `null`. type: object required: - stac_version @@ -3835,41 +3842,7 @@ components: enum: - Feature bbox: - description: |- - Potential *spatial extent* covered by the data. - - The bounding box is provided as four or six numbers. Six numbers are - specified, if the coordinate reference system includes a vertical axis - (height or depth). The order of the elements in the array: - - - West (lower left corner, coordinate axis 1) - - South (lower left corner, coordinate axis 2) - - Base (optional, lower left corner, coordinate axis 3) - - East (upper right corner, coordinate axis 1) - - North (upper right corner, coordinate axis 2) - - Height (optional, upper right corner, coordinate axis 3) - - The coordinate reference system of the values is WGS84 - longitude/latitude. - - Specifying the `bbox` is strongly RECOMMENDED for STAC compliance, - but can be omitted if the result is unlocated and the `geometry` - is set to `null`. - type: array - oneOf: - - title: 4 elements - minItems: 4 - maxItems: 4 - - title: 6 elements - minItems: 6 - maxItems: 6 - items: - type: number - example: - - -180 - - -90 - - 180 - - 90 + $ref: '#/components/schemas/bbox' geometry: description: |- Defines the full footprint of the asset represented by this item as @@ -4316,46 +4289,7 @@ components: type: array minItems: 1 items: - description: |- - Each bounding box is provided as four or six numbers, - depending on whether the coordinate reference system - includes a vertical axis (height or depth): - - * West (lower left corner, coordinate axis 1) - * South (lower left corner, coordinate axis 2) - * Base (optional, minimum value, coordinate axis 3) - * East (upper right corner, coordinate axis 1) - * North (upper right corner, coordinate axis 2) - * Height (optional, maximum value, coordinate axis 3) - - The coordinate reference system of the values is WGS 84 - longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84). - - For WGS 84 longitude/latitude the values are in most cases - the sequence of minimum longitude, minimum latitude, maximum - longitude and maximum latitude. - - However, in cases where the box spans the antimeridian the - first value (west-most box edge) is larger than the third value - (east-most box edge). - - If the vertical axis is included, the third and the sixth - number are the bottom and the top of the 3-dimensional bounding box. - type: array - oneOf: - - title: 4 elements - minItems: 4 - maxItems: 4 - - title: 6 elements - minItems: 6 - maxItems: 6 - items: - type: number - example: - - -180 - - -90 - - 180 - - 90 + $ref: '#/components/schemas/bbox' temporal: title: Collection Temporal Extent description: >- @@ -4440,9 +4374,10 @@ components: * `z` for the dimension of type `spatial` with the axis set to `z` * `t` for the dimension of type `temporal` * `bands` for dimensions of type `bands` + * `geometries` for dimensions of type `geometries` - This property REQUIRES to add the data cube extension to the list - of `stac_extensions`: `https://stac-extensions.github.io/datacube/v2.1.0/schema.json`. + This property REQUIRES to add a version of the data cube extension to the list + of `stac_extensions`, e.g. `https://stac-extensions.github.io/datacube/v2.2.0/schema.json`. type: object additionalProperties: x-additionalPropertiesName: Dimension Name @@ -4669,6 +4604,47 @@ components: anyOf: - type: string - type: number + bbox: + description: |- + Each bounding box is provided as four or six numbers, + depending on whether the coordinate reference system + includes a vertical axis (height or depth): + + * West (lower left corner, coordinate axis 1) + * South (lower left corner, coordinate axis 2) + * Base (optional, minimum value, coordinate axis 3) + * East (upper right corner, coordinate axis 1) + * North (upper right corner, coordinate axis 2) + * Height (optional, maximum value, coordinate axis 3) + + The coordinate reference system of the values is WGS 84 + longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84). + + For WGS 84 longitude/latitude the values are in most cases + the sequence of minimum longitude, minimum latitude, maximum + longitude and maximum latitude. + + However, in cases where the box spans the antimeridian the + first value (west-most box edge) is larger than the third value + (east-most box edge). + + If the vertical axis is included, the third and the sixth + number are the bottom and the top of the 3-dimensional bounding box. + type: array + oneOf: + - title: 4 elements + minItems: 4 + maxItems: 4 + - title: 6 elements + minItems: 6 + maxItems: 6 + items: + type: number + example: + - -180 + - -90 + - 180 + - 90 collection_id: type: string description: >- @@ -4678,17 +4654,19 @@ components: example: Sentinel-2A dimension: title: Dimension + description: A dimension, each object represents a distinct dimension with the key being the dimension name. type: object required: - type properties: type: - description: 'Type of the dimension.' + description: Type of the dimension. type: string enum: - spatial - temporal - bands + - geometries - other description: $ref: '#/components/schemas/description' @@ -4698,12 +4676,21 @@ components: spatial: '#/components/schemas/dimension_spatial' temporal: '#/components/schemas/dimension_temporal' bands: '#/components/schemas/dimension_bands' + geometries: '#/components/schemas/dimension_geometries' other: '#/components/schemas/dimension_other' dimension_other: allOf: - $ref: '#/components/schemas/dimension' - title: Additional Dimension type: object +# This is not supported by ReDoc yet: +# oneOf: +# - title: Additional Dimension with Extent +# required: +# - extent +# - title: Additional Dimension with Values +# required: +# - values properties: extent: $ref: '#/components/schemas/collection_dimension_extent_open' @@ -4714,8 +4701,40 @@ components: unit: $ref: '#/components/schemas/collection_dimension_unit' reference_system: - description: The reference system for the data. + description: The reference system for the dimension. type: string + dimension_geometries: + allOf: + - $ref: '#/components/schemas/dimension' + - title: Geometries Dimension + type: object + required: + - bbox + properties: + axes: + description: Axes of the vector dimension as an ordered set of `x`, `y` and `z`. Defaults to `x` and `y`. + default: + - 'x' + - 'y' + type: array + uniqueItems: true + items: + $ref: '#/components/schemas/dimension_axis_xyz' + bbox: + $ref: '#/components/schemas/bbox' + values: + description: Optionally, a representation of the vectors. This can be a list of WKT string or other free-form identifiers. + type: array + items: + type: string + geometry_types: + description: A set of all geometry types included in this dimension. If not present, mixed geometry types must be assumed. + type: array + uniqueItems: true + items: + $ref: '#/components/schemas/geometry_type' + reference_system: + $ref: '#/components/schemas/collection_dimension_srs' dimension_bands: allOf: - $ref: '#/components/schemas/dimension' @@ -4737,18 +4756,13 @@ components: allOf: - $ref: '#/components/schemas/dimension' - title: Spatial Dimension - description: A spatial dimension in one of the horizontal (x or y) or vertical (z) directions. + description: A spatial (raster) dimension in one of the horizontal (x or y) or vertical (z) directions. type: object required: - axis properties: axis: - description: 'Axis of the spatial dimension (`x`, `y` or `z`).' - type: string - enum: - - 'x' - - 'y' - - 'z' + $ref: '#/components/schemas/dimension_axis_xyz' extent: description: >- Extent (lower and upper bounds) of the @@ -4768,22 +4782,21 @@ components: step: $ref: '#/components/schemas/collection_dimension_step' reference_system: - description: >- - The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON object](https://proj.org/specifications/projjson.html) or [PROJ definition (deprecated)](https://proj.org/usage/quickstart.html). Defaults to EPSG code 4326. - default: 4326 - oneOf: - - type: number - title: EPSG code - - type: string - title: WKT2 or PROJ definition (deprecated) - - type: object - title: PROJJSON + $ref: '#/components/schemas/collection_dimension_srs' discriminator: propertyName: axis mapping: x: '#/components/schemas/dimension_spatial_horizontal' y: '#/components/schemas/dimension_spatial_horizontal' z: '#/components/schemas/dimension_spatial_vertical' + dimension_axis_xyz: + title: Axis + description: Axis of a geometry or dimension (`x`, `y` or `z`) + type: string + enum: + - 'x' + - 'y' + - 'z' dimension_spatial_horizontal: allOf: - $ref: '#/components/schemas/dimension_spatial' @@ -4851,6 +4864,18 @@ components: spaced steps. type: string nullable: true + collection_dimension_srs: + title: Spatial reference system + description: >- + The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON object](https://proj.org/specifications/projjson.html) or [PROJ definition (deprecated)](https://proj.org/usage/quickstart.html). Defaults to EPSG code 4326. + default: 4326 + oneOf: + - type: number + title: EPSG code + - type: string + title: WKT2 or PROJ definition (deprecated) + - type: object + title: PROJJSON collection_dimension_extent_open: description: >- If the dimension consists of @@ -5251,7 +5276,7 @@ components: description: $ref: '#/components/schemas/process_description' schema: - $ref: '#/components/schemas/data_type_schema' + $ref: '#/components/schemas/process_schema' experimental: type: boolean description: >- @@ -5388,7 +5413,7 @@ components: - schema properties: schema: - $ref: '#/components/schemas/parameter_schema' + $ref: '#/components/schemas/process_schema' allOf: - $ref: '#/components/schemas/base_parameter' batch_job: @@ -5810,22 +5835,57 @@ components: uniqueItems: true items: $ref: '#/components/schemas/process_json_schema' - parameter_schema: - title: Parameter Data Types - description: Either a single data type or a list of data types. + process_schema: + title: Process Data types + description: Either a single data type or a list of data types for process parameter or process return values. oneOf: - - $ref: '#/components/schemas/parameter_json_schema' + - $ref: '#/components/schemas/process_json_schema' - title: Multiple data types description: A list of data types supported, specified as JSON Schemas. type: array minItems: 1 uniqueItems: true items: - $ref: '#/components/schemas/parameter_json_schema' - parameter_json_schema: + $ref: '#/components/schemas/process_json_schema' + process_json_schema: + type: object title: Single Data Type + description: |- + Specifies a data type supported by a parameter or return value. + + The data types are specified according to the [JSON Schema draft-07](http://json-schema.org/) specification. + See the chapter ['Schemas' in 'Defining Processes'](#section/Processes/Defining-Processes) for more information. + + JSON Schemas SHOULD NOT contain `default`, `anyOf`, `oneOf`, `allOf` or `not` at the top-level of the schema. + Instead specify each data type in a separate array element. + + The following more complex JSON Schema keywords SHOULD NOT be used: + `if`, `then`, `else`, `readOnly`, `writeOnly`, `dependencies`, `minProperties`, `maxProperties`, `patternProperties`. + + JSON Schemas SHOULD always be dereferenced (i.e. all `$refs` should be resolved). This allows clients to consume the schemas much better. + Clients are not expected to support dereferencing `$refs`. + + Note: The specified schema is only a common subset of JSON Schema. Additional keywords MAY be used. + properties: + subtype: + type: string + description: The allowed sub data type for a value. See the chapter on [subtypes](#section/Processes/Defining-Processes) for more information. + deprecated: + $ref: '#/components/schemas/deprecated' + allOf: + - $ref: '#/components/schemas/json_schema' + oneOf: + - title: Generic + - $ref: '#/components/schemas/process_graph_json_schema' + - $ref: '#/components/schemas/datacube_json_schema' + process_graph_json_schema: + title: Process Graph type: object properties: + subtype: + type: string + enum: + - process-graph parameters: type: array title: Process Graph Parameters @@ -5839,7 +5899,8 @@ components: returns: type: object title: Process Graph Return Value - description: Description of the data that is returned by the child process graph. + description: |- + Description of the data that is returned by the child process graph. required: - schema properties: @@ -5849,35 +5910,57 @@ components: $ref: '#/components/schemas/data_type_schema' allOf: - $ref: '#/components/schemas/process_json_schema' - allOf: - - $ref: '#/components/schemas/process_json_schema' - process_json_schema: - type: object - title: Single data type - description: |- - Specifies a data type supported by a parameter or return value. - - The data types are specified according to the [JSON Schema draft-07](http://json-schema.org/) specification. - See the chapter ['Schemas' in 'Defining Processes'](#section/Processes/Defining-Processes) for more information. - - JSON Schemas SHOULD NOT contain `default`, `anyOf`, `oneOf`, `allOf` or `not` at the top-level of the schema. - Instead specify each data type in a separate array element. - - The following more complex JSON Schema keywords SHOULD NOT be used: - `if`, `then`, `else`, `readOnly`, `writeOnly`, `dependencies`, `minProperties`, `maxProperties`, `patternProperties`. - - JSON Schemas SHOULD always be dereferenced (i.e. all `$refs` should be resolved). This allows clients to consume the schemas much better. - Clients are not expected to support dereferencing `$refs`. - - Note: The specified schema is only a common subset of JSON Schema. Additional keywords MAY be used. - allOf: - - $ref: '#/components/schemas/json_schema' - - properties: - subtype: - type: string - description: The allowed sub data type for a value. See the chapter on [subtypes](#section/Processes/Defining-Processes) for more information. - deprecated: - $ref: '#/components/schemas/deprecated' + datacube_json_schema: + title: Datacube + properties: + subtype: + type: string + enum: + - datacube + dimensions: + title: Datacube constraints + description: |- + Allows to specify requirements the data cube has to fulfill. + Right now, it only allows to specify the dimension types and + adds for specific dimension types: + * axes for `spatial` dimensions in raster datacubes + * geometry types for `geometries` dimensions in vector datacubes + type: array + items: + type: object + required: + - type + oneOf: + - title: Spatial (raster) + properties: + type: + type: string + enum: + - spatial + axis: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/dimension_axis_xyz' + - title: Spatial (vector) + properties: + type: + type: string + enum: + - geometries + geometry_type: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/geometry_type' + - title: Other + properties: + type: + type: string + enum: + - bands + - temporal + - other json_schema: type: object title: JSON Schema @@ -5976,6 +6059,17 @@ components: Date and time the file has lastly been modified, formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. example: '2018-01-03T10:55:29Z' + geometry_type: + title: Geometry type + type: string + enum: + - Point + - MultiPoint + - LineString + - MultiLineString + - Polygon + - MultiPolygon + - GeometryCollection GeoJsonPoint3D: type: array description: Point in 3D space @@ -5996,22 +6090,50 @@ components: - Point coordinates: $ref: '#/components/schemas/GeoJsonPoint3D' - GeoJsonGeometry: - title: GeoJSON Geometry + GeoJsonFeatureCollection: type: object required: - type + - features properties: type: type: string enum: - - Point - - LineString - - Polygon - - MultiPoint - - MultiLineString - - MultiPolygon - - GeometryCollection + - FeatureCollection + features: + type: array + items: + $ref: '#/components/schemas/GeoJsonFeature' + GeoJsonFeature: + type: object + required: + - type + - geometry + - properties + properties: + type: + type: string + enum: + - Feature + geometry: + $ref: '#/components/schemas/GeoJsonGeometry' + properties: + type: object + nullable: true + GeoJson: + title: GeoJSON + oneOf: + - $ref: '#/components/schemas/GeoJsonFeatureCollection' + - $ref: '#/components/schemas/GeoJsonFeature' + - $ref: '#/components/schemas/GeoJsonGeometry' + GeoJsonGeometry: + title: GeoJSON Geometry + type: object + required: + - type + properties: + type: + $ref: '#/components/schemas/geometry_type' discriminator: propertyName: type mapping: @@ -6146,7 +6268,7 @@ components: Data of any type. It is the back-ends task to decide how to best present passed data to a user. - For example, a raster-cube passed to the `inspect` SHOULD return the + For example, a datacube passed to the `inspect` SHOULD return the metadata similar to the collection metadata, including `cube:dimensions`. There are implementation guidelines available for the `inspect` process. path: