Skip to content

Commit a645bae

Browse files
m-mohrm-mohr
committed
Crosswalk with OGC API - Processes
1 parent 3341922 commit a645bae

File tree

3 files changed

+371
-0
lines changed

3 files changed

+371
-0
lines changed

‎crosswalks/oap-echo-example.json

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
{
2+
"id": "EchoProcess",
3+
"title": "Echo Process",
4+
"description": "This process accepts and number of input and simple echoes each input as an output.",
5+
"version": "1.0.0",
6+
"jobControlOptions": [
7+
"async-execute",
8+
"sync-execute"
9+
],
10+
"outputTransmission": [
11+
"value",
12+
"reference"
13+
],
14+
"inputs": {
15+
"stringInput": {
16+
"title": "String Literal Input Example",
17+
"description": "This is an example of a STRING literal input.",
18+
"schema": {
19+
"type": "string",
20+
"enum": [
21+
"Value1",
22+
"Value2",
23+
"Value3"
24+
]
25+
},
26+
"doubleInput": {
27+
"title": "Bounded Double Literal Input Example",
28+
"description": "This is an example of a DOUBLE literal input that is bounded between a value greater than 0 and 10. The default value is 5.",
29+
"schema": {
30+
"type": "number",
31+
"format": "double",
32+
"minimum": 0,
33+
"maximum": 10,
34+
"default": 5,
35+
"exclusiveMinimum": true
36+
}
37+
}
38+
}
39+
},
40+
"outputs": {
41+
"stringOutput": {
42+
"schema": {
43+
"type": "string",
44+
"enum": [
45+
"Value1",
46+
"Value2",
47+
"Value3"
48+
]
49+
}
50+
},
51+
"doubleOutput": {
52+
"schema": {
53+
"type": "number",
54+
"format": "double",
55+
"minimum": 0,
56+
"maximum": 10,
57+
"default": 5,
58+
"exclusiveMinimum": true
59+
}
60+
}
61+
},
62+
"links": [
63+
{
64+
"href": "https://processing.example.org/oapi-p/processes/EchoProcess/execution",
65+
"rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
66+
"title": "Execute endpoint"
67+
}
68+
]
69+
}

‎crosswalks/ogcapi-processes.md

