From 248fce513e83be6f803fce585100c292239862da Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 19 Dec 2024 17:04:23 +0100 Subject: [PATCH] update JSON schema definitions and descriptions for compliance with openeo-test-suite --- titiler/openeo/models.py | 6 +- titiler/openeo/processes/data/arcosh.json | 14 ++-- .../openeo/processes/data/array_element.json | 75 ++++++++++++++++- titiler/openeo/processes/data/cosh.json | 11 +-- titiler/openeo/processes/data/ndvi.json | 80 ++++++++++++++++--- 5 files changed, 159 insertions(+), 27 deletions(-) diff --git a/titiler/openeo/models.py b/titiler/openeo/models.py index c35f249..0a9d561 100644 --- a/titiler/openeo/models.py +++ b/titiler/openeo/models.py @@ -282,7 +282,7 @@ class JsonSchema(BaseModel, extra="allow"): """ field_schema: Optional[AnyUrl] = Field( - AnyUrl("http://json-schema.org/draft-07/schema#"), + None, alias="$schema", json_schema_extra={ "description": "The JSON Schema version. If not given in the context of openEO,\ndefaults to `draft-07`.\n\nYou may need to add the default value for `$schema` property explicitly to the JSON Schema\nobject before passing it to a JSON Schema validator." @@ -319,7 +319,7 @@ class JsonSchema(BaseModel, extra="allow"): }, ) minItems: Optional[float] = Field( - 0, + None, ge=0.0, json_schema_extra={ "description": "The minimum number of items required in an array." @@ -553,7 +553,7 @@ class BaseParameter(BaseModel): }, ) optional: Optional[bool] = Field( - False, + None, json_schema_extra={ "description": "Determines whether this parameter is optional to be specified even when no default is specified.\nClients SHOULD automatically set this parameter to `true`, if a default value is specified. Back-ends SHOULD NOT fail, if a default value is specified and this flag is missing." }, diff --git a/titiler/openeo/processes/data/arcosh.json b/titiler/openeo/processes/data/arcosh.json index 6ed581f..9222a12 100644 --- a/titiler/openeo/processes/data/arcosh.json +++ b/titiler/openeo/processes/data/arcosh.json @@ -1,29 +1,31 @@ { "id": "arcosh", "summary": "Inverse hyperbolic cosine", - "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the inverse hyperbolic cosine of `x`. It is the inverse function of the hyperbolic cosine so that *`arcosh(cosh(x)) = x`*.\n\nNo-data values are passed through. `NaN` is returned for values outside of the allowed range.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "A number.", + "description": "A number in the range *[1, +∞)*.", "schema": { "type": [ "number", "null" ] - } + }, + "minimum": 1 } ], "returns": { - "description": "The computed angle in radians.", + "description": "The computed hyperbolic angle in radians in the range *[0, +∞)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": 0 } }, "examples": [ @@ -41,4 +43,4 @@ "title": "Inverse hyperbolic cosine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/titiler/openeo/processes/data/array_element.json b/titiler/openeo/processes/data/array_element.json index a50c97c..48f5b7a 100644 --- a/titiler/openeo/processes/data/array_element.json +++ b/titiler/openeo/processes/data/array_element.json @@ -23,7 +23,30 @@ "schema": { "type": "integer", "minimum": 0 - } + }, + "optional": true + }, + { + "name": "label", + "description": "The label of the element to retrieve. Throws an `ArrayNotLabeled` exception, if the given array is not a labeled array and this parameter is set.", + "schema": [ + { + "type": "number" + }, + { + "type": "string" + } + ], + "optional": true + }, + { + "name": "return_nodata", + "description": "By default this process throws an `ArrayElementNotAvailable` exception if the index or label is invalid. If you want to return `null` instead, set this flag to `true`.", + "schema": { + "type": "boolean" + }, + "default": false, + "optional": true } ], "returns": { @@ -32,6 +55,52 @@ "description": "Any data type is allowed." } }, - "exceptions": {}, - "examples": [] + "exceptions": { + "ArrayElementNotAvailable": { + "message": "The array has no element with the specified index or label." + }, + "ArrayElementParameterMissing": { + "message": "The process `array_element` requires either the `index` or `labels` parameter to be set." + }, + "ArrayElementParameterConflict": { + "message": "The process `array_element` only allows that either the `index` or the `labels` parameter is set." + }, + "ArrayNotLabeled": { + "message": "The array is not a labeled array, but the `label` parameter is set. Use the `index` instead." + } + }, + "examples": [ + { + "arguments": { + "data": [ + 9, + 8, + 7, + 6, + 5 + ], + "index": 2 + }, + "returns": 7 + }, + { + "arguments": { + "data": [ + "A", + "B", + "C" + ], + "index": 0 + }, + "returns": "A" + }, + { + "arguments": { + "data": [], + "index": 0, + "return_nodata": true + }, + "returns": null + } + ] } diff --git a/titiler/openeo/processes/data/cosh.json b/titiler/openeo/processes/data/cosh.json index 975958a..64fbd88 100644 --- a/titiler/openeo/processes/data/cosh.json +++ b/titiler/openeo/processes/data/cosh.json @@ -1,14 +1,14 @@ { "id": "cosh", "summary": "Hyperbolic cosine", - "description": "Computes the hyperbolic cosine of `x`.\n\nWorks on radians only.\nThe no-data value `null` is passed through and therefore gets propagated.", + "description": "Computes the hyperbolic cosine of `x`.\n\nNo-data values are passed through.", "categories": [ "math > trigonometric" ], "parameters": [ { "name": "x", - "description": "An angle in radians.", + "description": "An hyperbolic angle in radians.", "schema": { "type": [ "number", @@ -18,12 +18,13 @@ } ], "returns": { - "description": "The computed hyperbolic cosine of `x`.", + "description": "The computed hyperbolic cosine in the range *[1, +∞)*.", "schema": { "type": [ "number", "null" - ] + ], + "minimum": 1 } }, "examples": [ @@ -41,4 +42,4 @@ "title": "Hyperbolic cosine explained by Wolfram MathWorld" } ] -} \ No newline at end of file +} diff --git a/titiler/openeo/processes/data/ndvi.json b/titiler/openeo/processes/data/ndvi.json index 9cf4fbe..5bb952d 100644 --- a/titiler/openeo/processes/data/ndvi.json +++ b/titiler/openeo/processes/data/ndvi.json @@ -10,35 +10,90 @@ "parameters": [ { "name": "data", - "description": "A raster data cube.", + "description": "A raster data cube with two bands that have the common names `red` and `nir` assigned.", "schema": { "type": "object", - "subtype": "imagedata" + "subtype": "datacube", + "dimensions": [ + { + "type": "spatial", + "axis": [ + "x", + "y" + ] + }, + { + "type": "bands" + } + ] } }, { "name": "nir", - "description": "The index of the NIR band.", + "description": "The name of the NIR band. Defaults to the band that has the common name `nir` assigned.\n\nEither the unique band name (metadata field `name` in bands) or one of the common band names (metadata field `common_name` in bands) can be specified. If the unique band name and the common name conflict, the unique band name has a higher priority.", "schema": { - "type": "number" - } + "type": "string", + "subtype": "band-name" + }, + "default": "nir", + "optional": true }, { "name": "red", - "description": "The index of the Red band", + "description": "The name of the red band. Defaults to the band that has the common name `red` assigned.\n\nEither the unique band name (metadata field `name` in bands) or one of the common band names (metadata field `common_name` in bands) can be specified. If the unique band name and the common name conflict, the unique band name has a higher priority.", "schema": { - "type": "number" - } + "type": "string", + "subtype": "band-name" + }, + "default": "red", + "optional": true + }, + { + "name": "target_band", + "description": "By default, the dimension of type `bands` is dropped. To keep the dimension specify a new band name in this parameter so that a new dimension label with the specified name will be added for the computed values.", + "schema": [ + { + "type": "string", + "pattern": "^\\w+$" + }, + { + "type": "null" + } + ], + "default": null, + "optional": true } ], "returns": { "description": "A raster data cube containing the computed NDVI values. The structure of the data cube differs depending on the value passed to `target_band`:\n\n* `target_band` is `null`: The data cube does not contain the dimension of type `bands`, the number of dimensions decreases by one. The dimension properties (name, type, labels, reference system and resolution) for all other dimensions remain unchanged.\n* `target_band` is a string: The data cube keeps the same dimensions. The dimension properties remain unchanged, but the number of dimension labels for the dimension of type `bands` increases by one. The additional label is named as specified in `target_band`.", "schema": { "type": "object", - "subtype": "imagedata" + "subtype": "datacube", + "dimensions": [ + { + "type": "spatial", + "axis": [ + "x", + "y" + ] + } + ] + } + }, + "exceptions": { + "NirBandAmbiguous": { + "message": "The NIR band can't be resolved, please specify the specific NIR band name." + }, + "RedBandAmbiguous": { + "message": "The red band can't be resolved, please specify the specific red band name." + }, + "DimensionAmbiguous": { + "message": "dimension of type `bands` is not available or is ambiguous.." + }, + "BandExists": { + "message": "A band with the specified target name exists." } }, - "exceptions": {}, "links": [ { "rel": "about", @@ -49,6 +104,11 @@ "rel": "about", "href": "https://earthobservatory.nasa.gov/features/MeasuringVegetation/measuring_vegetation_2.php", "title": "NDVI explained by NASA" + }, + { + "rel": "about", + "href": "https://github.com/radiantearth/stac-spec/tree/master/extensions/eo#common-band-names", + "title": "List of common band names as specified by the STAC specification" } ] }