openapi: 3.2.0 info: title: Openeo User-Defined Processes API version: 1.3.0 contact: name: openEO Project Steering Committee url: https://openeo.org email: openeo.psc@uni-muenster.de license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html description: 'Operations tagged User-Defined Processes across 2 of this provider''s published API definitions: openeo-api-openapi.yaml, openeo-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://openeo.example/api/{version} description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only! variables: version: default: v1 description: 'API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the **major** part of the version numbers SHOULD be used for API versioning in the URL. To make clear that it is a version number, it is RECOMMENDED to add the prefix `v`. Example: API version `1.2.3` is recommended to use `v1`. The reason to only consider the major part is that backward-incompatible changes are introduced by major changes only. All changes from minor and patch releases can usually be integrated without breakages and thus a change in the URL is not really needed. The version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned in the property `api_version` from `GET /` instead.' tags: - name: User-Defined Processes description: These endpoints allow to store and manage user-defined processes with their process graphs at the back-end. paths: /validation: post: summary: Validate a user-defined process (graph) operationId: validate-custom-process description: 'Validates a user-defined process without executing it. A user-defined process is considered valid unless the `errors` array in the response contains at least one error. Checks whether the process graph is schematically correct and the processes are supported by the back-end. It MUST also check the arguments against the schema, but checking whether the arguments are adequate in the context of data is OPTIONAL. For example, a non-existing band name may get rejected only by a few back-ends. The validation MUST NOT throw an error for unresolvable process parameters. Back-ends MUST validate the process graph. Validating the corresponding metadata is OPTIONAL. Errors that usually occur during processing MAY NOT get reported, e.g. if a referenced file is accessible at the time of execution. Back-ends can either report all errors at once or stop the validation once they found the first error. Please note that a validation always returns with HTTP status code 200. Error codes in the 4xx and 5xx ranges MUST be returned only when the general validation request is invalid (e.g. server is busy or properties in the request body are missing), but never if an error was found during validation of the user-defined process (e.g. an unsupported process).' tags: - User-Defined Processes security: - {} - Bearer: [] responses: '200': description: Returns the validation result as a list of errors. An empty list indicates a successful validation. content: application/json: schema: title: Validation Result type: object required: - errors properties: errors: description: A list of validation errors. type: array items: $ref: '#/components/schemas/error' 4XX: $ref: '#/components/responses/client_error_auth' 5XX: $ref: '#/components/responses/server_error' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/process_graph_with_metadata' examples: evi_user_defined_process: $ref: '#/components/examples/evi_user_defined_process' description: Specifies the user-defined process to be validated. servers: - url: https://openeo.example/api/{version} description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only! variables: version: default: v1 description: 'API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the **major** part of the version numbers SHOULD be used for API versioning in the URL. To make clear that it is a version number, it is RECOMMENDED to add the prefix `v`. Example: API version `1.2.3` is recommended to use `v1`. The reason to only consider the major part is that backward-incompatible changes are introduced by major changes only. All changes from minor and patch releases can usually be integrated without breakages and thus a change in the URL is not really needed. The version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned in the property `api_version` from `GET /` instead.' /process_graphs: get: summary: List all user-defined processes operationId: list-custom-processes description: 'Lists all user-defined processes (process graphs) of the authenticated user that are stored at the back-end. It is **strongly RECOMMENDED** to keep the response size small by omitting larger optional values from the objects in `processes` (e.g. the `exceptions`, `examples` and `links` properties). To get the full metadata for a user-defined process clients MUST request `GET /process_graphs/{process_graph_id}`.' tags: - User-Defined Processes security: - Bearer: [] parameters: - $ref: '#/components/parameters/pagination_limit' responses: '200': description: JSON array with user-defined processes. content: application/json: schema: title: User-Defined Processes type: object required: - processes - links properties: processes: description: Array of user-defined processes type: array items: $ref: '#/components/schemas/user_defined_process_meta' links: $ref: '#/components/schemas/links_pagination' example: processes: - id: evi summary: Enhanced Vegetation Index description: 'Computes the Enhanced Vegetation Index (EVI). It is computed with the following formula: `2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)`.' parameters: - name: red description: Value from the red band. schema: type: number - name: blue description: Value from the blue band. schema: type: number - name: nir description: Value from the near infrared band. schema: type: number returns: description: Computed EVI. schema: type: number - id: ndsi summary: Normalized-Difference Snow Index parameters: - name: green description: Value from the Visible Green (0.53 - 0.61 micrometers) band. schema: type: number - name: swir description: Value from the Short Wave Infrared (1.55 - 1.75 micrometers) band. schema: type: number returns: schema: type: number - id: my_custom_process links: [] 4XX: $ref: '#/components/responses/client_error_auth' 5XX: $ref: '#/components/responses/server_error' servers: - url: https://openeo.example/api/{version} description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only! variables: version: default: v1 description: 'API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the **major** part of the version numbers SHOULD be used for API versioning in the URL. To make clear that it is a version number, it is RECOMMENDED to add the prefix `v`. Example: API version `1.2.3` is recommended to use `v1`. The reason to only consider the major part is that backward-incompatible changes are introduced by major changes only. All changes from minor and patch releases can usually be integrated without breakages and thus a change in the URL is not really needed. The version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned in the property `api_version` from `GET /` instead.' /process_graphs/{process_graph_id}: parameters: - name: process_graph_id in: path description: Per-user unique identifier for a user-defined process. required: true schema: $ref: '#/components/schemas/process_id' get: summary: Full metadata for a user-defined process operationId: describe-custom-process description: Lists all information about a user-defined process, including its process graph. tags: - User-Defined Processes security: - Bearer: [] responses: '200': description: The user-defined process with process graph. content: application/json: schema: title: User-Defined Process description: A user-defined process with processing instructions as process graph. type: object required: - process_graph allOf: - $ref: '#/components/schemas/user_defined_process_meta' examples: evi_user_defined_process: $ref: '#/components/examples/evi_user_defined_process' 4XX: $ref: '#/components/responses/client_error_auth' 5XX: $ref: '#/components/responses/server_error' put: summary: Store a user-defined process operationId: store-custom-process description: 'Stores a provided user-defined process with process graph that can be reused in other processes. If a process with the specified `process_graph_id` exists, the process is fully replaced. The id can not be changed for existing user-defined processes. The id MUST be unique across its namespace. Partially updating user-defined processes is not supported. To simplify exchanging user-defined processes, the property `id` can be part of the request body. If the values do not match, the value for `id` gets replaced with the value from the `process_graph_id` parameter in the path.' tags: - User-Defined Processes security: - Bearer: [] responses: '200': description: The user-defined process has been stored successfully. 4XX: $ref: '#/components/responses/client_error_auth' 5XX: $ref: '#/components/responses/server_error' requestBody: required: true description: Specifies the process graph with its meta data. content: application/json: schema: $ref: '#/components/schemas/process_graph_with_metadata' examples: evi_user_defined_process: $ref: '#/components/examples/evi_user_defined_process' delete: summary: Delete a user-defined process operationId: delete-custom-process description: 'Deletes the data related to this user-defined process, including its process graph. Does NOT delete jobs or services that reference this user-defined process.' tags: - User-Defined Processes security: - Bearer: [] responses: '204': description: The user-defined process has been successfully deleted 4XX: $ref: '#/components/responses/client_error_auth' 5XX: $ref: '#/components/responses/server_error' servers: - url: https://openeo.example/api/{version} description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only! variables: version: default: v1 description: 'API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the **major** part of the version numbers SHOULD be used for API versioning in the URL. To make clear that it is a version number, it is RECOMMENDED to add the prefix `v`. Example: API version `1.2.3` is recommended to use `v1`. The reason to only consider the major part is that backward-incompatible changes are introduced by major changes only. All changes from minor and patch releases can usually be integrated without breakages and thus a change in the URL is not really needed. The version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned in the property `api_version` from `GET /` instead.' components: schemas: process_graph_json_schema: title: Process Graph type: object properties: subtype: type: string enum: - process-graph parameters: type: array title: Process Graph Parameters description: 'A list of parameters passed to the child process graph. The order in the array corresponds to the parameter order to be used in clients that do not support named parameters.' items: $ref: '#/components/schemas/parameter' returns: type: object title: Process Graph Return Value description: Description of the data that is returned by the child process graph. required: - schema properties: description: $ref: '#/components/schemas/process_description' schema: $ref: '#/components/schemas/data_type_schema' allOf: - $ref: '#/components/schemas/process_json_schema' process_description: type: string format: commonmark description: 'Detailed description to explain the entity. [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()`` ```' parameter: title: Parameter type: object required: - schema properties: schema: $ref: '#/components/schemas/data_type_schema' allOf: - $ref: '#/components/schemas/base_parameter' 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: title: Process Graph description: A process graph defines a graph-like structure as a connected set of executable processes. Each key is a unique identifier (node ID) that is used to refer to the process in the graph. type: object additionalProperties: x-additionalPropertiesName: Node ID title: Process Node type: object required: - process_id - arguments properties: process_id: $ref: '#/components/schemas/process_id' namespace: $ref: '#/components/schemas/process_namespace' result: type: boolean description: Used to specify which node is the last in the chain and returns the result to return to the requesting context. This flag MUST only be set once in each list of process nodes. default: false description: description: Optional description about the process and its arguments. type: - string - 'null' arguments: $ref: '#/components/schemas/process_arguments' example: dc: process_id: load_collection arguments: id: Sentinel-2 spatial_extent: west: 16.1 east: 16.6 north: 48.6 south: 47.2 temporal_extent: - '2018-01-01' - '2018-02-01' bands: process_id: filter_bands description: Filter and order the bands. The order is important for the following reduce operation. arguments: data: from_node: dc bands: - B08 - B04 - B02 evi: process_id: reduce description: 'Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)' arguments: data: from_node: bands dimension: bands reducer: process_graph: nir: process_id: array_element arguments: data: from_parameter: data index: 0 red: process_id: array_element arguments: data: from_parameter: data index: 1 blue: process_id: array_element arguments: data: from_parameter: data index: 2 sub: process_id: subtract arguments: data: - from_node: nir - from_node: red p1: process_id: product arguments: data: - 6 - from_node: red p2: process_id: product arguments: data: - -7.5 - from_node: blue sum: process_id: sum arguments: data: - 1 - from_node: nir - from_node: p1 - from_node: p2 div: process_id: divide arguments: data: - from_node: sub - from_node: sum p3: process_id: product arguments: data: - 2.5 - from_node: div result: true mintime: process_id: reduce description: Compute a minimum time composite by reducing the temporal dimension arguments: data: from_node: evi dimension: temporal reducer: process_graph: min: process_id: min arguments: data: from_parameter: data result: true save: process_id: save_result arguments: data: from_node: mintime format: GTiff result: true process_parameters: type: array description: 'A list of parameters. The order in the array corresponds to the parameter order to be used in clients that do not support named parameters. **Note:** Specifying an empty array is different from (if allowed) `null` or the property being absent. An empty array means the process has no parameters. `null` / property absent means that the parameters are unknown as the user has not specified them. There could still be parameters in the process graph, if one is specified.' items: $ref: '#/components/schemas/process_parameter' experimental: type: boolean description: Declares that the specified entity is experimental, which means that it is likely to change or may produce unpredictable behavior. Users should refrain from using it in production, but still feel encouraged to try it out and give feedback. default: false 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/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/process_json_schema' log_code: type: string description: The code is either one of the standardized error codes or a custom code, for example specified by a user in the `inspect` process. example: SampleError geometry_type: title: Geometry type type: string enum: - Point - MultiPoint - LineString - MultiLineString - Polygon - MultiPolygon - GeometryCollection base_parameter: type: object required: - name - description properties: name: type: string description: "A unique name for the parameter. \n\nUsing [snake case](https://en.wikipedia.org/wiki/Snake_case) (e.g. `window_size` or `scale_factor`) is RECOMMENDED." pattern: ^\w+$ description: $ref: '#/components/schemas/process_description' optional: type: boolean description: 'Determines whether this parameter is optional to be specified even when no default is specified. Clients 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.' default: false deprecated: $ref: '#/components/schemas/deprecated' experimental: $ref: '#/components/schemas/experimental' default: description: The default value for this parameter. Required parameters SHOULD NOT specify a default value. Optional parameters SHOULD always specify a default value. process_parameter: title: Process Parameter type: object required: - schema properties: schema: $ref: '#/components/schemas/process_schema' allOf: - $ref: '#/components/schemas/base_parameter' process_summary: type: string description: A short summary of what the process does. process_arguments: title: Process Arguments type: object additionalProperties: $ref: '#/components/schemas/process_argument_value' user_defined_process_meta: title: User-defined Process Metadata description: A user-defined process, may only contain metadata and no process graph. type: object required: - id properties: summary: type: - string - 'null' description: type: - string - 'null' parameters: type: - array - 'null' items: {} returns: type: - object - 'null' allOf: - $ref: '#/components/schemas/process' process_argument_value: title: Process Argument Value description: Arguments for a process. See the API documentation for more information. anyOf: - type: - object - 'null' title: Object (restricted) properties: from_parameter: not: {} from_node: not: {} process_graph: not: {} - type: string title: String - type: number title: Number (incl. integers) - type: boolean title: Boolean - type: array title: Array items: $ref: '#/components/schemas/process_argument_value' - $ref: '#/components/schemas/process_graph_with_metadata' - type: object title: Result Reference description: Data that is expected to be passed from another process. required: - from_node properties: from_node: description: The ID of the node that data is expected to come from. type: string additionalProperties: false - type: object title: Parameter Reference description: A parameter for a process graph. Data that is expected to be passed to a process graph either from the user directly or from the process that is executing the process graph. required: - from_parameter properties: from_parameter: description: The name of the parameter that data is expected to come from. type: string additionalProperties: false json_schema_type: type: string enum: - array - boolean - integer - 'null' - number - object - string dimension_axis_xyz: title: Axis description: Axis of a geometry or dimension (`x`, `y` or `z`) type: string enum: - x - y - z process_exceptions: type: object title: Process Exceptions description: 'Declares exceptions (errors) that might occur during execution of this process. This list is just for informative purposes and may be incomplete. This list MUST only contain exceptions that stop the execution of a process and MUST NOT contain warnings, notices or debugging messages. It is meant to primarily contain errors that have been caused by the user. It is RECOMMENDED that exceptions are referred to and explained in process or parameter descriptions. The keys define the error code and MUST match the following pattern: `^\w+$` This schema follows the schema of the general openEO error list (see errors.json).' additionalProperties: x-additionalPropertiesName: Error Code title: Process Exception type: object required: - message properties: description: type: string format: commonmark description: 'Detailed description to explain the error to client users and back-end developers. This should not be shown in the clients directly, but MAY be linked to in the errors `url` property. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation.' message: type: string description: 'Explains the reason the server is rejecting the request. This message is intended to be displayed to the client user. For "4xx" error codes the message SHOULD explain shortly how the client needs to modify the request. The message MAY contain variables, which are enclosed by curly brackets. Example: `{variable_name}`' example: 'The value specified for the process argument ''{argument}'' in process ''{process}'' is invalid: {reason}' http: type: integer description: HTTP Status Code, following the [error handling conventions in openEO](#section/API-Principles/Error-Handling). Defaults to `400`. default: 400 process_namespace: type: - string - 'null' default: null example: null description: "The namespace the `process_id` is valid for.\n\nThe following options are predefined by the openEO API, but additional\nnamespaces may be introduced by back-ends or in a future version of the API.\n\n* `null` (default): Checks both user-defined and predefined processes,\n but prefers user-defined processes if both are available.\n This allows users to add missing predefined processes for portability,\n e.g. common processes from [processes.openeo.org](https://processes.openeo.org)\n that have a process graph included.\n Logging the namespace selected by the back-end for debugging purposes is RECOMMENDED.\n* `backend`: Uses exclusively the predefined processes listed at `GET /processes`.\n* `user`: Uses exclusively the user-defined processes listed at `GET /process_graphs`.\n\nIf multiple processes with the same identifier exist, Clients SHOULD\ninform the user that it's recommended to select a namespace." deprecated: type: boolean description: 'Declares that the specified entity 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.' default: false links_pagination: description: 'Links related to this list of resources, for example links for pagination or alternative formats such as a human-readable HTML version. The links array MUST NOT be paginated. If pagination is implemented, the following `rel` (relation) types apply: 1. `next` (REQUIRED): A link to the next page, except on the last page. 2. `prev` (OPTIONAL): A link to the previous page, except on the first page. 3. `first` (OPTIONAL): A link to the first page, except on the first page. 4. `last` (OPTIONAL): A link to the last page, except on the last page. For additional relation types see also the lists of [common relation types in openEO](#section/API-Principles/Web-Linking).' type: array items: $ref: '#/components/schemas/link' process_id: type: string description: "The identifier for the process. It MUST be unique across its namespace\n(e.g. predefined processes or user-defined processes).\n\nClients SHOULD warn the user if a user-defined process is added with the \nsame identifier as one of the predefined process." pattern: ^\w+$ example: ndvi process: title: Process type: object properties: id: $ref: '#/components/schemas/process_id' summary: $ref: '#/components/schemas/process_summary' description: $ref: '#/components/schemas/process_description' categories: $ref: '#/components/schemas/process_categories' parameters: $ref: '#/components/schemas/process_parameters' returns: $ref: '#/components/schemas/process_return_value' deprecated: $ref: '#/components/schemas/deprecated' experimental: $ref: '#/components/schemas/experimental' exceptions: $ref: '#/components/schemas/process_exceptions' examples: type: array description: Examples, may be used for unit tests. items: title: Process Example type: object required: - arguments properties: title: type: string description: A title for the example. description: $ref: '#/components/schemas/process_description' arguments: $ref: '#/components/schemas/process_arguments' returns: description: The return value which can by of any data type. links: type: array description: 'Links related to this process, e.g. additional external documentation. Providing links with the following `rel` (relation) types is RECOMMENDED: 1. `latest-version`: If a process has been marked as deprecated, a link SHOULD point to the preferred version of the process. The relation types `predecessor-version` (link to older version) and `successor-version` (link to newer version) can also be used to show the relation between versions. 2. `version-history`: A link to a changelog and/or a list of versions of the process (see also the relation types `latest-version` etc.). 3. `example`: Links to examples of other processes that use this process. 4. `cite-as`: For all DOIs associated with the process, the respective DOI links SHOULD be added. 5. `license`: Links to applicable license(s). The link titles should reflect the license names. 6. `author`: Links to authors of the process. The `href` can use the `mailto:` protocol to link to an email address. The link titles should reflect the author names and affiliations. 7. `canonical`: Points to a publicly accessible and more long-lived URL. For additional relation types see also the lists of [common relation types in openEO](#section/API-Principles/Web-Linking).' items: $ref: '#/components/schemas/link' process_graph: $ref: '#/components/schemas/process_graph' process_graph_with_metadata: title: Process Graph with metadata description: A process graph, optionally enriched with process metadata. type: object required: - process_graph properties: id: type: - string - 'null' summary: type: - string - 'null' description: type: - string - 'null' parameters: type: - array - 'null' items: {} returns: type: - object - 'null' allOf: - $ref: '#/components/schemas/process' process_categories: type: array description: A list of categories. items: type: string description: Name of the category. process_return_value: type: object title: Process Return Value description: Description of the data that is returned by this process. required: - schema properties: description: $ref: '#/components/schemas/process_description' schema: $ref: '#/components/schemas/process_schema' log_links: description: 'Links related to this log entry / error, e.g. to a resource that provides further explanations. For relation types see the lists of [common relation types in openEO](#section/API-Principles/Web-Linking).' type: array items: $ref: '#/components/schemas/link' example: - href: https://openeo.example/docs/errors/SampleError rel: about link: title: Link description: A link to another resource on the web. Bases on [RFC 5899](https://www.rfc-editor.org/rfc/rfc5988.html). type: object required: - href - rel properties: rel: type: string description: Relationship between the current document and the linked document. SHOULD be a [registered link relation type](https://www.iana.org/assignments/link-relations/link-relations.xml) whenever feasible. example: related href: type: string description: The value MUST be a valid URL. format: uri example: https://openeo.example type: type: string description: The value MUST be a string that hints at the format used to represent data at the provided URI, preferably a media (MIME) type. example: text/html title: type: string description: Used as a human-readable label for a link. example: openEO 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.\nRight now, it only allows to specify the dimension types and \nadds for specific dimension types:\n* axes for `spatial` dimensions in raster datacubes\n* geometry types for `geometry` dimensions in vector datacubes" type: array items: type: object required: - type properties: type: type: string 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: - geometry geometry_type: type: array minItems: 1 items: $ref: '#/components/schemas/geometry_type' - title: Other properties: type: type: string enum: - bands - temporal - other data_type_schema: title: Data Types description: Either a single data type or a list of data types. oneOf: - $ref: '#/components/schemas/process_json_schema' - title: Multiple data types description: A list of data types this parameter supports, specified as JSON Schemas. type: array minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/process_json_schema' error: title: General Error description: 'An error object declares additional information about a client-side or server-side error. See also: * [Error Handling](#section/API-Principles/Error-Handling) in the API in general. * [Common Error Codes](errors.json)' type: object required: - code - message properties: id: type: string description: A back-end MAY add a unique identifier to the error response to be able to log and track errors with further non-disclosable details. A client could communicate this id to a back-end provider to get further information. example: 550e8400-e29b-11d4-a716-446655440000 code: $ref: '#/components/schemas/log_code' message: type: string description: A message explaining what the client may need to change or what difficulties the server is facing. example: Parameter 'sample' is missing. links: $ref: '#/components/schemas/log_links' json_schema: type: object title: JSON Schema description: 'A JSON Schema compliant to [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or later. 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 in the OpenAPI document is only a common subset of JSON Schema. Additional keywords from the JSON Schema specification MAY be used.' properties: $schema: description: 'The JSON Schema version. If not given in the context of openEO, defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator.' type: string format: uri default: http://json-schema.org/draft-07/schema# $id: description: ID of your JSON Schema. type: string format: uri type: description: 'The allowed data type(s) for a value. If this property is not present, all data types are allowed.' oneOf: - $ref: '#/components/schemas/json_schema_type' - type: array minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/json_schema_type' pattern: type: string format: regex description: The regular expression a string value must match against. enum: type: array items: {} description: An exclusive list of allowed values. minimum: type: number description: The minimum value (inclusive) allowed for a numerical value. maximum: type: number description: The maximum value (inclusive) allowed for a numerical value. minItems: type: number minimum: 0 default: 0 description: The minimum number of items required in an array. maxItems: type: number minimum: 0 description: The maximum number of items required in an array. items: description: Specifies schemas for the items in an array. anyOf: - type: array minItems: 1 items: $ref: '#/components/schemas/json_schema' - $ref: '#/components/schemas/json_schema' additionalProperties: description: Any other property supported by the JSON Schema version that is given through the property `$schema` are allowed. Defaults to JSON Schema [draft-07](https://json-schema.org/draft-07/json-schema-validation.html), but can also be any later version of JSON Schema. example: type: string enum: - a - b parameters: pagination_limit: name: limit description: 'This parameter enables pagination for the endpoint and specifies the maximum number of elements that arrays in the top-level object (e.g. collections, processes, batch jobs, secondary services, log entries, etc.) are allowed to contain. The `links` array MUST NOT be paginated like the resources, but instead contain links related to the paginated resources or the pagination itself (e.g. a link to the next page). If the parameter is not provided or empty, all elements are returned. Pagination is OPTIONAL: back-ends or clients may not support it. Therefore, it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources. If the response is paginated, the `links` array MUST be used to communicate the links for browsing the pagination with predefined `rel` types. See the `links` array schema for supported `rel` types. Back-end implementations can, unless specified otherwise, use any kind of pagination technique, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding `rel` types.' in: query allowEmptyValue: true example: 10 schema: type: integer minimum: 1 responses: client_error_auth: description: 'The request can not be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications. The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6). This request MUST respond with HTTP status codes 401 if authorization is required or 403 if the authorization failed or access is forbidden in general to the authenticated user. HTTP status code 404 SHOULD be used if the value of a path parameter is invalid. See also: * [Error Handling](#section/API-Principles/Error-Handling) in the API in general. * [Common Error Codes](errors.json)' content: application/json: schema: $ref: '#/components/schemas/error' server_error: description: 'The request can not be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response. The response body SHOULD contain a JSON error object. MUST be any HTTP status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6). See also: * [Error Handling](#section/API-Principles/Error-Handling) in the API in general. * [Common Error Codes](errors.json)' content: application/json: schema: $ref: '#/components/schemas/error' examples: evi_user_defined_process: description: A user-defined process that computes the Enhanced Vegetation Index (EVI). value: id: evi summary: Enhanced Vegetation Index description: 'Computes the Enhanced Vegetation Index (EVI). It is computed with the following formula: `2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)`.' parameters: - name: red description: Value from the red band. schema: type: number - name: blue description: Value from the blue band. schema: type: number - name: nir description: Value from the near infrared band. schema: type: number returns: description: Computed EVI. schema: type: number process_graph: sub: process_id: subtract arguments: x: from_parameter: nir y: from_parameter: red p1: process_id: multiply arguments: x: 6 y: from_parameter: red p2: process_id: multiply arguments: x: -7.5 y: from_parameter: blue sum: process_id: sum arguments: data: - 1 - from_parameter: nir - from_node: p1 - from_node: p2 div: process_id: divide arguments: x: from_node: sub y: from_node: sum p3: process_id: multiply arguments: x: 2.5 y: from_node: div result: true securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT or openEO description: "A Bearer token can be provided in two different formats:\n1. **JSON Web Token (JWT) - RECOMMENDED**\n\n - Conformance class: `https://api.openeo.org/1.3.0/authentication/jwt`\n \n The Bearer token is an access token in [JWT](https://datatracker.ietf.org/doc/html/rfc7519) format\n as defined in RFC 7519. For openEO, it MUST include the issuer in the\n `iss` claim although being optional in RFC 7519.\n If the concept of an issuer does not exist in an authentication method (e.g. in HTTP Basic),\n implementations could use the endpoint for Basic Authentication as the issuer, for example.\n\n openEO backend implementations MUST signal their support for JWT by listing the given\n conformance class. Likewise, openEO clients SHOULD only use JWT when the openEO backend\n lists the conformance class.\n\n2. **openEO Tokens - DEPRECATED**\n\n - Conformance class: *None*\n\n The Bearer Token is constructed from the authentication method, a\n provider ID (if available) and the access token. All separated by a\n forward slash `/`.\n\n Examples (replace `TOKEN` with the actual access token):\n\n - Basic authentication (no provider ID available): `basic//TOKEN`\n - OpenID Connect (provider ID is `ms`): `oidc/ms/TOKEN`.\n For OpenID Connect, the provider ID corresponds to the value\n specified for `id` for each provider in `GET /credentials/oidc`.\n\n All openEO backends MUST accept this method for backward compatibility\n until version 2.0 of the specification.\n\n The access tokens provided by the identity provider do not include\n the prefix that includes the authentication method and provider ID.\n The Bearer Token sent to the openEO backend MUST have the prefix, e.g. `basic//` for Basic authentication.\n This means that the clients have to prepend the prefix.\n\nJWT and openEO tokens can be distinguished by the presence of a slash `/` in the token, which JWT can never contain due to the Base64 encoding." Basic: type: http scheme: basic externalDocs: description: openEO Documentation url: https://openeo.org/documentation/1.0/ x-refined-from: - openeo-api-openapi.yaml - openeo-openapi.yml