+243
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Crosswalk between openEO API and OGC API - Processes
2+
3+
This document gives a brief overview over similarities and differences between
4+
- **openEO API, v1.2.0**
5+
- **OGC API - Processes - Part 1: Core, v1.0.0**
6+
7+
In the following I use **OAP1** as an abbreviation for **OGC API - Processes - Part 1**.
8+
9+
## General
10+
11+
OCG API - Processes defines just processing, while the openEO API has a much broader scope.
12+
openEO covers many parts that other OGC API specifications define, some are aligned some are not.
13+
14+
The openEO API covers the following "categories" of endpoints:
15+
- [API discovery](#api-discovery) - partially covered by OGC API - Processes - Part 1
16+
- [Authentication](#authentication) - not defined by OGC
17+
- [Data Discovery](#data-discovery) - covered by various other OGC APIs (Coverages, EDR, Features, Records, ...)
18+
- [Process Discovery](#process-discovery) - covered by OGC API - Processes - Part 1
19+
- [Pre-defined processes](#pre-defined-processes) - covered by OGC API - Processes - Part 1
20+
- [User-defined processes](#user-defined-processes) - covered by OGC API - Processes - Part 2 and 3
21+
- [Data Processing](#data-processing) - covered by OGC API - Processes - Part 1 and 3
22+
- [Synchronous processing](#synchronous-processing) - covered by OGC API - Processes - Part 1
23+
- [Batch Job processing](#batch-job-processing) - covered by OGC API - Processes - Part 1
24+
- [On-demand processing](#on-demand-processing) - covered by other OGC APIs (Maps, Tiles, ...)
25+
- [File Storage](#file-storage) - not covered by OGC APIs
26+
27+
Both APIs use HTTP as the basis and encourage HTTPS.
28+
HTTP 1.1 is required for OAP1, while openEO doesn't specify a specific HTTP version.
29+
The APIs follow REST principles and make use of HTTP content negotiation.
30+
The APIs make broad use of "Web Linking" (compatible between OAP1 and openEO).
31+
Both specifications recommend the implementation of CORS.
32+
33+
The default encoding for requests and response bodies is JSON. OGC API recommends to also support
34+
HTML as an response body encoding. openEO uses client software to render HTML output from JSON.
35+
36+
Both specifications make broad use of OpenAPI 3.0 and JSON Schema for specification purposes.
37+
38+
Many API endpoints in OAP1 and openEO support pagination through links with the relation types `next`
39+
and `prev`. These endpoints have a `limit` parameter to enable pagination for a specific page size.
40+
**Note:** Pagination is rarely used in openEO implementations and most clients don't support it consistently.
41+
42+
## API discovery
43+
44+
Discovering the API, connecting to it and reading the capabilities is always the first step clients
45+
need to execute.
46+
47+
### Well-known document
48+
49+
- openEO: `GET /.well-known/openeo`
50+
- OAP1: n/a
51+
52+
openEO clients usually connect to the well-known document first to discover different versions or
53+
implementations of a server. Thus a client can choose a suitable API versions inclusing choosing
54+
between production and development instances. Then the openEO client connects to the selected
55+
instance's [landing page](#landing-page), which OGC API - Processes clients always directly connect
56+
to. openEO clients can usually also directly connect to the landing page though.
57+
58+
This folder structure with the document resides usually outside of the actual API implementations,
59+
i.e. in the root of the host or domain.
60+
61+
### Landing page
62+
63+
- openEO: `GET /` (required)
64+
- OAP1: `GET /` (required)
65+
66+
As the landing pages both are based on top of OGC API - Common, they are very similar.
67+
68+
Some differences include:
69+
- openEO requires the following additional fields:
70+
- Defined in OAP1, but not required: `title`, `description`
71+
- Not defined in OAP1: `api_version`, `backend_version`, `stac_version`, `id`, `endpoints`, (`type`)
72+
- The relation type to link to the conformance classes is `conformance` in openEO (originating from
73+
OGC API - Features / STAC API) and `http://www.opengis.net/def/rel/ogc/1.0/conformance` in OAP1.
74+
Two links with the same target but different relation types will be required.
75+
- The existance of API endpoints in openEO is primarily checked through `endpoints`, which is
76+
not present in OAP1. OAP1 uses links, which openEO primarily uses for non-API-related links.
77+
Nevertheless, links such as required in OAP1 can be added easily to an openEO implementation.
78+
The following additionl links are relevant for OAP1:
79+
- One of the link relations `service-desc` or `service-doc` is required in OAP1. They should link
80+
to an API description (e.g. OpenAPI or rendered HTML version).
81+
- A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/processes` to `/processes` is
82+
required for OAP1, but not in openEO.
83+
- A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/job-list` to `/jobs` can be
84+
added in OAP1, but is not present in openEO.
85+
86+
### Conformanc classes
87+
88+
- openEO: `GET /conformance` (optional)
89+
- OAP1: `GET /conformance` (required)
90+
91+
Both endpoints are 100% equivalent.
92+
OAP1 requires a separate endpoint that lists conformance classes.
93+
openEO additionally allows to list the conformance classes in the landing page (follows STAC API).
94+
Conformance classes are only fully defined since openEO API v1.2.0.
95+
96+
## Authentication
97+
98+
- openEO: `GET /credentials/basic` and/or `GET /credentials/oidc`
99+
- OAP1: n/a
100+
101+
OpenEO defines two authentication mechanisms:
102+
- OpenID Connect (primary)
103+
- HTTP Basic (secondary, primarily for development/testing purposes)
104+
105+
OAP1 doesn't define any authentication machanisms, but both authentication mechanisms can also be
106+
implemented for OAP1. The main issue will be that OAP1 clients will likely not support them.
107+
108+
The availability of the authentication mechanisms is detected through the `endpoints` in the
109+
[landing page](#landing-page) in openEO, while in OAP1 you need to parse the OpenAPI document for it
110+
(which implicitly requires a link to an OpenAPI 3.0 file with relation type `service-desc` in the
111+
landing page).
112+
113+
## Data Discovery
114+
115+
Data Discovery is not covered by OAP1, but it can be "plugged in" through various other OGC APIs
116+
(e.g. Coverages, EDR, Features, Records, ...). Except for OGC API - Processes - Part 3, it is not
117+
clear how the processes defined in OAP1 can access resources from the other APIs. The processes
118+
probably need to implement data access individually through OGC API clients. As such, OAP1 could
119+
also be made compliant with STAC API - Collection and STAC API - Features. STAC API - Collections
120+
is required by openEO, STAC API - Features is optional in openEO, but would likely be required to
121+
allow data access through OAP1 processes.
122+
123+
## Process Discovery
124+
125+
The OAP1 specification claims that it
126+
> does not mandate the use of any specific process description to specify the interface of a
127+
process.
128+
129+
It defines a "default" encoding in the conformance class "OGC Process Description" though.
130+
Unfortunately, this is [a somewhat miselading statement](https://github.com/opengeospatial/ogcapi-processes/issues/325)
131+
and OAP1 still provides a predefined set of fields which conflict with openEO (see below).
132+
133+
The openEO API specifies a single encoding for process descriptions.
134+
135+
An important difference is that in OAP1 you usually execute just one process
136+
(you can optionally chain them using OGC API - Processes - Part 3).
137+
This means a process in OAP1 are usually more complex.
138+
In openEO a process is usually very fine-granular (e.g. addition of two numbers)
139+
and you usually chain multiple of them to a more complex process (graph).
140+
141+
### Pre-defined processes
142+
143+
- openEO: `GET /processes` (required)
144+
- OAP1: `GET /processes`, `GET /processes/{processID}` (both required)
145+
146+
In openEO `GET /processes` returns the full process metadata, while in OAP1 it only returns a summary.
147+
The general structure of the response of `GET /processes` is the same (`processes` and `links`).
148+
The OGC Process Description and the openEO process description are not compatible though.
149+
150+
openEO doesn't define an endpoint yet to retrieve an indivdual process such as
151+
`GET /processes/{processID}` in OAP1.
152+
There is a [proposal](https://github.com/Open-EO/openeo-api/pull/348) available to add such an endpoint.
153+
openEO has the concept of namespace for processes though and thus defines the endpoint at
154+
`GET /processes/{namespace}/{process}` which would conflict with OAP1.
155+
156+
Some notable differences in the process description (only fully delivered via `GET /processes/{processID}`):
157+
- OAP1 defines `jobControlOptions`, which is
158+
[undefined in openEO](https://github.com/Open-EO/openeo-api/issues/429) yet
159+
(which implies `["sync-execute","async-execute"]`).
160+
- OAP1 defines `outputTransmission`, which is not available in openEO.
161+
It seems though [this will be removed](https://github.com/opengeospatial/ogcapi-processes/issues/326).
162+
- OAP1 allows multiple outputs, openEO only allows a single output
163+
(potential workaround: wrap in an array or object)
164+
- OAP1 uses `title` and openEO uses `summary`
165+
- OAP1 specifies `inputs` as object and the identifier as key,
166+
openEO specifies `parameters` as array and the identifier as `name` property
167+
(but the content of each of them is otherwise very similar).
168+
169+
Below is a simple process encoded in the two variants discussed here:
170+
- [OGC Process Description](oap-echo-example.json)
171+
- [openEO Process](openeo-echo-example.json)
172+
173+
### User-defined processes
174+
175+
TBD, lower priority as it's not covered by OAP1.
176+
Instead it is defined in OGC API - Processes - Part 2.
177+
178+
## Data Processing
179+
180+
### Synchronous processing
181+
182+
- openEO: `POST /result`
183+
- OAP1: `POST /processes/{processID}/execution`
184+
185+
TBD
186+
187+
### Batch Job processing
188+
189+
#### Job list
190+
191+
- openEO: `GET /jobs`
192+
- OAP1: `GET /jobs`
193+
194+
TBD
195+
196+
#### Job status
197+
198+
- openEO: `GET /jobs/{jobID}`
199+
- OAP1: `GET /jobs/{jobID}`
200+
201+
TBD
202+
203+
#### Creating a job
204+
- openEO: `POST /jobs`
205+
- OAP1: `POST /processes/{processID}/execution`
206+
207+
In OAP you may provide inputs, outputs, the response type (raw or document) and/or a subscriber.
208+
209+
In openEO you must provide a process (chained processes as process graph with optional additional metadata)
210+
and you may additionally provide a title, a description, a billing plan and/or a maximum budget.
211+
212+
Both specifications seem to allow providing additional properties.
213+
214+
#### Queueing a job
215+
216+
- openEO: `POST /jobs/{jobID}/results`
217+
- OAP1: n/a (queued directly after creation)
218+
219+
#### Result Access
220+
221+
- openEO: `GET /jobs/{jobID}/results`
222+
- OAP1: `GET /jobs/{jobID}/results`
223+
224+
In openEO result access does fully rely on STAC. The response is a valid STAC Item or Collection.
225+
226+
In OAP1 the result access [differs depending on the given parameters](https://docs.ogc.org/is/18-062r2/18-062r2.html#toc34).
227+
228+
### On-demand processing
229+
230+
*On-demand processing in this context means that processing is only executed for extents shown to*
231+
*the user, e.g. on a web map. Results are processed "on demand" depending on the interaction with*
232+
*the map (e.g. how Google Earth Engine does it in their Code Editor by default).*
233+
234+
TBD, lower priority as it's not covered by OAP1. It's also optional and very different in openEO.
235+
Instead it is defined as a separate OAP1 API implementation for individual OGC API resources.
236+
For example, a combination of OGC API - Maps and OGC API - Processes.
237+
238+
## File Storage
239+
240+
- openEO: `/files` (various methods), `/files/{path}` (various methods)
241+
- OAP1: n/a
242+
243+
As it is neither available in OAP1 nor in any of the OGC APIs, we don't make any comparisons here.

‎crosswalks/openeo-echo-example.json

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
{
2+
"id": "EchoProcess",
3+
"summary": "Echo Process",
4+
"description": "This process accepts and number of input and simple echoes each input as an output.",
5+
"parameters": [
6+
{
7+
"name": "stringInput",
8+
"description": "This is an example of a STRING literal input.",
9+
"schema": {
10+
"type": "string",
11+
"enum": [
12+
"Value1",
13+
"Value2",
14+
"Value3"
15+
]
16+
}
17+
},
18+
{
19+
"name": "doubleInput",
20+
"description": "This is an example of a DOUBLE literal input that is bounded between a value greater than 0 and 10. The default value is 5.",
21+
"schema": {
22+
"type": "number",
23+
"minimum": 0,
24+
"maximum": 10,
25+
"exclusiveMinimum": true
26+
},
27+
"optional": true,
28+
"default": 5
29+
}
30+
],
31+
"returns": {
32+
"schema": {
33+
"type": "array",
34+
"items": [
35+
{
36+
"type": "string",
37+
"enum": [
38+
"Value1",
39+
"Value2",
40+
"Value3"
41+
]
42+
},
43+
{
44+
"type": "number",
45+
"minimum": 0,
46+
"maximum": 10,
47+
"exclusiveMinimum": true
48+
}
49+
]
50+
}
51+
},
52+
"links": [
53+
{
54+
"href": "https://processing.example.org/openeo/processes/EchoProcess/execution",
55+
"rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
56+
"title": "Execute endpoint"
57+
}
58+
]
59+
}

0 commit comments

Comments
 (0)