From da2eefee834f7e56165331c65440e6e90f2bac29 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 18 Dec 2024 18:17:38 +0100 Subject: [PATCH] Add UDP extension --- extensions/processing-parameters/README.md | 45 +++++++++++++++++++ extensions/processing-parameters/openapi.yaml | 8 ++-- 2 files changed, 50 insertions(+), 3 deletions(-) diff --git a/extensions/processing-parameters/README.md b/extensions/processing-parameters/README.md index 68acc6af..ca18becd 100644 --- a/extensions/processing-parameters/README.md +++ b/extensions/processing-parameters/README.md @@ -9,3 +9,48 @@ The Processing Parameters Extension to the openEO API provides an interface to e **Note:** This document only documents the additions to the specification. Extensions can not change or break existing behavior of the openEO API. + +This extension adds a new endpoint (`GET /processing_options`, see [OpenAPI document](openapi.yaml)) +to discover the additional processing options that a back-end offers. + +Additionally, this extension allows to provide specific default values for user-defined processes (UDPs, see below). + +In both cases, the parameters and its values are provided separately for each processing mode. + +## Processing Parameters in UDPs + +UDPs can provide default values for specific processing parameters. + +The values for each parameter are provided separately for each processing mode. +The following properties are added to the top-level of a UDP for the respective processing modes: + +- `default_synchronous_parameters` for synchronous processing +- `default_job_parameters` for batch jobs +- `default_service_parameters` for secondary web services + +The schema for each of these properties is: + +```yaml +type: object +additionalProperties: + description: Any type +``` + +The keys of the object are the respecive parameter names. +The values of the object are the (default) values for the parameters. +Schematic restrictions are not defined for the object, but the schemas for the parameters as defined in `GET /processing_options` apply to the given values. +These values provide the defaults unless a user overrides them in the actual data processing request (e.g. `POST /jobs`, see below). + +## Resolving parameters + +Due to the variety of places where processing parameters can be provided, the following +list defines how the parameters must be resolved. The prioritization is as follows: + +1. If present, use the parameter specified in the processing request directly (e.g. in `POST /jobs` as a top-level property) +2. If present, use the default parameter specified in the UDP +3. Otherwise, use the default value for the parameter as specified in `GET /processing_options` + +"Present" means that the property is present in the JSON representation regardless of the value given, i.e. +properties are present if an empty string, an empty array, an empty object, `false`, `0`, or `null` are provided. + +Unrecognized/unknown parameters that are provided through UDPs must be ignored by backends. diff --git a/extensions/processing-parameters/openapi.yaml b/extensions/processing-parameters/openapi.yaml index b19b6c7a..450166ea 100644 --- a/extensions/processing-parameters/openapi.yaml +++ b/extensions/processing-parameters/openapi.yaml @@ -2,8 +2,10 @@ openapi: 3.0.2 info: title: openEO API - Processing Parameters Extension version: 0.1.0 - description: |- - The Processing Parameters Extension to the openEO API provides an interface to explore and handle additional processing options that a back-end can offer for the three processing modes (synchronous processing, batch jobs, secondary web services). + description: >- + The Processing Parameters Extension to the openEO API provides an interface to explore and handle additional processing options that a back-end can offer for the three processing modes (synchronous processing, batch jobs, and secondary web services). + The openEO API specification allows back-ends to accept "additional back-end specific properties" for each of the processing modes. + As the openEO API specification does not define the name and schemas of these properties, this extension provides a standardized way to define and document these properties. contact: name: openEO Consortium url: 'https://openeo.org' @@ -47,7 +49,7 @@ paths: summary: Additional processing options operationId: list-processing-options description: |- - Lists additional custom processing options ("additional back-end specific properties" in the API specification) + Lists additional custom processing options that a back-end offers for the different processing modes (synchronous processing, batch jobs, secondary web services). The options specified here can be added to the corresponding `POST` requests at the top-level of the object that is sent as the payload. All options SHOULD explicitly be made optional with reasonable defaults as otherwise the interoperability between the implementations decreases.