Replies: 6 comments 1 reply
-
|
@m-mohr Interesting! Few thoughts (and fair warning: I'm far from being a
There might be ways to special case @m-mohr I'm curious, does the @philsturgeon Would you know how common it is to only expose a discriminator without listing all the possible schemas? And from another perspective, from a tooling standpoint, does schema validation even do anything meaningful in that context? |
Beta Was this translation helpful? Give feedback.
0 replies
-
Me neither, just learned to use it some weeks ago and struggled a lot.
openapi-generator throws a warning if I list them also in oneOf/anyOf. I think they argue that you better define it as shown below (only discriminator) and then define the other schemas and use allOf to reference the parent schema (see below). At least that is how I made code generation work and it somewhat makes sense. Otherwise it feels it needs to generate a single class with all the properties that could be available in the oneOfs, but that's not the case.
Yes, that would be appreciated a lot as code generation currently is very messy. Unfortunately, a discussion doesn't help now. OpenAPI 3.1 is around the corner and the issue hasn't been tackled there so until we have a better solution it will take years for the spec + tooling support.
Could be, but I don't see a violation of the openAPI spec so would expect that it works as it's referenced and not unsued.
I need to check that, but it's likely to fail as we still use it as shown below. I'd need to remove the "sub-types" that inherit with allOf to check that, but not sure how useful it is as we we actually have these sub-types and without them it's - as you said - probably not very useful.
As I said above, we use it as follows. It was the only way to get reasonable results from openapi-generator. components:
schemas:
udf_runtime:
type: object
required:
- type
- default
properties:
title:
$ref: '#/components/schemas/object_title'
description:
$ref: '#/components/schemas/description'
type:
type: string
description: |-
The type of the UDF runtime.
Pre-defined types are:
* `language` for Programming Languages and
* `docker` for Docker Containers.
The types can potentially be extended by back-ends.
default:
type: string
links:
type: array
description: |-
Links related to this runtime, e.g. external documentation.
It is highly RECOMMENDED to provide at least links with
the following `rel` (relation) types:
1. `about`: A resource that further explains the runtime,
e.g. a user guide or the documentation.
For additional relation types see also the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '#/components/schemas/link'
discriminator:
propertyName: type
mapping:
language: '#/components/schemas/udf_programming_language'
docker: '#/components/schemas/udf_docker'
udf_programming_language:
allOf:
- $ref: '#/components/schemas/udf_runtime'
- title: Programming language
required:
- versions
properties:
default:
type: string
description: The default version. MUST be one of the keys in the `versions` object.
versions:
title: Programming language versions
description: Versions available for the programming language.
type: object
additionalProperties:
x-additionalPropertiesName: Programming Language Version
title: Programming language version
type: object
required:
- libraries
properties:
libraries:
description: >-
Map of installed libraries, modules, packages
or extensions for the programming language.
The names of them are used as the property keys.
additionalProperties:
x-additionalPropertiesName: Library Name
title: Programming language library
type: object
required:
- version
properties:
version:
type: string
description: Version number of the library.
deprecated:
type: boolean
default: false
description: |-
Specifies that the library 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.
A link with relation type `latest-version` SHOULD be added to the
`links` and MUST refer to the library or library version that can be
used instead.
links:
type: array
description: |-
Additional links related to this library,
e.g. external documentation for this library.
It is highly RECOMMENDED to provide links with
the following `rel` (relation) types:
1. `about`: A resource that further explains the library,
e.g. a user guide or the documentation.
2. `latest-version`: If a library has been marked as deprecated,
a link should point to either a new library replacing the deprecated
library or a latest version of the library available at the back-end.
For additional relation types see also the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '#/components/schemas/link'
udf_docker:
allOf:
- $ref: '#/components/schemas/udf_runtime'
- title: Docker container
required:
- docker
- tags
properties:
docker:
type: string
description: >-
Identifier of a Docker image on Docker Hub or a
private repository, i.e. the docker image name.
default:
type: string
description: The default tag. MUST be one of the values in the `tags` array.
tags:
type: array
description: The docker tags that are supported.
minItems: 1
items:
type: string |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
Here's another example of discriminator being used as such: OAI/OpenAPI-Specification#2116 |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
What's the consequence of this being converted to a discussion? Is this not considered being a bug anymore? |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
More than one year later... Same issue here. Any update? |
Beta Was this translation helpful? Give feedback.
0 replies
-
|
This appears to be a missed definition for a discriminator object. The spec states:
That means you need to define the list of available schemas to be discriminated. I've only updated a few areas of the definition to abide by the spec. specifically,
When using Spectral VSC extension with hope this helps. OpenAPI definition for openEO APIopenapi: 3.0.4
info:
title: openEO API
version: 1.0.0-rc.2
description: |-
The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.
# API Principles
## Language
In the specification the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119).
## Casing
Unless otherwise stated the API works **case sensitive**.
All names SHOULD be written in snake case, i.e. words are separated with one underscore character (_) and no spaces, with all letters lower-cased. Example: `hello_world`. This applies particularly to endpoints and JSON property names. HTTP header fields follow their respective casing conventions, e.g. `Content-Type` or `OpenEO-Costs`, despite being case-insensitive according to [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2).
## HTTP / REST
This uses [HTTP REST](https://en.wikipedia.org/wiki/Representational_state_transfer) [Level 2](https://martinfowler.com/articles/richardsonMaturityModel.html#level2) for communication between client and back-end server.
Public APIs MUST be available via HTTPS only.
Endpoints are made use meaningful HTTP verbs (e.g. GET, POST, PUT, PATCH, DELETE) whenever technically possible. If there is a need to transfer big chunks of data for a GET requests to the back-end, POST requests MAY be used as a replacement as they support to send data via request body. Unless otherwise stated, PATCH requests are only defined to work on direct (first-level) children of the full JSON object. Therefore, changing a property on a deeper level of the full JSON object always requires to send the whole JSON object defined by the first-level property.
Naming of endpoints follow the REST principles. Therefore, endpoints are centered around resources. Resource identifiers MUST be named with a noun in plural form except for single actions that can not be modelled with the regular HTTP verbs. Single actions MUST be single endpoints with a single HTTP verb (POST is RECOMMENDED) and no other endpoints beneath it.
## JSON
The API uses JSON for request and response bodies whenever feasible. Services use JSON as the default encoding. Other encodings can be requested using [Content Negotiation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html). Clients and servers MUST NOT rely on the order in which properties appears in JSON. Collections usually don't include nested JSON objects if those information can be requested from the individual resources.
## Web Linking
The API is designed in a way that to most entities (e.g. collections and processes) a set of links can be added. These can be alternate representations, e.g. data discovery via OGC WCS or OGC CSW, references to a license, references to actual raw data for downloading, detailed information about pre-processing and more. Clients should allow users to follow the links.
Whenever links are utilized in the API, the description explains which relation (`rel` property) types are commonly used.
A [list of standardized link relations types is provided by IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml) and the API tries to align whenever feasible.
Some very common relation types - usually not mentioned explicitly in the description of `links` fields - are:
1. `self`: which allows link to the location that the resource can be (permanently) found online.This is particularly useful when the data is data is made available offline, so that the downstream user knows where the data has come from.
2. `alternate`: An alternative representation of the resource, may it be another metadata standard the data is available in or simply a human-readable version in HTML or PDF.
3. `about`: A resource that is related or further explains the resource, e.g. a user guide.
## Error Handling
The success of requests MUST be indicated using [HTTP status codes](https://tools.ietf.org/html/rfc7231#section-6) according to [RFC 7231](https://tools.ietf.org/html/rfc7231).
If the API responds with a status code between 100 and 399 the back-end indicates that the request has been handled successfully.
In general an error is communicated with a status code between 400 and 599. Client errors are defined as a client passing invalid data to the service and the service *correctly* rejecting that data. Examples include invalid credentials, incorrect parameters, unknown versions, or similar. These are generally "4xx" HTTP error codes and are the result of a client passing incorrect or invalid data. Client errors do *not* contribute to overall API availability.
Server errors are defined as the server failing to correctly return in response to a valid client request. These are generally "5xx" HTTP error codes. Server errors *do* contribute to the overall API availability. Calls that fail due to rate limiting or quota failures MUST NOT count as server errors.
### JSON error object
A JSON error object SHOULD be sent with all responses that have a status code between 400 and 599.
``` json
{
"id": "936DA01F-9ABD-4D9D-80C7-02AF85C822A8",
"code": "SampleError",
"message": "A sample error message.",
"url": "https://example.openeo.org/docs/errors/SampleError"
}
```
Sending `code` and `message` is REQUIRED.
* A back-end MAY add a free-form `id` (unique identifier) to the error response to be able to log and track errors with further non-disclosable details.
* The `code` is either one of the [standardized textual openEO error codes](errors.json) or a proprietary error code.
* The `message` explains the reason the server is rejecting the request. For "4xx" error codes the message explains how the client needs to modify the request.
By default the message MUST be sent in English language. Content Negotiation is used to localize the error messages: If an `Accept-Language` header is sent by the client and a translation is available, the message should be translated accordingly and the `Content-Language` header must be present in the response. See "[How to localize your API](http://apiux.com/2013/04/25/how-to-localize-your-api/)" for more information.
* `url` is an OPTIONAL attribute and contains a link to a resource that is explaining the error and potential solutions in-depth.
### Standardized status codes
The openEO API usually uses the following HTTP status codes for successful requests:
- **200 OK**:
Indicates a successful request **with** a response body being sent.
- **201 Created**
Indicates a successful request that successfully created a new resource. Sends a `Location` header to the newly created resource **without** a response body.
- **202 Accepted**
Indicates a successful request that successfully queued the creation of a new resource, but it has not been created yet. The response is sent **without** a response body.
- **204 No Content**:
Indicates a successful request **without** a response body being sent.
The openEO API has some commonly used HTTP status codes for failed requests:
- **400 Bad Request**:
The back-end responds with this error code whenever the error has its origin on client side and no other HTTP status code in the 400 range is suitable.
- **401 Unauthorized**:
The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct.
- **403 Forbidden**:
The client did provided correct authentication details, but the privileges/permissions of the provided credentials do not allow to request the resource.
- **404 Not Found**:
The resource specified by the path does not exist, i.e. one of the resources belonging to the specified identifiers are not available at the back-end.
*Note:* Unsupported endpoints MUST use HTTP status code 501.
- **500 Internal Server Error**:
The error has its origin on server side and no other status code in the 500 range is suitable.
If a HTTP status code in the 400 range is returned, the client SHOULD NOT repeat the request without modifications. For HTTP status code in the 500 range, the client MAY repeat the same request later.
All HTTP status codes defined in RFC 7231 in the 400 and 500 ranges can be used as openEO error code in addition to the most used status codes mentioned here. Responding with openEO error codes 400 and 500 SHOULD be avoided in favor of any more specific standardized or proprietary openEO error code.
## Temporal data
Date, time, intervals and durations are formatted based on ISO 8601 or its profile [RFC 3339](https://www.ietf.org/rfc/rfc3339) whenever there is an appropriate encoding available in the standard. All temporal data are specified based on the Gregorian calendar.
# Authentication
The openEO API offers two forms of authentication by default:
* OpenID Connect (recommended) at `GET /credentials/oidc`
* Basic at `GET /credentials/basic`
After authentication with any of the methods listed above, the tokens obtained during the authentication workflows can be sent to protected endpoints in subsequent requests.
Further authentication methods MAY be added by back-ends.
<SecurityDefinitions />
# Cross-Origin Resource Sharing (CORS)
> Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources [...] on a web page to be requested from another domain outside the domain from which the first resource was served. [...]
> CORS defines a way in which a browser and server can interact to determine whether or not it is safe to allow the cross-origin request. It allows for more freedom and functionality than purely same-origin requests, but is more secure than simply allowing all cross-origin requests.
Source: [https://en.wikipedia.org/wiki/Cross-origin_resource_sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
openEO-based back-ends are usually hosted on a different domain / host than the client that is requesting data from the back-end. Therefore most requests to the back-end are blocked by all modern browsers. This leads to the problem that the JavaScript library and any browser-based application can't access back-ends. Therefore, all back-end providers SHOULD support CORS to enable browser-based applications to access back-ends. [CORS is a recommendation of the W3C organization](https://www.w3.org/TR/cors/). The following chapters will explain how back-end providers can implement CORS support.
## OPTIONS method
All endpoints must respond to the `OPTIONS` HTTP method. This is a response for the preflight requests made by the browsers. It needs to respond with a status code of `204` and send the HTTP headers shown in the table below. No body needs to be provided.
| Name | Description | Example |
| -------------------------------- | ------------------------------------------------------------ | ------- |
| Access-Control-Allow-Origin | Allowed origin for the request, including protocol, host and port. It is RECOMMENDED to return the value of the request's origin header. If no `Origin` is sent to the back-end CORS headers SHOULD NOT be sent at all. | `http://client.isp.com:80` |
| Access-Control-Allow-Credentials | If authorization is implemented by the back-end the value MUST be `true`. | `true` |
| Access-Control-Allow-Headers | Comma-separated list of HTTP headers allowed to be send. MUST contain at least `Authorization` if authorization is implemented by the back-end. | ` Authorization, Content-Type` |
| Access-Control-Allow-Methods | Comma-separated list of HTTP methods allowed to be requested. Back-ends MUST list all implemented HTTP methods for the endpoint here. | `OPTIONS, GET, POST, PATCH, PUT, DELETE` |
| Access-Control-Expose-Headers | Some endpoints send non-safelisted HTTP response headers such as `OpenEO-Identifier` and `OpenEO-Costs`. All headers except `Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified` and `Pragma` must be listed in this header. Currently, the openEO API requires at least the following headers to be listed: `Location, OpenEO-Identifier, OpenEO-Costs`. | `Location, OpenEO-Identifier, OpenEO-Costs` |
| Content-Type | SHOULD return the content type delivered by the request that the permission is requested for. | `application/json` |
### Example request and response
Request:
```http
OPTIONS /api/v1/jobs HTTP/1.1
Host: openeo.cloudprovider.com
Origin: http://client.org:8080
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization, Content-Type
```
Response:
```http
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://client.org:8080
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: OPTIONS, GET, POST, PATCH, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Content-Type: application/json
```
## CORS headers
The following headers MUST be included with every response:
| Name | Description | Example |
| -------------------------------- | ------------------------------------------------------------ | ------- |
| Access-Control-Allow-Origin | Allowed origin for the request, including protocol, host and port. It is RECOMMENDED to return the value of the request's origin header. If no `Origin` is sent to the back-end CORS headers SHOULD NOT be sent at all. | `http://client.isp.com:80` |
| Access-Control-Allow-Credentials | If authorization is implemented by the back-end the value MUST be `true`. | `true` |
| Access-Control-Expose-Headers | Some endpoints send non-safelisted HTTP response headers such as `OpenEO-Identifier` and `OpenEO-Costs`. All headers except `Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified` and `Pragma` must be listed in this header. Currently, the openEO API requires at least the following headers to be listed: `Location, OpenEO-Identifier, OpenEO-Costs`. | `Location, OpenEO-Identifier, OpenEO-Costs` |
**Tip**: Most server can send the required headers and the responses to the OPTIONS requests globally. Otherwise you may want to use a proxy server to add the headers and OPTIONS responses.
# Processes
A **process** is an operation that performs a specific task on a set of parameters and returns a result. An example is computing a statistical operation, such as mean or median, on selected EO data. A process is similar to a function or method in programming languages. In openEO, processes are used to build a chain of processes ([process graph](#section/Processes/Process-Graphs)), which can be applied to EO data to derive your own findings from the data.
A **pre-defined process** is a process provided by the *back-end*. There is a set of predefined processes by openEO to improve interoperability between back-ends.
Back-ends SHOULD follow these specifications whenever possible. Not all processes need to be implemented by all back-ends. See the **[process reference](https://processes.openeo.org)** for pre-defined processes.
A **user-defined process** is a process defined by the *user*. It can directly be part of another process graph or be stored as custom process on a back-end. Internally it is a *process graph* with optional additional metadata.
A **process graph** chains specific process calls from the set of pre-defined and user-defined processes together. A process graph itself can be stored as a (user-defined) process again. Similarly to scripts in the context of programming, process graphs organize and automate the execution of one or more processes that could alternatively be executed individually. In a process graph, processes need to be specific, i.e. concrete values or "placeholders" for input parameters need to be specified. These values can be scalars, arrays, objects, references to parameters or previous computations or other process graphs.
## Defining Processes
Back-ends and users MAY define new proprietary processes for their domain.
**Back-end providers** MUST follow the schema for predefined processes as in [`GET /processes`](/#tag/Process-Discovery) to define new processes. This includes:
* Choosing a intuitive and ideally unique name as process id, consisting of only letters (a-z), numbers and underscores.
* Defining the parameters and their exact (JSON) schemes.
* Specifying the return value of a process also with a (JSON) schema.
* Providing examples or compliance tests.
* Trying to make the process universally usable so that other back-end providers or openEO can adopt it.
**Users** MUST follow the schema for user-defined processes as in [`GET /process_graphs`](/#tag/User-Defined-Processes) to define new processes. This includes:
* Choosing a intuitive and ideally unique name as process id, consisting of only letters (a-z), numbers and underscores.
* Defining the algorithm as a process graph.
* Optionally, specifying the additional metadata for processes.
If new process are potentially useful for other back-ends the openEO consortium is happily accepting [pull requests](https://github.com/Open-EO/openeo-processes/pulls) to include them in the list of pre-defined processes.
### Schemas
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/).
Two custom keywords have been defined:
* `subtype` for more fine-grained data-types than JSON Schema supports.
* `parameters` to specify parameters that processes can pass to other process graphs.
### Subtypes
JSON Schema allows to specify only a small set of native data types (string, boolean, number, integer, array, object, null).
To support more fine grained data types, a custom [JSON Schema keyword](https://tools.ietf.org/html/draft-handrews-json-schema-01#section-6.4) has been defined: `subtype`.
It works similarly as the JSON Schema keyword [`format`](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7) and defines a number of subtypes for the native data types.
These 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.
Clients should offer make passing subtypes as easy as passing a general data type.
For example, a parameter accepting strings must also allow passing a string with subtype `date` and thus clients should encourage this by also providing a date-picker.
A [list of predefined subtypes](subtype-schemas.json) is available as JSON Schema.
## Process Graphs
As defined above, a **process graph** is a chain of processes with explicit values for their parameters.
Technically, a process graph is defined to be a graph of connected processes with exactly one node returning the final result:
```
<ProcessGraph> := {
"<ProcessNodeIdentifier>": <ProcessNode>,
...
}
```
`<ProcessNodeIdentifier>` is a unique key within the process graph that is used to reference (the return value of) this process in arguments of other processes. The identifier is unique only strictly within itself, excluding any parent and child process graphs. Process node identifiers are also strictly scoped and can not be referenced from child or parent process graphs. Circular references are not allowed.
Note: We provide a non-binding [JSON Schema for basic process graph validation](assets/pg-schema.json).
### Processes (Process Nodes)
A single node in a process graph (i.e. a specific instance of a process) is defined as follows:
```
<ProcessNode> := {
"process_id": <string>,
"description": <string>,
"arguments": <Arguments>,
"result": true / false
}
```
A process node MUST always contain key-value-pairs named `process_id` and `arguments`. It MAY contain a `description`.
One of the nodes in a map of processes (the final one) MUST have the `result` flag set to `true`, all the other nodes can omit it as the default value is `false`. Having such a node is important as multiple end nodes are possible, but in most use cases it is important to exactly specify the return value to be used by other processes. Each child process graph must also specify a result node similar to the "main" process graph.
`process_id` MUST be any of the pre-defined or user-defined process IDs, which are all listed at `GET /processes` and `GET /process_graphs`. An example is `load_collection` to retrieve data from a specific collection for processing.
### Arguments
A process can have an arbitrary number of arguments. Their name and value are specified
in the process specification as an object of key-value pairs:
```
<Arguments> := {
"<ParameterName>": <string|number|boolean|null|array|object|ResultReference|UserDefinedProcess|ParameterReference>
}
```
**Notes:**
- The specified data types are the native data types supported by JSON, except for `ResultReference`, `UserDefinedProcess` and `ParameterReference`.
- Objects are not allowed to have keys with the following reserved names:
* `from_node`, except for objects of type `ResultReference`
* `process_graph`, except for objects of type `UserDefinedProcess`
* `from_parameter`, except for objects of type `ParameterReference`
- Arrays and objects can also contain a `ResultReference`, a `UserDefinedProcess` or a `ParameterReference`. So back-ends must *fully* traverse the process graphs, including all children.
### Accessing results of other process nodes
A value of type `<ResultReference>` is an object with a key `from_node` and a `<ProcessNodeIdentifier>` as corresponding value:
```
<ResultReference> := {
"from_node": "<ProcessNodeIdentifier>"
}
```
This tells the back-end that the process expects the result (i.e. the return value) from another process node to be passed as argument.
The `<ProcessNodeIdentifier>` is strictly scoped and can only reference nodes from within the same process graph, not child or parent process graphs.
### User-defined process
A user-defined process in a process graph is a child process graph, to be evaluated as part of another process.
**Example**: You want to calculate the absolute value of each pixel in a data cube.
This can be achieved in openeEO by executing the `apply` process and pass it
a user-defined process as the "operator" to apply to each pixel.
In this simple example, the "child" process graph defining the user-defined process
consists of a single process `absolute`, but it can be arbitrairy complex in general.
A `<UserDefinedProcess>` argument must at least consist of an object with a key `process_graph`.
Optionally, it can also be described with the same additional properties available for pre-defined processes such as an id, parameters, return values etc.
When embedded in a process graph, these additional properties of a user-defined process are usually not used, except for validation purposes.
```
<UserDefinedProcess> := {
"process_graph": <ProcessGraph>,
...
}
```
### Accessing process parameters
A "parent" process that works with a user-defined process can make so called *process graph parameters*
available to the "child" logic.
Processes in the "child" process graph can access these parameters by passing a `ParameterReference` object as argument.
It is an object with key `from_parameter` specifying the name of the process graph parameter:
```
<ParameterReference> := {
"from_parameter": "<ParameterReferenceName>"
}
```
The parameter names made available for `<ParameterReferenceName>` are defined and passed to the process graph by one of the parent entities.
The parent could be a process (such as `apply` or `reduce_dimension`) or something else that executes a process graph (a secondary web service for example).
If the parent is a process, the parameter are defined in the [`parameters` property](#section/Processes/Defining-Processes) of the corresponding JSON Schema.
In case of the example given above, the parameter `process` in the process [`apply`](https://processes.openeo.org/#apply) defines two process graph parameters: `x` (the value of each pixel that will be processed) and `context` (additional data passed through from the user).
The process `absolute` expects an argument with the same name `x`.
The process graph for the example would look as follows:
```
{
"process_id": "apply",
"arguments": {
"data": {"from_node": "loadcollection1"}
"process": {
"process_graph": {
"abs1": {
"process_id": "absolute",
"arguments": {
"x": {"from_parameter": "x"}
},
"result": true
}
}
}
}
}
```
`loadcollection1` would be a result from another process, which is not part of this example.
**Important:** `<ParameterReferenceName>` is less strictly scoped than `<ProcessNodeIdentifier>`.
`<ParameterReferenceName>` can be any parameter from the process graph or any of its parents.
The value for the parameter must be resolved as follows:
1. In general the most specific parameter value is used. This means the parameter value is resolved starting from the current scope and then checking each parent for a suitable parameter value until a parameter values is found or the "root" process graph has been reached.
2. In case a parameter value is not available, the most unspecific default value from the process graph parameter definitions are used. For example, if default values are available for the root process graph and all children, the default value from the root process graph is used.
3. If no default values are available either, the error `ProcessParameterMissing` must be thrown.
### Full example for an EVI computation
Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel 2 imagery. The main process graph in blue, child process graphs in yellow:
The process graph for the algorithm: [pg-evi-example.json](assets/pg-evi-example.json)
## Data Processing
Processes can run in three different ways:
1. Results can be pre-computed by creating a ***batch job***. They are submitted to the back-end's processing system, but will remain inactive until explicitly put into the processing queue. They will run only once and store results after execution. Results can be downloaded. Batch jobs are typically time consuming and user interaction is not possible although log files are generated for them. This is the only mode that allows to get an estimate about time, volume and costs beforehand.
2. A more dynamic way of processing and accessing data is to create a **secondary web service**. They allow web-based access using different protocols such as [OGC WMS](http://www.opengeospatial.org/standards/wms) (Open Geospatial Consortium Web Map Service), [OGC WCS](http://www.opengeospatial.org/standards/wcs) (Web Coverage Service) or [XYZ tiles](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames). These protocols usually allow users to change the viewing extent or level of detail (zoom level). Therefore, computations often run *on demand* so that the requested data is calculated during the request. Back-ends should make sure to cache processed data to avoid additional/high costs and reduce waiting times for the user.
3. Processes can also be executed **on-demand** (i.e. synchronously). Results are delivered with the request itself and no job is created. Only lightweight computations, for example previews, should be executed using this approach as timeouts are to be expected for [long-polling HTTP requests](https://www.pubnub.com/blog/2014-12-01-http-long-polling/).
### Validation
Process graph validation is a quite complex task. There's a [JSON schema](assets/pg-schema.json) for basic process graph validation. It checks the general structure of a process graph, but only checking against the schema is not fully validating a process graph. Note that this JSON Schema is probably good enough for a first version, but should be revised and improved for production. There are further steps to do:
1. Validate whether there's exactly one `result: true` per process graph.
2. Check whether the process names that are referenced in the field `process_id` are actually available. There's a custom format `process-id`, which can be used to check the value directly during validation against the JSON Schema.
3. Validate all arguments for each process against the JSON schemas that are specified in the corresponding process specifications.
4. Check whether the values specified for `from_node` have a corresponding node in the same process graph.
5. Validate whether the return value and the arguments requesting a return value with `from_node` are compatible.
7. Check the content of arrays and objects. These could include parameter and result references (`from_node`, `from_parameter` etc.).
### Execution
To process the process graph on the back-end you need to go through all nodes/processes in the list and set for each node to which node it passes data and from which it expects data. In another iteration the back-end can find all start nodes for processing by checking for zero dependencies.
You can now start and execute the start nodes (in parallel, if possible). Results can be passed to the nodes that were identified beforehand. For each node that depends on multiple inputs you need to check whether all dependencies have already finished and only execute once the last dependency is ready.
Please be aware that the result node (`result` set to `true`) is not necessarily the last node that is executed. The author of the process graph may choose to set a non-end node to the result node!
contact:
name: openEO Consortium
url: 'https://openeo.org'
email: openeo@list.tuwien.ac.at
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
externalDocs:
description: openEO Documentation
url: 'https://openeo.org/documentation/1.0/'
tags:
- name: Capabilities
description: General information about the API implementation and other supported capabilities at the back-end.
- name: Account Management
description: |-
The following endpoints handle user profiles, accounting and authentication. See also [Authentication](#section/Authentication). In general, the openEO API only defines a minimum subset of user management and accounting functionality. It allows to
* [authenticate and authorize](http://www.differencebetween.net/technology/difference-between-authentication-and-authorization/) a user, which may include [user registration with OpenID Connect](http://openid.net/specs/openid-connect-registration-1_0.html),
* handle storage space limits (disk quota),
* manage billing, which includes to
* query the credit a user has available,
* estimate costs for certain operations (data processing and downloading),
* get information about produced costs,
* limit costs of certain operations.
Therefore, the API leaves some aspects open that have to be handled by the back-ends separately, including
* credential recovery, e.g. retrieving a forgotten password
* user data management, e.g. changing the users payment details or email address
* payments, i.e. topping up credits for pre-paid services or paying for post-paid services
* other accounting related tasks, e.g. creating invoices,
* user registration (except for [user registration with OpenID Connect](http://openid.net/specs/openid-connect-registration-1_0.html)).
- name: EO Data Discovery
description: |-
These endpoints allow to list the collections that are available at the back-end and can be used as data cubes for data processing.
## STAC
For data discovery of Earth Observation Collections at the back-ends, openEO strives for compatibility with the specifications [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) and [OGC API - Features - Part 1: Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) as far as possible. Implementing the data discovery endpoints of openEO should also produce valid STAC API 0.9.0 and OGC API - Features 1.0 responses, including ([partial](#provide-data-for-download)) compatibility with their APIs.
The data discovery endpoints `GET /collections` and `GET /collections/{collection_id}` are compatible with OGC API - Features and STAC. Both specifications define additional endpoints that need to be implemented to be fully compatible. The additional endpoints can easily be integrated into an openEO API implementation. A rough list of actions for compatibility is available below, but please refer to their specifications to find out the full details.
**Important:** [STAC specification](https://github.com/radiantearth/stac-spec) and [STAC API](https://github.com/radiantearth/stac-api-spec) are different specifications and have different version numbers after version 0.9.0.
The openEO API only implements [STAC API version 0.9.0](https://github.com/radiantearth/stac-spec/blob/v0.9.0/api-spec/README.md), which allows to serve all STAC specification versions in the range of 0.9.x and 1.x.x (see the `stac_version` property).
### Content Extensions
STAC has several [extensions](https://github.com/radiantearth/stac-spec/tree/v0.9.0/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 metadata.
Some commonly used extensions that are relevant for datasets exposed through the openEO API are:
- Data Cube extension (part of the openEO API)
- [EO (Electro-Optical) extension](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions/eo)
- [SAR extension](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions/sar)
- [Satellite extension](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions/sat)
- [Scientific extension](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions/scientific)
### 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/{collectionId}/items/{featureId}` to support retrieval of individual items. To benefit from the STAC ecosystem and allow searching for items you can also implement `POST /search` and `GET /search`. Further information can be found in the [STAC API repository](https://github.com/radiantearth/stac-spec/tree/v0.9.0/api-spec).
- name: Process Discovery
description: |-
These endpoints allow to list the predefined processes that are available at the back-end. To list user-defined processes see '[User-Defined Processes](#tag/User-Defined-Processes)'.
- name: User-Defined Processes
description: These endpoints allow to store and manage user-defined processes with their process graphs at the back-end.
- name: Data Processing
description: Organizes and manages data processing on the back-end, either as synchronous on-demand computation or batch jobs.
- name: Batch Jobs
description: Management of batch processing tasks (jobs) and their results.
- name: Secondary Services
description: On-demand access to data using other web service protocols.
- name: File Storage
description: Management of user-uploaded assets and processed data.
servers:
- url: 'https://localhost/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.0
description: >-
API versioning is RECOMMENDED. As the openEO API is following
[SemVer](https://semver.org/) only the MAJOR part of the stable
version numbers (i.e. versions >= 1.0.0) SHOULD be used for API
versioning in the URL. The reason is that backward-incompatible
changes are usually introduced by major changes. Therefore, 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 from
`GET /` instead.
paths:
/:
get:
summary: Information about the back-end
operationId: capabilities
description: >-
Returns general information about the back-end, including which version
and endpoints of the openEO API are supported. May also include billing
information.
tags:
- Capabilities
security:
- {}
responses:
'200':
description: >-
Information about the API version and supported endpoints /
features.
content:
application/json:
schema:
title: Capabilities
type: object
required:
- id
- title
- description
- api_version
- backend_version
- stac_version
- endpoints
- links
properties:
api_version:
type: string
description: >-
Version number of the openEO specification this back-end
implements.
example: 1.0.1
backend_version:
type: string
description: >-
Version number of the back-end implementation.
Every change on back-end side MUST cause a change of the
version number.
example: 1.1.2
stac_version:
$ref: '#/components/schemas/stac_version'
id:
type: string
description: >-
Identifier for the service.
This field originates from STAC and is used as unique identifier for the STAC catalog available at `/collections`.
example: cool-eo-cloud
title:
type: string
description: The name of the service.
example: Cool EO Cloud
description:
type: string
format: commonmark
description: >-
A description of the service, which allows the service
provider to introduce the user to its service.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be
used for rich text representation.
example: |-
This service is provided to you by [Cool EO Cloud Corp.](http://cool-eo-cloud-corp.com). It implements the full openEO API and allows to process a range of 999 EO data sets, including
* Sentinel 1/2/3 and 5
* Landsat 7/8
A free plan is available to test the service. For further information please contact our customer service at [support@cool-eo-cloud-corp.com](mailto:support@cool-eo-cloud-corp.com).
production:
$ref: '#/components/schemas/production'
endpoints:
type: array
description: >-
Lists all supported endpoints. Supported are all
endpoints, which are implemented, return a 2XX or 3XX HTTP
status code and are fully compatible to the API
specification.
items:
title: Endpoint
type: object
required:
- path
- methods
properties:
path:
description: >-
Path to the endpoint, relative to the URL of this
endpoint. In general the paths MUST follow the paths
specified in the openAPI specification as closely as
possible. Therefore, paths MUST be prepended with a
leading slash, but MUST NOT contain a trailing
slash. Variables in the paths MUST be placed in
curly braces and follow the parameter names in the
openAPI specification, e.g. `{job_id}`.
type: string
methods:
description: >-
Supported HTTP verbs in uppercase. It is not
required to list OPTIONS as method (see the
documentation regarding CORS).
type: array
items:
enum:
- GET
- POST
- PATCH
- PUT
- DELETE
example:
- path: /collections
methods:
- GET
- path: '/collections/{collection_id}'
methods:
- GET
- path: /processes
methods:
- GET
- path: /jobs
methods:
- GET
- POST
- path: '/jobs/{job_id}'
methods:
- GET
- DELETE
- PATCH
billing:
title: Billing
description: >-
Billing related data, e.g. the currency used or available
plans to process jobs.
This property MUST be specified if the back-end uses any
billing related API functionalities, e.g. budgeting or
estimates.
The absence of this property doesn't mean the back-end is
necessarily free to use for all. Providers may choose to
bill users outside of the API, e.g. with a monthly fee
that is not depending on individual API interactions.
type: object
required:
- currency
properties:
currency:
description: >-
The currency the back-end is billing in. The currency
MUST be either a valid currency code as defined in
ISO-4217 or a proprietary currency, e.g. tiles or
back-end specific credits. If set to the default value
`null`, budget and costs are not supported by the
back-end and users can't be charged.
type: string
nullable: true
default: null
example: USD
default_plan:
type: string
description: >-
Name of the default plan to use when the user doesn't
specify a plan. Is allowed to be *case insensitive*
throughout the API.
example: free
plans:
description: Array of plans
type: array
items:
title: Billing Plan
type: object
required:
- name
- description
- paid
properties:
name:
type: string
description: >-
Name of the plan. Is allowed to be *case
insensitive* throughout the API.
example: free
description:
type: string
format: commonmark
description: >-
A description that gives a rough overview over
the plan.
[CommonMark 0.29](http://commonmark.org/) syntax
MAY be used for rich text representation.
example: Free plan for testing.
paid:
type: boolean
description: >-
Indicates whether the plan is a paid plan
(`true`) or a free plan (`false`).
url:
type: string
description: >-
URL to a web page with more details about the
plan.
format: uri
example: 'http://cool-cloud-corp.com/plans/free-plan'
example:
- name: free
description: >-
Free plan. Calculates one tile per second and a
maximum amount of 100 tiles per hour.
url: 'http://cool-cloud-corp.com/plans/free-plan'
paid: false
- name: premium
description: >-
Premium plan. Calculates unlimited tiles and each
calculated tile costs 0.003 USD.
url: 'http://cool-cloud-corp.com/plans/premium-plan'
paid: true
links:
description: |-
Links related to this service, e.g. the homepage of
the service provider or the terms of service.
It is highly RECOMMENDED to provide links with the
following `rel` (relation) types:
1. `version-history`: A link back to the Well-Known URL
(see `/.well-known/openeo`) to allow clients to work on
the most recent version.
2. `terms-of-service`: A link to the terms of service. If
a back-end provides a link to the terms of service, the
clients MUST provide a way to read the terms of service
and only connect to the back-end after the user agreed to
them. The user interface MUST be designed in a way that
the terms of service are not agreed to by default, i.e.
the user MUST explicitly agree to them.
3. `privacy-policy`: A link to the privacy policy (GDPR).
If a back-end provides a link to a privacy policy, the
clients MUST provide a way to read the privacy policy and
only connect to the back-end after the user agreed to
them. The user interface MUST be designed in a way that
the privacy policy is not agreed to by default, i.e. the
user MUST explicitly agree to them.
4. `service-desc` or `service-doc`: A link to the API definition.
Use `service-desc` for machine-readable API definition and
`service-doc` for human-readable API definition.
Required if full OGC API compatibility is desired.
5. `conformance`: A link to the Conformance declaration
(see `/conformance`).
Required if full OGC API compatibility is desired.
6. `data`: A link to the collections (see `/collections`).
Required if full OGC API compatibility is desired.
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'
example:
- href: 'http://www.cool-cloud-corp.com'
rel: about
type: text/html
title: Homepage of the service provider
- href: 'https://www.cool-cloud-corp.com/tos'
rel: terms-of-service
type: text/html
title: Terms of Service
- href: 'https://www.cool-cloud-corp.com/privacy'
rel: privacy-policy
type: text/html
title: Privacy Policy
- href: 'http://www.cool-cloud-corp.com/.well-known/openeo'
rel: version-history
type: application/json
title: List of supported openEO versions
- href: 'http://www.cool-cloud-corp.com/api/v1.0/conformance'
rel: conformance
type: application/json
title: OGC Conformance Classes
- href: 'http://www.cool-cloud-corp.com/api/v1.0/collections'
rel: data
type: application/json
title: List of Datasets
4XX:
$ref: '#/components/responses/client_error'
5XX:
$ref: '#/components/responses/server_error'
/.well-known/openeo:
get:
summary: Supported openEO versions
operationId: connect
description: |-
Well-Known URI (see [RFC 5785](https://tools.ietf.org/html/rfc5785))
for openEO, listing all implemented openEO versions supported by the
service provider.
This allows a client to easily identify the most recent openEO
implementation it supports. By default, a client SHOULD connect to the
most recent production-ready version it supports. If not available, the
most recent supported version of *all* versions SHOULD be connected to.
Clients MAY let users choose to connect to versions that are not
production-ready or outdated.
The most recent version is determined by comparing the version numbers
according to rules from [Semantic Versioning](https://semver.org/),
especially [§11](https://semver.org/#spec-item-11). Any pair of API
versions in this list MUST NOT be equal according to Semantic Versioning.
The Well-Known URI is the entry point for clients and users, so make
sure it is permanent and easy to use and remember. Clients MUST NOT
require the well-known path (`./well-known/openeo`) in the URL that is
specified by a user to connect to the back-end. A client MUST request
`https://example.com/.well-known/openeo` if a user tries to connect to
`https://example.com`. If the request to the well-known URI fails, the
client SHOULD try to request the capabilities at `/` from
`https://example.com`.
**This URI MUST NOT be versioned as the other endpoints.** If your API
is available at `https://example.com/api/v1.0`, the Well-Known URI
SHOULD be located at `https://example.com/.well-known/openeo` and the
URI users connect to SHOULD be `https://example.com`.
Clients MAY get additional information (e.g. title or description) about
a back-end from the most recent version that has the `production` flag
set to `true`.
tags:
- Capabilities
security:
- {}
servers:
- url: 'https://localhost'
description: >-
The Well-Known URI SHOULD be available directly at
`https://{{domain}}/.well-known/openeo` in contrast to the other
endpoints, which may be versioned and can run on other hosts, ports,
... etc.
responses:
'200':
description: >-
List of all available API instances, each with URL and the
implemented openEO API version.
content:
application/json:
schema:
title: Well Known Discovery
type: object
required:
- versions
properties:
versions:
type: array
items:
title: API Instance
type: object
required:
- url
- api_version
properties:
url:
type: string
format: uri
description: '*Absolute* URLs to the service.'
example: 'https://example.com/api/v1.0'
production:
$ref: '#/components/schemas/production'
api_version:
type: string
description: >-
Version number of the openEO specification this
back-end implements.
example: 1.0.1
example:
versions:
- url: 'https://example.openeo.org/api/v0.5'
api_version: 0.5.1
- url: 'https://example.openeo.org/api/v1.0'
api_version: 1.0.0
- url: 'https://example.openeo.org/api/v1.1'
production: false
api_version: 1.1.0-beta
4XX:
$ref: '#/components/responses/client_error'
5XX:
$ref: '#/components/responses/server_error'
/file_formats:
get:
summary: Supported file formats
operationId: list-file-types
description: >-
The request will ask the back-end for supported input and output file
formats. *Input* file formats specify which file a back-end can *read*
from. *Output* file formats specify which file a back-end can *write*
to.
The response to this request is an object listing all available input
and output file formats separately with their parameters and additional
data. This endpoint does not include the supported secondary web
services.
**Note**: Format names and parameters MUST be fully aligned with the
GDAL codes if available, see [GDAL Raster
Formats](http://www.gdal.org/formats_list.html) and [OGR Vector
Formats](http://www.gdal.org/ogr_formats.html). It is OPTIONAL to
support all output format parameters supported by GDAL. Some file
formats not available through GDAL may be defined centrally for openEO.
Custom file formats or parameters MAY be defined.
The format descriptions must describe how the file formats relate to
data cubes. Input file formats must describe how the files have to be
structured to be transformed into data cubes. Output file formats must
describe how the data cubes are stored at the back-end and how the
resulting file structure looks like.
Back-ends MUST NOT support aliases, for example it is not allowed to
support `geotiff` instead of `gtiff`. Nevertheless, openEO Clients MAY
translate user input input for convenience (e.g. translate `geotiff` to
`gtiff`). Also, for a better user experience the back-end can specify a
`title`.
Format names are allowed to be *case insensitive* throughout the API.
tags:
- Capabilities
- Data Processing
security:
- {}
- Bearer: []
responses:
'200':
description: >-
An object with containing all input and output format separately.
For each property `input` and `output` an object is defined where
the file format names are the property keys and the property values
are objects that define a title, supported parameters and related
links.
content:
application/json:
schema:
title: File Formats
type: object
required:
- input
- output
properties:
input:
title: Input File Formats
type: object
description: >-
Map of supported input file formats, i.e. file formats a
back-end can **read** from. The property keys are the file
format names that are used by clients and users, for
example in process graphs.
additionalProperties:
$ref: '#/components/schemas/file_format'
output:
title: Output File Formats
type: object
description: >-
Map of supported output file formats, i.e. file formats a
back-end can **write** to. The property keys are the file
format names that are used by clients and users, for
example in process graphs.
additionalProperties:
$ref: '#/components/schemas/file_format'
example:
output:
GTiff:
title: GeoTiff
description: Export to GeoTiff. Doesn't support cloud-optimized GeoTiffs (COGs) yet.
gis_data_types:
- raster
parameters:
tiled:
type: boolean
description: >-
This option can be used to force creation of tiled
TIFF files [true]. By default [false] stripped TIFF
files are created.
default: false
compress:
type: string
description: Set the compression to use.
default: NONE
enum:
- JPEG
- LZW
- DEFLATE
- NONE
jpeg_quality:
type: integer
description: Set the JPEG quality when using JPEG.
minimum: 1
maximum: 100
default: 75
links:
- href: 'https://www.gdal.org/frmt_gtiff.html'
rel: about
title: GDAL on the GeoTiff file format and storage options
GPKG:
title: OGC GeoPackage
gis_data_types:
- raster
- vector
parameters:
version:
type: string
description: >-
Set GeoPackage version. In AUTO mode, this will be
equivalent to 1.2 starting with GDAL 2.3.
enum:
- auto
- '1'
- '1.1'
- '1.2'
default: auto
links:
- href: 'https://www.gdal.org/drv_geopackage_raster.html'
rel: about
title: GDAL on GeoPackage for raster data
- href: 'https://www.gdal.org/drv_geopackage.html'
rel: about
title: GDAL on GeoPackage for vector data
input:
GPKG:
title: OGC GeoPackage
gis_data_types:
- raster
- vector
parameters:
table:
type: string
description: >-
**RASTER ONLY.** Name of the table containing the
tiles. If the GeoPackage dataset only contains one
table, this option is not necessary. Otherwise, it
is required.
links:
- href: 'https://www.gdal.org/drv_geopackage_raster.html'
rel: about
title: GDAL on GeoPackage for raster data
- href: 'https://www.gdal.org/drv_geopackage.html'
rel: about
title: GDAL on GeoPackage for vector data
4XX:
$ref: '#/components/responses/client_error'
5XX:
$ref: '#/components/responses/server_error'
/conformance:
get:
summary: OGC specifications this API conforms to
operationId: conformance
description: >-
A list of all conformance classes specified in OGC standards that the
server conforms to.
This endpoint is only required if full compliance with OGC API standards is desired.
Therefore, openEO back-ends may implement it for compatibility with OGC API clients and openEO clients don't need to request it.
tags:
- Capabilities
responses:
'200':
description: The URIs of all conformance classes supported by the server.
content:
application/json:
schema:
title: OGC Conformance Classes
type: object
required:
- conformsTo
properties:
conformsTo:
type: array
items:
type: string
format: uri
example: http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core
example:
conformsTo:
- 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core'
5XX:
$ref: '#/components/responses/server_error'
/collections:
get:
summary: Basic metadata for all datasets
operationId: list-collections
description: |-
Lists available collections with at least the required information.
It is **strongly RECOMMENDED** to keep the response size small by
omitting larger optional values from the objects in `collections` (e.g. the
`summaries` and `cube:dimensions` properties).
To get the full metadata for a collection clients MUST
request `GET /collections/{collection_id}`.
This endpoint is compatible with [STAC 0.9.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/v0.9.0/api-spec)
features / extensions and
[STAC extensions](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions)
can be implemented in addition to what is documented here.
tags:
- EO Data Discovery
security:
- {}
- Bearer: []
parameters:
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
description: Lists of collections and related links.
content:
application/json:
schema:
title: Collections
type: object
required:
- collections
- links
properties:
collections:
type: array
items:
$ref: '#/components/schemas/collection'
links:
$ref: '#/components/schemas/links_pagination'
example:
collections:
- stac_version: 0.9.0
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:
bbox:
- - -180
- -56
- 180
- 83
temporal:
interval:
- - '2015-06-23T00:00:00Z'
- '2019-01-01T00:00:00Z'
keywords:
- copernicus
- esa
- msi
- sentinel
providers:
- name: European Space Agency (ESA)
roles:
- producer
- licensor
url: >-
https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi
- name: openEO
roles:
- host
url: >-
https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2
links:
- rel: license
href: >-
https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf
- stac_version: 0.9.0
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:
bbox:
- - -180
- -90
- 180
- 90
temporal:
interval:
- - '2000-02-01T00:00:00Z'
- null
links:
- rel: license
href: 'https://example.openeo.org/api/collections/MOD09Q1/license'
links:
- rel: alternate
href: 'https://example.openeo.org/csw'
title: openEO catalog (OGC Catalogue Services 3.0)
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/collections/{collection_id}':
parameters:
- name: collection_id
in: path
description: Collection identifier
required: true
schema:
$ref: '#/components/schemas/collection_id'
get:
summary: Full metadata for a specific dataset
operationId: describe-collection
description: |-
Lists **all** information about a specific collection specified by the
identifier `collection_id`.
This endpoint is compatible with [STAC 0.9.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/v0.9.0/api-spec)
features / extensions and
[STAC extensions](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions)
can be implemented in addition to what is documented here.
tags:
- EO Data Discovery
security:
- {}
- Bearer: []
responses:
'200':
description: JSON object with the full collection metadata.
content:
application/json:
schema:
type: object
required:
- 'cube:dimensions'
- summaries
allOf:
- $ref: '#/components/schemas/collection'
example:
stac_version: 0.9.0
stac_extensions:
- collection-assets
- datacube
- scientific
- version
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.
license: proprietary
keywords:
- copernicus
- esa
- msi
- sentinel
version: 20200106A
providers:
- name: European Space Agency (ESA)
roles:
- producer
- licensor
url: >-
https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi
- name: Google
roles:
- host
url: >-
https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2
extent:
spatial:
bbox:
- - -180
- -56
- 180
- 83
temporal:
interval:
- - '2015-06-23T00:00:00Z'
- null
links:
- rel: license
href: https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf
type: application/pdf
- rel: about
href: https://earth.esa.int/web/sentinel/user-guides/sentinel-2-msi/product-types/level-1c
type: text/html
title: ESA Sentinel-2 MSI Level-1C User Guide
- rel: example
href: 'https://example.openeo.org/api/collections/Sentinel-2/examples/true-color.json'
type: application/json
title: Example Process for True-Color Visualization
- rel: example
href: 'https://example.openeo.org/api/collections/Sentinel-2/examples/ndvi.json'
type: application/json
title: Example Process for NDVI Calculation and Visualization
'cube:dimensions':
x:
type: spatial
axis: x
extent:
- -180
- 180
reference_system: 4326
y:
type: spatial
axis: 'y'
extent:
- -56
- 83
reference_system: 4326
t:
type: temporal
extent:
- '2015-06-23T00:00:00Z'
- null
step: null
bands:
type: bands
values:
- B1
- B2
- B3
- B4
- B5
- B6
- B7
- B8
- B8A
- B9
- B10
- B11
- B12
'sci:citation': 'Copernicus Sentinel data [Year]'
summaries:
'constellation':
- Sentinel-2
'platform':
- Sentinel-2A
- Sentinel-2B
'instruments':
- MSI
'eo:cloud_cover':
min: 0
max: 75
'sat:orbit_state':
- ascending
- descending
'eo:gsd':
- 10
- 20
- 60
'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
common_name: nir08
center_wavelength: 0.8648
gsd: 20
- name: B9
common_name: nir09
center_wavelength: 0.945
gsd: 60
- name: B10
common_name: cirrus
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
'proj:epsg':
min: 32601
max: 32660
assets:
thumbnail:
href: 'https://example.openeo.org/api/collections/Sentinel-2/thumbnail.png'
type: image/png
title: Preview
roles:
- thumbnail
inspire:
href: 'https://example.openeo.org/api/collections/Sentinel-2/inspire.xml'
type: application/xml
title: INSPIRE metadata
description: INSPIRE compliant XML metadata
roles:
- metadata
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
/processes:
get:
summary: Supported predefined processes
operationId: list-processes
description: >-
The request asks the back-end for available predefined processes and returns
detailed process descriptions, including parameters and return values.
tags:
- Process Discovery
security:
- {}
- Bearer: []
parameters:
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
description: Formal specification describing the supported predefined processes.
content:
application/json:
schema:
title: Processes
type: object
required:
- processes
- links
properties:
processes:
type: array
items:
title: Pre-Defined Process
description: A pre-defined process made available by the back-end.
type: object
required:
- id
- description
- parameters
- returns
allOf:
- $ref: '#/components/schemas/process'
links:
$ref: '#/components/schemas/links_pagination'
example:
processes:
- id: apply
summary: Apply a process to each pixel
description: >-
Applies a *unary* process to each pixel value in the data cube (i.e. a local operation). A unary process takes a single value and returns a single value, for example ``abs()`` or ``linear_scale_range()``.
categories:
- cubes
parameters:
- name: data
description: A data cube.
schema:
type: object
subtype: raster-cube
- name: process
description: 'A unary process to be applied on each value, may consist of multiple sub-processes.'
schema:
type: object
subtype: process-graph
parameters:
- name: x
description: The value to process.
schema:
description: Any data type.
returns:
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
- id: multiply
summary: Multiplication of two numbers
description: |-
Multiplies the two numbers `x` and `y` (*x * y*) and returns the computed product.
No-data values are taken into account so that `null` is returned if any element is such a value.
The computations follow [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) whenever the processing environment supports it.
categories:
- math
parameters:
- name: x
description: The multiplier.
schema:
type:
- number
- 'null'
- name: 'y'
description: The multiplicand.
schema:
type:
- number
- 'null'
returns:
description: The computed product of the two numbers.
schema:
type:
- number
- 'null'
exceptions:
MultiplicandMissing:
message: Multiplication requires at least two numbers.
examples:
- arguments:
x: 5
y: 2.5
returns: 12.5
- arguments:
x: -2
y: -4
returns: 8
- arguments:
x: 1
y: null
returns: null
links:
- rel: about
href: 'http://mathworld.wolfram.com/Product.html'
title: Product explained by Wolfram MathWorld
- rel: about
href: 'https://ieeexplore.ieee.org/document/8766229'
title: IEEE Standard 754-2019 for Floating-Point Arithmetic
links:
- rel: alternate
href: 'https://provider.com/processes'
type: text/html
title: HTML version of the processes
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
/udf_runtimes:
get:
summary: Supported UDF runtimes
operationId: list-udf-runtimes
description: >-
Returns the supported runtimes for user-defined functions (UDFs),
which includes either the programming languages including version
numbers and available libraries including version numbers or docker
containers.
tags:
- Capabilities
security:
- {}
- Bearer: []
responses:
'200':
description: Description of UDF runtime support
content:
application/json:
schema:
title: UDF Runtimes
type: object
description: >-
Map of available runtime environments. Each runtime
environment has a unique name, which is used as the property
key. The name is used in processes to select the runtime
environment for UDFs, so the names should be stable and
meaningful (see example). Runtime environments can be either a
programming language environment or Docker-based.
additionalProperties:
x-additionalPropertiesName: UDF Runtime name
oneOf:
- $ref: '#/components/schemas/udf_programming_language'
- $ref: '#/components/schemas/udf_docker'
example:
PHP7:
title: PHP v7.x
description: Just an example how to reference a docker image.
docker: openeo/udf-php7
default: latest
tags:
- latest
- 7.3.1
- '7.3'
- '7.2'
links:
- href: 'https://hub.docker.com/openeo/udf-php7/'
rel: about
R:
title: R v3.x for Statistical Computing
description: R programming language with `Rcpp` and `rmarkdown` extensions installed.
default: 3.5.2
versions:
3.1.0:
libraries:
Rcpp:
version: 1.0.10
links:
- href: >-
https://cran.r-project.org/web/packages/Rcpp/index.html
rel: about
rmarkdown:
version: 1.7.0
links:
- href: >-
https://cran.r-project.org/web/packages/rmarkdown/index.html
rel: about
3.5.2:
libraries:
Rcpp:
version: 1.2.0
links:
- href: >-
https://cran.r-project.org/web/packages/Rcpp/index.html
rel: about
rmarkdown:
version: 1.7.0
links:
- href: >-
https://cran.r-project.org/web/packages/rmarkdown/index.html
rel: about
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
/credentials/oidc:
get:
summary: OpenID Connect authentication
operationId: authenticate-oidc
description: >-
This endpoint lists the supported [OpenID
Connect](http://openid.net/connect/) providers (OP). OpenID Providers
MUST support [OpenID Connect
Discovery](http://openid.net/specs/openid-connect-discovery-1_0.html).
It is highly RECOMMENDED to implement OpenID Connect for public services
in favor of Basic authentication.
openEO clients MUST use the **access token** as part of the Bearer token
for authorization in subsequent API calls (see also the information
about Bearer tokens in this document). Clients MUST NOT use the id token
or the authorization code. The access token provided by an OpenID
Provider does not necessarily provide information about the issuer (i.e. the
OpenID provider) and therefore a prefix MUST be added to the Bearer
Token sent in subsequent API calls to protected endpoints. The Bearer
Token sent to protected endpoints MUST consist of the authentication
method (here `oidc`), the provider ID and the access token itself. All
separated by a forward slash `/`. The provider ID corresponds to the
value specified for `id` for each provider in the response body of this
endpoint. The header in subsequent API calls for a provider with `id`
`ms` would look as follows: `Authorization: Bearer oidc/ms/TOKEN`
(replace `TOKEN` with the actual access token received from the OpenID
Provider).
Back-ends MAY request user information ([including Claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims))
from the [OpenID Connect Userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
using the access token (without the prefix described above). Therefore,
both openEO client and openEO back-end are relying parties (clients) to
the OpenID Provider.
tags:
- Account Management
security:
- {}
responses:
'200':
description: Lists the the OpenID Providers.
content:
application/json:
schema:
title: OpenID Providers
type: object
required:
- providers
properties:
providers:
type: array
minItems: 1
items:
title: OpenID Provider
type: object
required:
- id
- issuer
- title
properties:
id:
type: string
description: >-
A **unique** identifier for the OpenID Provider to
be as prefix for the Bearer token.
pattern: '[\d\w]{1,20}'
issuer:
type: string
format: uri
description: >-
The [issuer location](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
(also referred to as 'authority' in some client libraries) is the URL of the
OpenID provider, which conforms to a set of rules:
1. After appending `/.well-known/openid-configuration` to the URL, a
[HTTP/1.1 GET
request](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest)
to the concatenated URL must return a [OpenID Discovery Configuration
Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).
The response provides all information required to authenticate using
OpenID Connect.
2. The URL MUST NOT contain a terminating forward slash `/`.
example: 'https://accounts.google.com'
scopes:
type: array
description: >-
A list of OpenID Connect scopes that the client MUST use.
If scopes are specified, the list MUST at least contain the `openid` scope.
items:
type: string
title:
type: string
description: >-
The name that is publicly shown in clients for this
OpenID provider.
description:
type: string
format: commonmark
description: |-
A description that explains how the authentication procedure works.
It should make clear how to register and get credentials. This should
include instruction on setting up `client_id`, `client_secret` and `redirect_uri`.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich
text representation.
links:
type: array
description: |-
Links related to this provider, for example a
help page or a page to register a new user account.
For relation types see the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '#/components/schemas/link'
example:
providers:
- id: google
issuer: 'https://accounts.google.com'
title: Google
description: Login with your Google Account.
scopes:
- openid
- profile
- email
- earthengine
- id: ms
issuer: 'https://login.microsoftonline.com/example-tenant/v2.0'
title: Microsoft
description: Login with your Microsoft or Skype Account.
scopes: []
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
/credentials/basic:
get:
summary: HTTP Basic authentication
operationId: authenticate-basic
description: >-
This request checks the credentials provided through [HTTP Basic
Authentication according to RFC
7617](https://tools.ietf.org/html/rfc7617) and returns an access token
for valid credentials.
The credentials (username and password) must be sent in the HTTP header
`Authorization` with type `Basic` and the Base64 encoded string
consisting of username and password separated by a double colon `:`. The
header would look as follows for username `user` and password `pw`:
`Authorization: Basic dXNlcjpwdw==`.
The access token has to be used in the Bearer token for authorization in
subsequent API calls (see also the information about Bearer tokens in
this document). The access token returned by this request MUST NOT be
provided with `basic//` prefix, but the Bearer Token sent in subsequent
API calls to protected endpoints MUST be prefixed with `basic//`. The
header in subsequent API calls would look as follows: `Authorization:
Bearer basic//TOKEN` (replace `TOKEN` with the actual access token).
It is RECOMMENDED to implement this authentication method for non-public
services only.
tags:
- Account Management
security:
- Basic: []
responses:
'200':
description: Credentials are correct and authentication succeeded.
content:
application/json:
schema:
title: HTTP Basic Access Token
type: object
required:
- access_token
properties:
access_token:
description: >-
The access token (without `basic//` prefix) to be used in
the Bearer token for authorization in subsequent API
calls.
type: string
example: b34ba2bdf9ac9ee1
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
/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 user-defined process is schematically correct and the
processes are supported by the back-end. It MUST also checks the
parameter values against the schema, but checking whether the values 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.
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.
/result:
post:
summary: Process and download data synchronously
operationId: compute-result
description: >-
A user-defined process will be executed directly and the result will be
downloaded in the format specified in the process graph. This endpoint
can be used to generate small previews or test user-defined processes before
starting a batch job.
Timeouts on either client- or server-side are to be expected for complex
computations. Back-ends MAY send the openEO error `ProcessGraphComplexity`
immediately if the computation is expected to time out. Otherwise requests
MAY time-out after a certain amount of time by sending openEO error `RequestTimeout`.
A header named `OpenEO-Costs` MAY be sent with all responses, which MUST
include the costs for processing and downloading the data. Additionally,
a link to a log file MAY be sent in the header.
tags:
- Data Processing
security:
- Bearer: []
responses:
'200':
description: Result data in the requested output format
headers:
Content-Type:
description: >-
The appropriate media (MIME) type for the requested output
format MUST be sent.
schema:
type: string
OpenEO-Costs:
description: MAY include the costs for processing and downloading the data.
schema:
$ref: '#/components/schemas/money'
Link:
description: >-
The header MAY indicate a link to a log file generated by the request. If provided, the link MUST be serialized according to [RFC 8288](https://tools.ietf.org/html/rfc8288#section-3) and MUST use the relation type `monitor`. The link MUST follow the specifications for the links `GET /jobs/{job_id}/logs` and `GET /services/{service_id}/logs`, except that is MUST NOT accept any parameters (limit/offset). Therefore, the link MUST be accessible with HTTP GET, MUST be secured using a Bearer token and MUST follow the corresponding request body schema.
schema:
type: string
pattern: ^<[^>]+>;\s?rel="monitor"
example: <https://example.openeo.org/api/logs/258489231>; rel="monitor"
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
requestBody:
description: 'Specifies the job details, e.g. the user-defined process and billing details.'
required: true
content:
application/json:
schema:
title: Synchronous Result Request
type: object
required:
- process
properties:
process:
$ref: '#/components/schemas/process_graph_with_metadata'
budget:
$ref: '#/components/schemas/budget'
plan:
$ref: '#/components/schemas/billing_plan_defaultable'
/process_graphs:
get:
summary: List all user-defined processes
operationId: list-custom-processes
description: |-
This service 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 secondary web service clients MUST
request `GET /services/{service_id}`.
tags:
- User-Defined Processes
- Process Discovery
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'
'/process_graphs/{process_graph_id}':
parameters:
- name: process_graph_id
in: path
description: 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: Returns all information about a user-defined process, including its process graph.
tags:
- User-Defined Processes
- Process Discovery
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't
be changed for stored user-defined processes.
The id must be unique for the authenticated user, including all
pre-defined processes by the back-end.
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 don't 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'
/service_types:
get:
summary: Supported secondary web service protocols
operationId: list-service-types
description: |-
The request will ask the back-end for supported secondary web service
protocols, e.g. WMS or WCS. The response is an object of all available
secondary web service protocols,supported configuration settings and
process parameters.
Configuration settings for the service need to be defined upon
creation of a service and the service will be set up accordingly.
A list of process parameters is also available. This parameters can
be used by users in a user-defined process that is used to compute web service
results. The objects can directly be used inside the process graph with
a `from_parameter` reference. Such parameters are usually things that
have to be injected into the user-defined process from the context of the web
service during runtime. For example, a map service such as a WMS would
need to inject the spatial extent into the user-defined process so that the
back-end can compute the corresponding tile correctly.
To improve interoperability between back-ends common names for the
services SHOULD be used, e.g. the abbreviations used in the official
[OGC Schema Repository](http://schemas.opengis.net/) for the respective
services.
Service names are allowed to be *case insensitive* throughout the API.
tags:
- Capabilities
- Secondary Services
security:
- {}
- Bearer: []
responses:
'200':
description: >-
An object with a map containing all service names as keys and an
object that defines supported configuration settings and process parameters.
content:
application/json:
schema:
title: Service Types
type: object
description: Map of supported secondary web services.
additionalProperties:
x-additionalPropertiesName: Service Name
title: Service Type
type: object
properties:
title:
$ref: '#/components/schemas/object_title'
description:
$ref: '#/components/schemas/description'
configuration:
title: Service Configuration
description: Map of supported configuration settings made available to the creator the service.
type: object
additionalProperties:
$ref: '#/components/schemas/argument'
process_parameters:
title: Process Parameters
description: List of parameters made available to user-defined processes.
type: array
items:
$ref: '#/components/schemas/parameter'
links:
description: |-
Links related to this service type, e.g. more
information about the configuration settings and process parameters.
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:
WMS:
title: OGC Web Map Service
configuration:
version:
type: string
description: The WMS version offered to consumers of the service.
default: 1.3.0
enum:
- 1.1.1
- 1.3.0
process_parameters:
- name: layer
description: The layer name.
schema:
type: string
default: roads
- name: spatial_extent_west
description: The lower left corner for coordinate axis 1 of the extent currently shown to the consumer.
schema:
type: number
- name: spatial_extent_south
description: The lower left corner for coordinate axis 2 of the extent currently shown to the consumer.
schema:
type: number
- name: spatial_extent_east
description: The upper right corner for coordinate axis 1 of the extent currently shown to the consumer.
schema:
type: number
- name: spatial_extent_north
description: The upper right corner for coordinate axis 2 of the extent currently shown to the consumer.
schema:
type: number
links:
- href: 'https://www.opengeospatial.org/standards/wms'
rel: about
title: OGC Web Map Service Standard
WFS:
title: OGC Web Feature Service
description: >-
Exposes a OGC-compliant WFS service.
Note: This is NOT compliant to OGC API - Features.
configuration:
version:
type: string
description: The WFS version offered to consumers of the service.
default: 2.0.0
enum:
- 1.0.0
- 1.1.0
- 2.0.0
maxFeatures:
type: integer
description: Maximum number of features (since WFS 2.0.0 only).
default: 10000
minimum: 1
maximum: 100000
links:
- href: 'https://www.opengeospatial.org/standards/wfs'
rel: about
title: OGC Web Feature Service Standard
4XX:
$ref: '#/components/responses/client_error'
5XX:
$ref: '#/components/responses/server_error'
/services:
get:
summary: List all web services
operationId: list-services
description: |-
Requests to this endpoint will list all secondary web services submitted
by a user.
It is **strongly RECOMMENDED** to keep the response size small by
omitting all optional non-scalar values from objects in`services`
(i.e. the `process`, `configuration` and `attributes` properties).
To get the full metadata for a secondary web service clients MUST
request `GET /services/{service_id}`.
tags:
- Secondary Services
security:
- Bearer: []
parameters:
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
description: Array of secondary web service descriptions
content:
application/json:
schema:
title: Secondary Web Services
type: object
required:
- services
- links
properties:
services:
type: array
items:
$ref: '#/components/schemas/service'
links:
$ref: '#/components/schemas/links_pagination'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
post:
summary: Publish a new service
operationId: create-service
description: >-
Calling this endpoint will create a secondary web service such as WMTS,
TMS or WCS. The underlying data is processes on-demand, but a process
graph may simply access results from a batch job. Computations should be
performed in the sense that it is only evaluated for the requested
spatial / temporal extent and resolution.
**Note:** Costs incurred by shared secondary web services are usually
paid by the owner, but this depends on the service type and whether it
supports charging fees or not.
tags:
- Secondary Services
security:
- Bearer: []
responses:
'201':
description: The service has been created successfully.
headers:
Location:
required: true
schema:
description: |-
Absolute URL to the newly created service.
The URL points to the metadata endpoint
`GET /services/{service_id}` with the `{service_id}` being the
unique identifier (ID) of the created service.
MUST NOT point to the actual instance (e.g. WMTS base URL) of
the service. The URL to the instance is made available by the
metadata endpoint in the property `url`.
format: uri
type: string
example: 'https://example.openeo.org/api/services/123'
OpenEO-Identifier:
required: true
schema:
$ref: '#/components/schemas/service_id'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
requestBody:
required: true
content:
application/json:
schema:
title: Store Secondary Web Service Request
type: object
required:
- type
- process
properties:
title:
$ref: '#/components/schemas/eo_title'
description:
$ref: '#/components/schemas/eo_description'
process:
$ref: '#/components/schemas/process_graph_with_metadata'
type:
$ref: '#/components/schemas/service_type'
enabled:
$ref: '#/components/schemas/service_enabled'
configuration:
$ref: '#/components/schemas/service_configuration'
plan:
$ref: '#/components/schemas/billing_plan_defaultable'
budget:
$ref: '#/components/schemas/budget'
description: The base data for the secondary web service to create
'/services/{service_id}':
parameters:
- $ref: '#/components/parameters/service_id'
patch:
summary: Modify a service
operationId: update-service
description: >-
Calling this endpoint will change the specified secondary web service,
but maintain its identifier. Changes can be grouped in a single request.
To change the service type create a new service.
tags:
- Secondary Services
security:
- Bearer: []
responses:
'204':
description: Changes to the service were applied successfully.
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
requestBody:
required: true
content:
application/json:
schema:
title: Update Secondary Web Service Request
type: object
properties:
title:
$ref: '#/components/schemas/eo_title'
description:
$ref: '#/components/schemas/eo_description'
process:
$ref: '#/components/schemas/process_graph_with_metadata'
enabled:
$ref: '#/components/schemas/service_enabled'
configuration:
$ref: '#/components/schemas/service_configuration'
plan:
$ref: '#/components/schemas/billing_plan_defaultable'
budget:
$ref: '#/components/schemas/budget'
description: The data to change for the specified secondary web service.
get:
summary: Full metadata for a service
operationId: describe-service
description: >-
Requests to this endpoint will return JSON description of the secondary
web service.
tags:
- Secondary Services
security:
- Bearer: []
responses:
'200':
description: Details of the created service
content:
application/json:
schema:
type: object
required:
- process
- configuration
- attributes
allOf:
- $ref: '#/components/schemas/service'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
delete:
summary: Delete a service
operationId: delete-service
description: >-
Calling this endpoint will stop a given secondary web service to access
result data.
tags:
- Secondary Services
security:
- Bearer: []
responses:
'204':
description: The service has been successfully deleted.
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/services/{service_id}/logs':
get:
summary: Logs for a secondary service
operationId: debug-service
description: >-
Shows log entries for the secondary service, usually for debugging purposes.
Back-ends can log any information that may be relevant for a user.
Users can log information during data processing using respective
processes such as `debug`.
If requested consecutively while the secondary service is enabled, it is
RECOMMENDED that clients use the offset parameter to get only the entries
they have not received yet.
While pagination itself is OPTIONAL, the `offset` parameter is REQUIRED
to be implemented by back-ends.
tags:
- Secondary Services
security:
- Bearer: []
parameters:
- $ref: '#/components/parameters/service_id'
- $ref: '#/components/parameters/log_offset'
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
$ref: '#/components/responses/logs'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
/jobs:
get:
summary: List all batch jobs
operationId: list-jobs
description: |-
Requests to this endpoint will list all batch jobs submitted by a user.
It is **strongly RECOMMENDED** to keep the response size small by
omitting all optional non-scalar values from objects in `jobs` (i.e. the `process` property).
To get the full metadata for a job clients MUST request `GET /jobs/{job_id}`.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
parameters:
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
description: Array of job descriptions
content:
application/json:
schema:
title: Batch Jobs
type: object
required:
- jobs
- links
properties:
jobs:
type: array
items:
$ref: '#/components/schemas/batch_job'
links:
$ref: '#/components/schemas/links_pagination'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
post:
summary: Create a new batch job
operationId: create-job
description: >-
Creates a new batch processing task (job) from one or more (chained)
processes at the back-end.
Processing the data doesn't start yet. The job status gets initialized
as `created` by default.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
responses:
'201':
description: The batch job has been created successfully.
headers:
Location:
required: true
schema:
description: |-
Absolute URL to the newly created batch job.
The URL points to the metadata endpoint
`GET /jobs/{job_id}` with the `{job_id}` being the
unique identifier (ID) of the created batch job.
format: uri
type: string
example: 'https://example.openeo.org/api/jobs/123'
OpenEO-Identifier:
required: true
schema:
$ref: '#/components/schemas/job_id'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
requestBody:
required: true
content:
application/json:
schema:
title: Store Batch Job Request
type: object
required:
- process
properties:
title:
$ref: '#/components/schemas/eo_title'
description:
$ref: '#/components/schemas/eo_description'
process:
$ref: '#/components/schemas/process_graph_with_metadata'
plan:
$ref: '#/components/schemas/billing_plan_defaultable'
budget:
$ref: '#/components/schemas/budget'
description: 'Specifies the job details, e.g. the user-defined process and billing details.'
'/jobs/{job_id}':
parameters:
- $ref: '#/components/parameters/job_id'
patch:
summary: Modify a batch job
operationId: update-job
description: >-
Modifies an existing job at the back-end but maintains the identifier.
Changes can be grouped in a single request.
Jobs can only be modified when the job is not queued or running.
Otherwise requests to this endpoint MUST be rejected with openEO error
`JobLocked`.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
responses:
'204':
description: Changes to the job applied successfully.
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
requestBody:
required: true
content:
application/json:
schema:
title: Update Batch Job Request
type: object
properties:
title:
$ref: '#/components/schemas/eo_title'
description:
$ref: '#/components/schemas/eo_description'
process:
$ref: '#/components/schemas/process_graph_with_metadata'
plan:
$ref: '#/components/schemas/billing_plan_defaultable'
budget:
$ref: '#/components/schemas/budget'
description: Specifies the job details to update.
get:
summary: Full metadata for a batch job
operationId: describe-job
description: Returns all information about a submitted batch job.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
responses:
'200':
description: Full job information.
content:
application/json:
schema:
type: object
required:
- process
allOf:
- $ref: '#/components/schemas/batch_job'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
delete:
summary: Delete a batch job
operationId: delete-job
description: >-
Deletes all data related to this job. Computations are stopped and
computed results are deleted. This job won't generate additional costs
for processing.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
responses:
'204':
description: The job has been successfully deleted.
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/jobs/{job_id}/estimate':
get:
summary: Get an estimate for a batch job
operationId: estimate-job
description: >-
Clients can ask for an estimate for a batch job. Back-ends can decide to
either calculate the duration, the costs, the size or a combination of
them. This MUST be the upper limit of the incurring costs. Clients can
be charged less than specified, but never more. Back-end providers MAY
specify an expiry time for the estimate. Starting to process data
afterwards MAY be charged at a higher cost. Costs MAY NOT include
downloading costs. This can be indicated with the `downloads_included`
flag.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
parameters:
- $ref: '#/components/parameters/job_id'
responses:
'200':
description: >-
The estimated costs with regard to money, processing time and
storage capacity. At least one of `costs`, `duration` or `size` MUST
be provided.
content:
application/json:
schema:
title: Batch Job Estimate
type: object
properties:
costs:
$ref: '#/components/schemas/money'
duration:
type: string
description: >-
Estimated duration for the operation. Duration MUST be
specified as a ISO 8601 duration.
example: P1Y2M10DT2H30M
size:
type: integer
description: >-
Estimated required storage capacity, i.e. the size of the
generated files. Size MUST be specified in bytes.
example: 157286400
downloads_included:
type: integer
nullable: true
description: >-
Specifies how many full downloads of the processed data
are included in the estimate. Set to `null` for unlimited
downloads, which is also the default value.
example: 5
default: null
expires:
type: string
format: date-time
description: >-
Time until which the estimate is valid, formatted as a
[RFC 3339](https://www.ietf.org/rfc/rfc3339) date-time.
example: '2020-11-01T00:00:00Z'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/jobs/{job_id}/logs':
get:
summary: Logs for a batch job
operationId: debug-job
description: |-
Shows log entries for the batch job, usually for debugging purposes.
Back-ends can log any information that may be relevant for a user.
Users can log information during data processing using respective
processes such as `debug`.
If requested consecutively while a job is running, it is RECOMMENDED
that clients use the offset parameter to get only the entries they have
not received yet.
While pagination itself is OPTIONAL, the `offset` parameter is REQUIRED
to be implemented by back-ends.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
parameters:
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/log_offset'
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
$ref: '#/components/responses/logs'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/jobs/{job_id}/results':
parameters:
- $ref: '#/components/parameters/job_id'
get:
summary: Download results for a completed batch job
operationId: list-results
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.9.0)](https://github.com/radiantearth/stac-spec/tree/v0.9.0/item-spec)
if it has spatial and temporal references included.
URL 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.
If processing has not finished yet requests to this endpoint MUST be
rejected with openEO error `JobNotFinished`.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
responses:
'200':
description: >-
Valid download links have been returned. The download links doesn't
necessarily need to be located under the API base url.
headers:
OpenEO-Costs:
description: >-
Specifies the costs for fully downloading the data **once**,
i.e. this header MAY change in subsequent calls. It MUST be set
to `0` if the requester is the owner of the job and still has
free downloads included in his processing charges estimated by
`GET /jobs/{job_id}/estimate`.
If a requester other than the owner is requesting the data of a shared job this header indicates the costs for the requester.
schema:
$ref: '#/components/schemas/money'
content:
application/json:
schema:
$ref: '#/components/schemas/batch_job_result'
application/geo+json:
schema:
$ref: '#/components/schemas/batch_job_result'
'424':
description: >-
The request can't be fulfilled as the batch job failed. This request
will deliver the last error message that was produced by the batch job.
This HTTP code MUST be sent only when the job `status` is `error`.
content:
application/json:
schema:
$ref: '#/components/schemas/log_entry'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
post:
summary: Start processing a batch job
operationId: start-job
description: >-
Adds a batch job to the processing queue to compute the results.
The result will be stored in the format specified in the process graph.
To specify the format use a process such as `save_result`.
This endpoint has no effect if the job status is already `queued` or
`running`. In particular, it doesn't restart a running job. Processing
MUST be canceled before to restart it.
The job status is set to `queued`, if processing doesn't start
instantly.
* Once the processing starts the status is set to `running`.
* Once the data is available to download the status is set to
`finished`.
* Whenever an error occurs during processing, the status must be set to
`error`.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
responses:
'202':
description: The creation of the resource has been queued successfully.
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
delete:
summary: Cancel processing a batch job
operationId: stop-job
description: >-
Cancels all related computations for this job at the back-end. It will
stop generating additional costs for processing.
A subset of processed results may be available for downloading depending
on the state of the job as it was canceled. Finished results MUST NOT be
deleted until the job is deleted or job processing is started again.
This endpoint only has an effect if the job status is `queued` or
`running`.
The job status is set to `canceled` if the status was `running`
beforehand and partial or preliminary results are available to be
downloaded. Otherwise the status is set to `created`.
tags:
- Data Processing
- Batch Jobs
security:
- Bearer: []
responses:
'204':
description: Processing the job has been successfully canceled.
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/files':
get:
summary: List all files in the workspace
operationId: list-files
description: >-
This service lists all user-uploaded files that are stored at the
back-end.
tags:
- File Storage
security:
- Bearer: []
parameters:
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
description: >-
Flattened file tree with path relative to the user's root directory
and some basic properties such as the file size and the timestamp of
the last modification. All properties except the name are optional.
Folders MUST NOT be listed separately so each element in the list
MUST be a downloadable file.
content:
application/json:
schema:
title: Workspace Files
type: object
required:
- files
- links
properties:
files:
type: array
items:
$ref: '#/components/schemas/file'
links:
$ref: '#/components/schemas/links_pagination'
example:
files:
- path: test.txt
size: 182
modified: '2015-10-20T17:22:10Z'
- path: test.tif
size: 183142
modified: '2017-01-01T09:36:18Z'
- path: >-
Sentinel2/S2A_MSIL1C_20170819T082011_N0205_R121_T34KGD_20170819T084427.zip
size: 4183353142
modified: '2018-01-03T10:55:29Z'
links: []
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/files/{path}':
parameters:
- name: path
in: path
description: "Path of the file, relative to the user's root directory.\r\n\r\n**Note:** Folder and file names in the path MUST be url-encoded. The path separator `/` and the file extension separator `.` MUST NOT be url-encoded. This may be shown incorrectly in rendered versions due to [OpenAPI 3 not supporting path parameters which contain slashes](https://github.com/OAI/OpenAPI-Specification/issues/892)."
required: true
schema:
type: string
examples:
normal:
description: >-
A path without special chars. It describes a file `europe.geojson`
in a folder called `borders`.
value: borders/europe.geojson
specialchars:
description: >-
A path with special chars. It describes a file `münster.shp` in
folders called `europe` and `österreich`.
value: europe/%C3%B6sterreich/m%C3%BCnster.shp
get:
summary: Download a file from the workspace
operationId: download-file
description: >-
This service downloads a user files identified by its path relative to
the user's root directory.
If a folder is specified as path a `FileOperationUnsupported` error MUST
be sent as response.
tags:
- File Storage
security:
- Bearer: []
responses:
'200':
description: A file from the workspace.
content:
application/octet-stream:
schema:
type: string
format: binary
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
put:
summary: Upload a file to the workspace
operationId: upload-file
description: >-
This service uploads a new or updates an existing file at a given path.
Folders are created once required by a file upload. Empty folders can't
be created.
tags:
- File Storage
security:
- Bearer: []
responses:
'200':
description: The file has been uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/file'
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
delete:
summary: Delete a file from the workspace
operationId: delete-file
description: >-
This service deletes an existing user-uploaded file specified by its
path. Resulting empty folders MUST be deleted automatically.
Back-ends MAY support deleting folders including its files and
sub-folders. If not supported by the back-end a
`FileOperationUnsupported` error MUST be sent as response.
tags:
- File Storage
security:
- Bearer: []
responses:
'204':
description: The file has been successfully deleted at the back-end.
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
/me:
get:
summary: Information about the authenticated user
operationId: describe-account
description: >-
This endpoint always returns the user id and MAY return the disk quota
available to the user. It MAY also return links related to user management
and the user profile, e.g. where payments are handled or the user profile
could be edited.
For back-ends that involve accounting, this service MAY also return the
currently available money or credits in the currency the back-end is
working with.
This endpoint MAY be extended to fulfil the specification of the [OpenID
Connect UserInfo
Endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
tags:
- Account Management
security:
- Bearer: []
responses:
'200':
description: Information about the logged in user.
content:
application/json:
schema:
title: User Data
description: >-
Holds user information. If no budget or storage limit applies
to the user account the corresponding properties MUST be set
to null.
type: object
required:
- user_id
properties:
user_id:
$ref: '#/components/schemas/user_id'
name:
type: string
description: >-
The user name, a human-friendly displayable name. Could be
the user's real name or a nickname.
storage:
title: User Storage
description: Information about the storage space available to the user.
type: object
nullable: true
required:
- free
- quota
properties:
free:
type: integer
description: >-
Free storage space in bytes, which is still available
to the user. Effectively, this is the disk quota minus
the used space by the user, e.g. user-uploaded files
and job results.
example: 536870912
quota:
type: integer
description: >-
Maximum storage space (disk quota) in bytes available
to the user.
example: 1073741824
budget:
$ref: '#/components/schemas/budget'
links:
description: |-
Links related to the user profile, e.g. where payments
are handled or the user profile could be edited.
It is RECOMMENDED to provide links with the following `rel` (relation) types:
1. `payment`: A page where users can recharge their user account with money or credits.
2. `edit-form`: Points to a page where the user can edit his user profile.
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'
example:
- href: 'https://example.openeo.org/john_doe/payment/'
rel: payment
- href: 'https://example.openeo.org/john_doe/edit/'
rel: edit-form
- href: 'https://example.openeo.org/john_doe/'
rel: alternate
type: text/html
title: User profile
- href: 'https://example.openeo.org/john_doe.vcf'
rel: alternate
type: text/vcard
title: vCard of John Doe
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
components:
schemas:
udf_runtime:
type: object
properties:
title:
$ref: '#/components/schemas/object_title'
description:
$ref: '#/components/schemas/description'
default:
type: string
links:
type: array
description: |-
Links related to this runtime, e.g. external documentation.
It is highly RECOMMENDED to provide at least links with
the following `rel` (relation) types:
1. `about`: A resource that further explains the runtime,
e.g. a user guide or the documentation.
For additional relation types see also the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '#/components/schemas/link'
udf_programming_language:
title: Programming language
allOf:
- $ref: '#/components/schemas/udf_runtime'
- required:
- default
- versions
properties:
default:
description: The default version. MUST be one of the keys in the `versions` object.
versions:
title: Programming language versions
description: Versions available for the programming language.
type: object
additionalProperties:
x-additionalPropertiesName: Programming Language Version
title: Programming language version
type: object
required:
- libraries
properties:
libraries:
description: >-
Map of installed libraries, modules, packages
or extensions for the programming language.
The names of them are used as the property keys.
additionalProperties:
x-additionalPropertiesName: Library Name
title: Programming language library
type: object
required:
- version
properties:
version:
type: string
description: Version number of the library.
deprecated:
type: boolean
default: false
description: |-
Specifies that the library 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.
A link with relation type `latest-version` SHOULD be added to the
`links` and MUST refer to the library or library version that can be
used instead.
links:
type: array
description: |-
Additional links related to this library,
e.g. external documentation for this library.
It is highly RECOMMENDED to provide links with
the following `rel` (relation) types:
1. `about`: A resource that further explains the library,
e.g. a user guide or the documentation.
2. `latest-version`: If a library has been marked as deprecated,
a link should point to either a new library replacing the deprecated
library or a latest version of the library available at the back-end.
For additional relation types see also the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '#/components/schemas/link'
udf_docker:
title: Docker container
allOf:
- $ref: '#/components/schemas/udf_runtime'
- required:
- docker
- default
- tags
properties:
docker:
type: string
description: >-
Identifier of a Docker image on Docker Hub or a
private repository, i.e. the docker image name.
default:
description: The default tag. MUST be one of the values in the `tags` array.
tags:
type: array
description: The docker tags that are supported.
minItems: 1
items:
type: string
batch_job_result:
title: Batch Job Results Response as STAC Item
type: object
required:
- stac_version
- id
- type
- geometry
- properties
- assets
- links
properties:
stac_version:
$ref: '#/components/schemas/stac_version'
stac_extensions:
$ref: '#/components/schemas/stac_extensions'
id:
$ref: '#/components/schemas/job_id'
type:
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
geometry:
description: |-
Defines the full footprint of the asset represented by this item as
GeoJSON Geometry.
Results without a known location can set this value to `null`.
nullable: true
type: object
allOf:
- $ref: '#/components/schemas/GeoJsonGeometry'
example:
type: Polygon
coordinates:
- - - -180
- -90
- - 180
- -90
- - 180
- 90
- - -180
- 90
- - -180
- -90
properties:
type: object
title: Item Properties
description: >-
MAY contain any additional properties, e.g. other STAC Item
properties, properties from STAC extensions or custom properties.
required:
- datetime
additionalProperties: true
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.
If this field is set to `null` (usually for larger time ranges),
it is STRONGLY RECOMMENDED to specify both `start_datetime` and
`end_datetime` for STAC compliance.
type: string
format: date-time
nullable: true
start_datetime:
type: string
format: date-time
description: >-
For time series: The first or start date and time for the data,
in UTC. Formatted as a [RFC
3339](https://www.ietf.org/rfc/rfc3339) date-time.
end_datetime:
type: string
format: date-time
description: >-
For time series: The last or end date and time for the data, in
UTC. Formatted as a [RFC 3339](https://www.ietf.org/rfc/rfc3339)
date-time.
title:
$ref: '#/components/schemas/eo_title'
description:
$ref: '#/components/schemas/eo_description'
license:
$ref: '#/components/schemas/stac_license'
providers:
$ref: '#/components/schemas/stac_providers'
created:
$ref: '#/components/schemas/created'
updated:
$ref: '#/components/schemas/updated'
expires:
type: string
format: date-time
description: >-
Time until which the assets are accessible, in UTC. Formatted as
a [RFC 3339](https://www.ietf.org/rfc/rfc3339) date-time.
example: '2020-11-01T00:00:00Z'
assets:
type: object
title: Assets
description: |-
Dictionary of asset objects for data that can be downloaded, each with a
unique key. The keys MAY be used by clients as file names.
It is RECOMMENDED to link to a copy of this STAC Item with relative links in the assets,
which allows users to easily publish their processed data with a basic set of metadata.
additionalProperties:
$ref: '#/components/schemas/asset'
example:
preview.png:
href: 'https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/preview.png'
type: image/png
title: Thumbnail
roles:
- thumbnail
process.json:
href: 'https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/process.json'
type: application/json
title: Original Process
roles:
- process
- reproduction
1.tif:
href: 'https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/1.tif'
type: image/tiff; application=geotiff
title: Band 1
roles:
- data
2.tif:
href: 'https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/2.tif'
type: image/tiff; application=geotiff
title: Band 2
roles:
- data
inspire.xml:
href: 'https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/inspire.xml'
type: application/xml
title: INSPIRE metadata
description: INSPIRE compliant XML metadata
roles:
- metadata
links:
type: array
description: >-
Links related to this batch job result, e.g. a link to an
invoice, additional log files or external documentation.
The links MUST NOT contain links to the processed and
downloadable data. Instead specify these in the `assets` property.
Clients MUST NOT download the data referenced in the links by
default.
For relation types see the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '#/components/schemas/link'
file_format:
x-additionalPropertiesName: File Format Name
title: File Format
type: object
description: Describes a specific file format.
required:
- gis_data_types
properties:
title:
$ref: '#/components/schemas/object_title'
description:
$ref: '#/components/schemas/description'
gis_data_types:
type: array
description: Specifies the supported GIS spatial data type for this format.
items:
enum:
- raster
- vector
- table
- other
parameters:
title: File Format Parameters
description: Specifies the supported parameters for this file format.
type: object
additionalProperties:
$ref: '#/components/schemas/argument'
links:
type: array
description: |-
Links related to this file format, e.g. external documentation.
For relation types see the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '#/components/schemas/link'
production:
type: boolean
description: >-
Specifies whether the implementation is ready to be used in production
use (`true`) or not (`false`).
Clients SHOULD only connect to non-production implementations if the
user explicitly confirmed to use a non-production implementation.
This flag is part of `GET /.well-known/openeo` and `GET /`.
It must be used consistently in both endpoints.
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'
link:
title: Link
description: >-
A link to another resource on the web. Bases on [RFC
5899](https://tools.ietf.org/html/rfc5988).
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://example.openeo.org'
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
asset:
title: STAC Asset
type: object
required:
- href
properties:
href:
title: Asset location
description: >-
URL to the downloadable asset.
The URLs SHOULD be available without authentication so that
external clients can download them easily.
If the data is confidential, signed URLs SHOULD be used to protect
against unauthorized access from third parties.
type: string
title:
description: The displayed title for clients and users.
type: string
description:
type: string
format: commonmark
description: |-
Multi-line description to explain the asset.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich
text representation.
type:
title: Media Type
description: Media type of the asset.
type: string
example: image/tiff; application=geotiff
roles:
type: array
items:
type: string
description: |-
Purposes of the asset. Can be any value, but commonly used values are:
* `thumbnail`: A visualization of the data, usually a lower-resolution true color image in JPEG or PNG format.
* `reproducibility`: Information how the data was produced and/or can be reproduced, e.g. the process graph used to compute the data in JSON format.
* `data`: The computed data in the format specified by the user in the process graph (applicable in `GET /jobs/{job_id}/results` only).
* `metadata`: Additional metadata available for the computed data.
example:
- data
money:
description: >-
An amount of money or credits. The value MUST be specified in the
currency the back-end is working with. The currency can be retrieved by
calling `GET /`. If no currency is set, this field MUST be `null`.
type: number
example: 12.98
nullable: true
default: null
budget:
type: number
nullable: true
default: null
description: >-
Maximum amount of costs the request is allowed to produce. The value
MUST be specified in the currency the back-end is working with. The
currency can be retrieved by calling `GET /`. If no currency is set,
this field MUST NOT be a number.
If possible, back-ends SHOULD reject jobs with openEO error
`PaymentRequired` if the budget is too low to process the request
completely. Otherwise, when reaching the budget jobs MAY try to return
partial results if possible. Otherwise the request and results are
discarded. Users SHOULD be warned by clients that reaching the budget
MAY discard the results and that setting this value should be
well-wrought.
Setting the budget to `null` means there is no specified budget.
example: 100
billing_plan_defaultable:
type: string
description: >-
The billing plan to process and charge the job with.
The plans and the default plan can be retrieved by calling `GET /`.
Billing plans MUST be accepted *case insensitive*. Billing plans not on
the list of available plans MUST be rejected with openEO error
`BillingPlanInvalid`.
If no billing plan is specified by the client, the server MUST default
to the default billing plan in `GET /`. If the default billing plan of
the provider changes, the job or service MUST not be affected by the
change, i.e. the default plan which is valid during job or service
creation must be permanently assigned to the job or service until the
client requests to change it.
example: free
nullable: true
billing_plan:
type: string
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:
title: Collection
type: object
required:
- stac_version
- id
- description
- license
- extent
- links
properties:
stac_version:
$ref: '#/components/schemas/stac_version'
stac_extensions:
$ref: '#/components/schemas/stac_extensions'
id:
$ref: '#/components/schemas/collection_id'
title:
type: string
description: A short descriptive one-line title for the collection.
description:
type: string
format: commonmark
description: >-
Detailed multi-line description to explain the collection.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
rich text representation.
keywords:
type: array
description: List of keywords describing the collection.
items:
type: string
version:
type: string
description: |-
Version of the collection.
This property REQUIRES to add `version` to the list
of `stac_extensions`.
deprecated:
type: boolean
default: false
description: |-
Specifies that the collection is deprecated with the potential to
be removed. It should be transitioned out of usage as soon as
possible and users should refrain from using it in new projects.
A link with relation type `latest-version` SHOULD be added to the
links and MUST refer to the collection that can be used instead.
This property REQUIRES to add `version` to the list
of `stac_extensions`.
license:
$ref: '#/components/schemas/stac_license'
providers:
$ref: '#/components/schemas/stac_providers'
extent:
type: object
title: 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:
title: Collection Spatial Extent
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.
If multiple areas are provided, the union of the bounding
boxes describes the spatial extent.
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.
If a feature has multiple spatial geometry properties, it
is the decision of the server whether only a single spatial geometry
property is used to determine the extent or all relevant geometries.
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
temporal:
title: Collection Temporal Extent
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.
The value `null` is supported and indicates an open time
interval.
In the Core only a single time interval is supported.
Extensions may support
multiple intervals. If multiple intervals are provided, the
union of the
intervals 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
links:
description: >-
Links related to this collection.
Could reference to licensing information, other meta data formats with
additional information or a preview image.
It is RECOMMENDED to provide links with the following
`rel` (relation) types:
1. `root` and `parent`: URL to the data discovery endpoint at `/collections`.
2. `license`: A link to the license(s) should be specified if the `license`
field is set to `proprietary` or `various`.
3. `example`: Links to examples of processes that use this collection.
4. `derived_from`: Allows linking to the data this collection was derived from.
5. `cite-as`: [DOI](https://www.doi.org/) links should be added. DOIs can also be
listed in the STAC fields `sci:doi` and `sci:publications`, see the [STAC scientific
extension](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions/scientific)
for more details.
6. `latest-version`: If a collection has been marked as deprecated, a link should
point to the latest version of the collection. 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.
7. `alternate`: An alternative representation of the collection.
For example, this could be the collection available through another
catalog service such as OGC CSW, a human-readable HTML version or a
metadata document following another standard such as ISO 19115 or DCAT.
For additional relation types see also the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking)
and the STAC specification for Collections.
type: array
items:
$ref: '#/components/schemas/link'
'cube:dimensions':
title: STAC Collection Cube Dimensions
description: |-
Uniquely named dimensions of the data cube.
The 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:
* `x` for the dimension of type `spatial` with the axis set to `x`
* `y` for the dimension of type `spatial` with the axis set to `y`
* `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`
This property REQUIRES to add `datacube` to the list
of `stac_extensions`.
type: object
additionalProperties:
x-additionalPropertiesName: Dimension Name
allOf:
- $ref: '#/components/schemas/dimension'
summaries:
title: STAC Summaries (Collection Properties)
description: |-
Collection properties from STAC extensions (e.g. EO,
SAR, Satellite or Scientific) or even custom extensions.
Summaries 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.
Potential fields for the summaries can be found here:
* **[STAC Common Metadata](https://github.com/radiantearth/stac-spec/tree/v0.9.0/item-spec/common-metadata.md)**:
A list of commonly used fields throughout all domains
* **[Content Extensions](https://github.com/radiantearth/stac-spec/tree/v0.9.0/extensions/README.md#list-of-content-extensions)**:
Domain-specific fields for domains such as EO, SAR and point clouds.
* **Custom Properties**:
It is generally allowed to add custom fields.
type: object
additionalProperties:
oneOf:
- type: array
title: Set of values
items:
description: A value of any type.
- $ref: '#/components/schemas/collection_summary_stats'
assets:
type: object
title: Assets
description: >-
Dictionary of asset objects for data that can be downloaded,
each with a unique key.
The keys MAY be used by clients as file names.
Implementing this property REQUIRES to add `collection-assets`
to the list of `stac_extensions`.
additionalProperties:
$ref: '#/components/schemas/asset'
stac_version:
type: string
description: >-
The [version of the STAC specification](https://github.com/radiantearth/stac-spec/releases),
which MAY not be equal to the [STAC API version](#section/STAC).
Supports versions 0.9.x and 1.x.x.
stac_extensions:
type: array
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:
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: datacube
stac_license:
type: string
description: |-
License(s) of the data as a SPDX [License identifier](https://spdx.org/licenses/).
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.
Non-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
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
properties:
name:
description: The name of the organization or the individual.
type: string
example: Cool EO Cloud Corp
description:
description: >-
Multi-line description to add further provider information such as
processing details for processors and producers, hosting details
for hosts or basic contact information.
CommonMark 0.29 syntax MAY be used for rich text representation.
type: string
example: No further processing applied.
roles:
description: >-
Roles of the provider.
The provider's role(s) can be one or more of the following
elements:
* licensor: The organization that is licensing the dataset under
the license specified in the collection's license field.
* producer: The producer of the data is the provider that
initially captured and processed the source data, e.g. ESA for
Sentinel-2 data.
* processor: A processor is any provider who processed data to a
derived product.
* host: The host is the actual provider offering the data on their
storage. There should be no more than one host, specified as last
element of the list.
type: array
items:
enum:
- producer
- licensor
- processor
- host
example:
- producer
- licensor
- host
url:
description: >-
Homepage on which the provider describes the dataset and publishes
contact information.
type: string
format: uri
example: http://cool-eo-cloud-corp.com
collection_summary_stats:
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
collection_id:
type: string
description: >-
A unique identifier for the collection, which MUST match the specified
pattern.
pattern: '^[\w\-\.~\/]+$'
example: Sentinel-2A
dimension:
title: Dimension
type: object
required:
- type
properties:
type:
description: 'Type of the dimension.'
enum:
- spatial
- temporal
- bands
- other
description:
$ref: '#/components/schemas/description'
oneOf:
- $ref: '#/components/schemas/dimension_spatial'
- $ref: '#/components/schemas/dimension_temporal'
- $ref: '#/components/schemas/dimension_bands'
- $ref: '#/components/schemas/dimension_other'
discriminator:
propertyName: type
mapping:
spatial: '#/components/schemas/dimension_spatial'
temporal: '#/components/schemas/dimension_temporal'
bands: '#/components/schemas/dimension_bands'
other: '#/components/schemas/dimension_other'
dimension_other:
allOf:
- $ref: '#/components/schemas/dimension'
- title: Additional Dimension
type: object
properties:
extent:
$ref: '#/components/schemas/collection_dimension_extent_open'
values:
$ref: '#/components/schemas/collection_dimension_values'
step:
$ref: '#/components/schemas/collection_dimension_step'
unit:
$ref: '#/components/schemas/collection_dimension_unit'
reference_system:
description: The reference system for the data.
type: string
dimension_bands:
allOf:
- $ref: '#/components/schemas/dimension'
- title: Band Dimension
description: |-
A dimension for the bands.
The band dimension only specifies the band names
as dimension labels. Further information to the
bands are available in either `sar:bands` or
`eo:bands` in the `summaries` property.
type: object
required:
- values
properties:
values:
$ref: '#/components/schemas/collection_dimension_values'
dimension_spatial:
allOf:
- $ref: '#/components/schemas/dimension'
- title: Spatial Dimension
description: A spatial 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`).'
enum:
- 'x'
- 'y'
- 'z'
extent:
description: >-
Extent (lower and upper bounds) of the
dimension as two-dimensional array. Open
intervals with `null` are not allowed.
type: array
minItems: 2
maxItems: 2
items:
type: number
values:
description: 'A set of all potential values.'
type: array
minItems: 1
items:
type: number
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) or [PROJ definition (deprecated)](https://proj.org/usage/quickstart.html). Defaults to EPSG code 4326.
oneOf:
- type: string
description: WKT2 or PROJ definition
- type: number
default: 4326
description: EPSG code
oneOf:
- $ref: '#/components/schemas/dimension_spatial_horizontal'
- $ref: '#/components/schemas/dimension_spatial_horizontal'
- $ref: '#/components/schemas/dimension_spatial_vertical'
discriminator:
propertyName: axis
mapping:
x: '#/components/schemas/dimension_spatial_horizontal'
y: '#/components/schemas/dimension_spatial_horizontal'
z: '#/components/schemas/dimension_spatial_vertical'
dimension_spatial_horizontal:
allOf:
- $ref: '#/components/schemas/dimension_spatial'
- title: Horizontal Spatial Dimension
required:
- extent
dimension_spatial_vertical:
allOf:
- $ref: '#/components/schemas/dimension_spatial'
- title: Vertical Spatial Dimension
anyOf:
- title: Vertical Spatial Dimension with Extent
required:
- extent
- title: Vertical Spatial Dimension with Values
required:
- values
dimension_temporal:
allOf:
- $ref: '#/components/schemas/dimension'
- 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:
- extent
properties:
values:
description: >-
If the dimension consists of set of specific
values they can be listed here. The dates
and/or times must be strings compliant to
[ISO
8601](https://en.wikipedia.org/wiki/ISO_8601).
type: array
minItems: 1
items:
type: string
extent:
description: >-
Extent (lower and upper bounds) of the
dimension as two-dimensional array. The
dates and/or times must be strings compliant
to [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601).
`null` is allowed for open date ranges.
type: array
minItems: 2
maxItems: 2
items:
type: string
nullable: true
step:
description: >-
The space between the temporal instances as
[ISO 8601
duration](https://en.wikipedia.org/wiki/ISO_8601#Durations),
e.g. `P1D`. Use `null` for irregularly
spaced steps.
type: string
nullable: true
collection_dimension_extent_open:
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. Use `null` for open intervals.
type: array
minItems: 2
maxItems: 2
items:
type: number
nullable: true
collection_dimension_values:
description: >-
A set of all potential values, especially useful for
[nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level)
values.
**Important:** The order of the values MUST be exactly how the dimension
values are also ordered in the data (cube). If the values specify band
names, the values MUST be in the same order as they are in the
corresponding band fields (i.e. `eo:bands` or `sar:bands`).
type: array
minItems: 1
items:
oneOf:
- type: number
- type: string
collection_dimension_step:
description: >-
If the dimension consists of
[interval](https://en.wikipedia.org/wiki/Level_of_measurement#Interval_scale)
values, the space between the values. Use `null` for irregularly spaced
steps.
type: number
nullable: true
collection_dimension_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
process_arguments:
title: Process Arguments
type: object
additionalProperties:
$ref: '#/components/schemas/process_argument_value'
process_argument_value:
title: Process Argument Value
description: Arguments for a process. See the API documentation for more information.
anyOf:
- type: object
nullable: true
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
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'
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
nullable: true
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:
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/process_deprecated'
experimental:
$ref: '#/components/schemas/process_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:
type: string
nullable: true
links:
type: array
description: >-
Links related to this process, e.g. additional external documentation.
It is RECOMMENDED to provide links with the following `rel` (relation) types:
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. `example`: Links to examples of other processes that use this process.
3. `cite-as`: For all DOIs associated with the process, the respective DOI
links should be added.
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'
nullable_process:
type: object
properties:
summary:
type: string
nullable: true
description:
type: string
nullable: true
parameters:
type: array
items: {}
nullable: true
returns:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/process'
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
allOf:
- $ref: '#/components/schemas/nullable_process'
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
nullable: true
allOf:
- $ref: '#/components/schemas/nullable_process'
process_id:
type: string
description: |-
Unique identifier for the process.
MUST be unique across all predefined and user-defined processes available for the authenticated user.
If a back-end adds a process with the name of a user-defined process, the user-defined process takes
preference over predefined processes in execution to not break existing process graphs.
Back-ends may choose to enforce a prefix for user-defined processes while storing the process, e.g.
`user_ndvi` with `user_` being the prefix. Prefixes must still follow the pattern.
pattern: '^\w+$'
example: ndvi
process_summary:
type: string
description: A short summary of what the process does.
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: The data that is returned from this process.
required:
- schema
properties:
description:
$ref: '#/components/schemas/process_description'
schema:
$ref: '#/components/schemas/data_type_schema'
process_experimental:
type: boolean
description: >-
Declares the process or parameter to be experimental, which means that
it is likely to change or may produce unpredictable behaviour. Users
should refrain from using it in production, but still feel encouraged
to try it out and give feedback.
default: false
process_deprecated:
type: boolean
description: >-
Specifies that the process or parameter 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.
For processes a link with relation type `latest-version` SHOULD be
added to the `links` and MUST refer to the process that can be used
instead.
default: false
process_exceptions:
type: object
title: Process Exceptions
description: |-
Declares any 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.
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_parameters:
type: array
description: |-
A list of parameters.
The order in the array corresponds to the parameter order to
be used in clients that don't 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'
base_parameter:
type: object
required:
- name
- description
properties:
name:
type: string
description: |-
A unique name for the parameter.
It is RECOMMENDED to use [snake case](https://en.wikipedia.org/wiki/Snake_case) (e.g. `window_size` or `scale_factor`).
pattern: '^\w+$'
description:
$ref: '#/components/schemas/process_description'
optional:
type: boolean
description: Determines whether this parameter is optional to be specified.
default: false
deprecated:
$ref: '#/components/schemas/process_deprecated'
experimental:
$ref: '#/components/schemas/process_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.
type: string
nullable: true
parameter:
title: Parameter
type: object
required:
- schema
properties:
schema:
$ref: '#/components/schemas/data_type_schema'
allOf:
- $ref: '#/components/schemas/base_parameter'
process_parameter:
title: Process Parameter
type: object
required:
- schema
properties:
schema:
$ref: '#/components/schemas/parameter_schema'
allOf:
- $ref: '#/components/schemas/base_parameter'
batch_job:
title: Batch Job
description: >-
The metadata of a batch jobs that has been submitted by the
authenticated user.
type: object
required:
- id
- status
- created
properties:
id:
$ref: '#/components/schemas/job_id'
title:
$ref: '#/components/schemas/eo_title'
description:
$ref: '#/components/schemas/eo_description'
process:
$ref: '#/components/schemas/process_graph_with_metadata'
status:
enum:
- created
- queued
- running
- canceled
- finished
- error
description: |-
The current status of a batch job.
The following status changes can occur:
* `POST /jobs`: The status is initialized as `created`.
* `POST /jobs/{job_id}/results`: The status is set to `queued`, if
processing doesn't start instantly.
* Once the processing starts the status is set to `running`.
* Once the data is available to download the status is set to `finished`.
* Whenever an error occurs during processing, the status must be set to `error`.
* `DELETE /jobs/{job_id}/results`: The status is set to `canceled` if
the status was `running` beforehand and partial or preliminary results
are available to be downloaded. Otherwise the status is set to
`created`.
example: running
default: created
progress:
type: number
description: >-
Indicates the process of a running batch job in percent.
Can also be set for a job which stopped due to an error or was
canceled by the user. In this case, the value indicates
the progress at which the job stopped. Property may not be
available for the status codes `created` and `queued`.
Submitted and queued jobs only allow the value `0`,
finished jobs only allow the value `100`.
minimum: 0
maximum: 100
example: 75.5
created:
$ref: '#/components/schemas/created'
updated:
$ref: '#/components/schemas/updated'
plan:
$ref: '#/components/schemas/billing_plan'
costs:
$ref: '#/components/schemas/money'
budget:
$ref: '#/components/schemas/budget'
job_id:
type: string
description: >-
Unique identifier of the batch job, generated by the
back-end during creation. MUST match the specified pattern.
pattern: '^[\w\-\.~]+$'
example: a3cca2b2aa1e3b5b
created:
type: string
format: date-time
description: >-
Date and time of creation, formatted as a [RFC
3339](https://www.ietf.org/rfc/rfc3339) date-time.
example: '2017-01-01T09:32:12Z'
updated:
type: string
format: date-time
description: >-
Date and time of last status change, formatted as a [RFC
3339](https://www.ietf.org/rfc/rfc3339) date-time.
example: '2017-01-01T09:36:18Z'
user_id:
type: string
description: >-
Unique identifier of the user. MUST match the specified pattern.
This is usually a randomly generated internal identifier from the provider
not meant for displaying purposes.
pattern: '^[\w\-\.~]+$'
example: john_doe
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.
object_title:
type: string
description: >-
A human-readable short title to be displayed to users **in addition** to
the names specified in the keys. This property is only for better user
experience so that users can understand the names better.
Example titles could be `GeoTiff` for the key `GTiff` (for file formats)
or `OGC Web Map Service` for the key `WMS` (for service types).
The title MUST NOT be used in communication (e.g. in process graphs),
although clients MAY translate the titles into the corresponding names.
eo_title:
description: A short description to easily distinguish entities.
type: string
nullable: true
example: NDVI based on Sentinel 2
eo_description:
type: string
format: commonmark
description: >-
Detailed multi-line description to explain the entity.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich
text representation.
nullable: true
example: Deriving minimum NDVI measurements over pixel time series of Sentinel 2
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()`` ```
service:
title: Secondary Web Service
description: >-
The metadata of a secondary web service that has been submitted by the
authenticated user.
type: object
required:
- id
- enabled
- type
- url
properties:
id:
$ref: '#/components/schemas/service_id'
title:
$ref: '#/components/schemas/eo_title'
description:
$ref: '#/components/schemas/eo_description'
url:
type: string
format: uri
description: >-
URL at which the secondary web service is accessible. Doesn't
necessarily need to be located within the API.
example: 'https://example.openeo.org/wms/wms-a3cca9'
type:
$ref: '#/components/schemas/service_type'
enabled:
$ref: '#/components/schemas/service_enabled'
process:
$ref: '#/components/schemas/process_graph_with_metadata'
configuration:
$ref: '#/components/schemas/service_configuration'
attributes:
title: Secondary Web Service Attributes
type: object
description: >-
Additional attributes of the secondary web service, e.g.
available layers for a WMS based on the bands in the
underlying GeoTiff.
example:
layers:
- ndvi
- evi
created:
$ref: '#/components/schemas/created'
plan:
$ref: '#/components/schemas/billing_plan'
costs:
$ref: '#/components/schemas/money'
budget:
$ref: '#/components/schemas/budget'
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
example: wms
service_configuration:
type: object
title: Service Configuration
description: >-
Map of arguments, i.e. the parameter names supported by the secondary
web service combined with actual values. See `GET /service_types` for
supported parameters and valid arguments. For example, this could
specify the required version of the service, visualization details or
any other service dependant configuration.
example:
version: 1.3.0
service_enabled:
type: boolean
description: >-
Describes whether a secondary web service is responding to requests
(true) or not (false). Defaults to true. Disabled services don't produce
any costs.
default: true
service_id:
type: string
description: >-
Unique identifier of the secondary web service, generated by the
back-end during creation. MUST match the specified pattern.
pattern: '^[\w\-\.~]+$'
example: wms-a3cca9
argument:
x-additionalPropertiesName: Parameter Name
type: object
title: Argument
description: Describes a general argument for various entities.
required:
- description
properties:
type:
type: string
description: >-
The type is the expected data type for the content of the parameter.
`null` is allowed for all types. If no type is specified, any type is
allowed to be passed.
enum:
- string
- number
- integer
- boolean
- array
- object
description:
type: string
description: A brief description of the argument.
required:
type: boolean
description: Determines whether this argument is mandatory.
default: false
default:
description: >-
The default value represents what would be assumed by the consumer
of the input as the value of the argument if none is provided. The
value MUST conform to the defined type for the argument defined at
the same level. For example, if type is string, then default can be
"foo" but cannot be 1.
type: string
nullable: true
minimum:
type: number
description: Minimum value allowed for numeric arguments.
maximum:
type: number
description: Maximum value allowed for numeric arguments.
enum:
type: array
description: >-
List of allowed values for this argument. To represent examples that
cannot be naturally represented in JSON, a string value can be used
to contain the example with escaping where necessary.
items:
description: A single value allowed for this argument.
example:
description: >-
A free-form property to include an example for this argument. To
represent examples that cannot be naturally represented in JSON, a
string value can be used to contain the example with escaping where
necessary.
example:
description: A percentage between 0 and 100.
required: true
minimum: 0
maximum: 100
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'
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 `debug` process.
example: SampleError
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://example.openeo.org/docs/errors/SampleError'
rel: about
data_type_schema:
title: Data Types
description: Either a single data type or a list of data types.
oneOf:
- $ref: '#/components/schemas/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/json_schema'
parameter_schema:
title: Parameter Data Types
description: Either a single data type or a list of data types.
oneOf:
- $ref: '#/components/schemas/parameter_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:
title: Single Data Type
type: object
properties:
parameters:
type: array
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 don't support named parameters.
items:
$ref: '#/components/schemas/parameter'
allOf:
- $ref: '#/components/schemas/json_schema'
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.
It is discouraged to specify JSON Schemas with `default`, `anyOf`, `oneOf`, `allOf` or `not` at the top-level of the schema.
Instead specify each data type in a separate array element.
It is recommended to refrain from using the following more complex JSON Schema keywords:
`if`, `then`, `else`, `readOnly`, `writeOnly`, `dependencies`, `minProperties`, `maxProperties`, `patternProperties`, `multipleOf`.
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:
type:
oneOf:
- $ref: '#/components/schemas/json_schema_type'
- type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/json_schema_type'
subtype:
type: string
pattern:
type: "string"
format: "regex"
enum:
type: array
items: {}
minimum:
type: number
maximum:
type: number
minItems:
type: number
minimum: 0
default: 0
maxItems:
type: number
minimum: 0
items:
anyOf:
- type: array
minItems: 1
items:
$ref: '#/components/schemas/json_schema'
- $ref: '#/components/schemas/json_schema'
additionalProperties: true
json_schema_type:
enum:
- array
- boolean
- integer
- 'null'
- number
- object
- string
file:
title: Workspace File
type: object
required:
- path
properties:
path:
type: string
description: >-
Path of the file, relative to the user's root directory. MUST NOT
start with a slash and MUST NOT be url-encoded.
example: folder/file.txt
size:
type: integer
description: File size in bytes.
example: 1024
modified:
type: string
format: date-time
description: >-
Date and time the file has lastly been modified, formatted as a [RFC
3339](https://www.ietf.org/rfc/rfc3339) date-time.
example: '2018-01-03T10:55:29Z'
GeoJsonPoint3D:
type: array
description: Point in 3D space
minItems: 2
maxItems: 3
items:
type: number
GeoJsonPoint:
type: object
title: GeoJSON Point
required:
- type
- coordinates
properties:
type:
enum:
- Point
coordinates:
$ref: '#/components/schemas/GeoJsonPoint3D'
GeoJsonGeometry:
title: GeoJSON Geometry
type: object
required:
- type
properties:
type:
enum:
- Point
- LineString
- Polygon
- MultiPoint
- MultiLineString
- MultiPolygon
- GeometryCollection
oneOf:
- $ref: '#/components/schemas/GeoJsonPoint'
- $ref: '#/components/schemas/GeoJsonLineString'
- $ref: '#/components/schemas/GeoJsonPolygon'
- $ref: '#/components/schemas/GeoJsonMultiPoint'
- $ref: '#/components/schemas/GeoJsonMultiLineString'
- $ref: '#/components/schemas/GeoJsonMultiPolygon'
- $ref: '#/components/schemas/GeoJsonGeometryCollection'
discriminator:
propertyName: type
mapping:
Point: '#/components/schemas/GeoJsonPoint'
LineString: '#/components/schemas/GeoJsonLineString'
Polygon: '#/components/schemas/GeoJsonPolygon'
MultiPoint: '#/components/schemas/GeoJsonMultiPoint'
MultiLineString: '#/components/schemas/GeoJsonMultiLineString'
MultiPolygon: '#/components/schemas/GeoJsonMultiPolygon'
GeometryCollection: '#/components/schemas/GeoJsonGeometryCollection'
GeoJsonLineString:
allOf:
- $ref: '#/components/schemas/GeoJsonGeometry'
- type: object
title: GeoJSON LineString
required:
- coordinates
properties:
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonPoint3D'
GeoJsonPolygon:
allOf:
- $ref: '#/components/schemas/GeoJsonGeometry'
- type: object
title: GeoJSON Polygon
required:
- coordinates
properties:
coordinates:
type: array
items:
type: array
items:
$ref: '#/components/schemas/GeoJsonPoint3D'
GeoJsonMultiPoint:
allOf:
- $ref: '#/components/schemas/GeoJsonGeometry'
- type: object
title: GeoJSON MultiPoint
required:
- coordinates
properties:
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonPoint3D'
GeoJsonMultiLineString:
allOf:
- $ref: '#/components/schemas/GeoJsonGeometry'
- type: object
title: GeoJSON MultiLineString
required:
- coordinates
properties:
coordinates:
type: array
items:
type: array
items:
$ref: '#/components/schemas/GeoJsonPoint3D'
GeoJsonMultiPolygon:
allOf:
- $ref: '#/components/schemas/GeoJsonGeometry'
- type: object
title: GeoJSON MultiPolygon
required:
- coordinates
properties:
coordinates:
type: array
items:
type: array
items:
type: array
items:
$ref: '#/components/schemas/GeoJsonPoint3D'
GeoJsonGeometryCollection:
allOf:
- $ref: '#/components/schemas/GeoJsonGeometry'
- type: object
title: GeoJSON GeometryCollection
required:
- geometries
properties:
geometries:
type: array
items:
$ref: '#/components/schemas/GeoJsonGeometry'
log_entry:
title: Log Entry
description: >-
An log message that communicates information about the processed data.
type: object
required:
- id
- level
- message
- path
properties:
id:
type: string
description: >-
An unique identifier for the log message, could simply be an incrementing number.
example: "1"
code:
$ref: '#/components/schemas/log_code'
level:
description: |-
The severity level of the log entry.
The order of the levels is as follows (from high to low severity): `error`, `warning`, `info`, `debug`.
The level `error` usually stops processing the data.
enum:
- error
- warning
- info
- debug
example: error
message:
type: string
description: A message explaining the log entry.
example: >-
Can't load the UDF file from the URL `https://example.com/invalid/file.txt`.
Server responded with error 404.
data:
description: |-
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 `debug` should return the
metadata similar to the collection metadata, including `cube:dimensions`.
type: string
nullable: true
path:
description: >-
Describes where the log entry has occurred.
The first element of the array is the process that has triggered the log entry, the second element is the parent of the process that has triggered the log entry, etc. This pattern is followed until the root of the process graph.
type: array
items:
type: object
required:
- node_id
properties:
node_id:
type: string
example: runudf1
process_id:
type: string
example: run_udf
parameter:
type: string
nullable: true
example: udf
links:
$ref: '#/components/schemas/log_links'
responses:
logs:
description: Lists the requested log entries.
content:
application/json:
schema:
title: Log Entries
type: object
required:
- logs
- links
properties:
logs:
type: array
items:
$ref: '#/components/schemas/log_entry'
links:
$ref: '#/components/schemas/links_pagination'
client_error:
description: |-
The request can't 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://tools.ietf.org/html/rfc7231#section-6.6). This request
usually does not respond with HTTP status codes 401 and 403 due to
missing authorization. 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'
client_error_auth:
description: |-
The request can't 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://tools.ietf.org/html/rfc7231#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't 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://tools.ietf.org/html/rfc7231#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'
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. jobs or log entries) are allowed to contain.
The only exception is the `links` array, which MUST NOT be paginated as otherwise the
pagination links may be missing ins responses.
If the parameter is not provided or empty, all elements are returned.
Pagination is OPTIONAL and back-ends and 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 will return all resources.
If the response is paginated, the links array MUST be used to propagate the
links for pagination with pre-defined `rel` types. See the links array schema
for supported `rel` types.
*Note:* Implementations can use all kind of pagination techniques, depending on what is
supported best by their infrastructure. So it doesn't care whether it is page-based,
offset-based or uses tokens for pagination. The clients will use whatever is specified
in the links with the corresponding `rel` types.
in: query
allowEmptyValue: true
example: 10
schema:
type: integer
minimum: 1
log_offset:
name: offset
description: The last identifier (property `id` of a log entry) the client has received. If provided, the back-ends only sends the entries that occured after the specified identifier. If not provided or empty, start with the first entry.
in: query
allowEmptyValue: true
example: "log1234"
schema:
type: string
service_id:
name: service_id
in: path
description: Unique secondary web service identifier.
required: true
schema:
$ref: '#/components/schemas/service_id'
job_id:
name: job_id
in: path
description: Unique job identifier.
required: true
schema:
$ref: '#/components/schemas/job_id'
examples:
evi_user_defined_process:
description: A user-defined process that computes the 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: >-
The Bearer Token MUST consist of the authentication method, a provider
ID (if available) and the token itself. All separated by a forward slash
`/`. Examples (replace `TOKEN` with the actual access token): (1) Basic
authentication (no provider ID available): `basic//TOKEN` (2) OpenID
Connect (provider ID is `ms`): `oidc/ms/TOKEN`. For OpenID Connect, the
provider ID corresponds to the value specified for `id` for each
provider in `GET /credentials/oidc`.
Basic:
type: http
scheme: basic
|
Beta Was this translation helpful? Give feedback.
1 reply
-
|
Thank you for the pointer. It seems indeed correct that the OpenAPI doc requires this oneOf duplication of references, but unfortunately the redoc ecosystem can't handle this. Either it's incomplete or we run into recursive schemas. |
Beta Was this translation helpful? Give feedback.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Describe the bug
I'm getting the following warning from Spectral:
This only happens for Schemas that are only referenced in the discriminator mappings, for example:
To Reproduce
Here's the OpenAPI file I'm working on: https://github.com/Open-EO/openeo-api/blob/76ec4a59/openapi.yaml
I'm running: spectral lint openapi.yaml
Ruleset is spectral:oas
Expected behavior
No warning.
Environment (remove any that are not applicable):
Beta Was this translation helpful? Give feedback.
All reactions