Skip to content

Commit a9fbc3e

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

File tree

3 files changed

+314
-0
lines changed

3 files changed

+314
-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

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
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 **OAP** 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+
- [Data Access and Visualization](#data-access-and-visualization) - covered by other OGC APIs (Coverages, Features, Maps, Tiles, ...)
27+
28+
Both APIs use HTTP as the basis and encourage HTTPS.
29+
HTTP 1.1 is required for OAP, while openEO doesn't specify a specific HTTP version.
30+
The APIs follow REST principles and make use of HTTP content negotiation.
31+
The APIs make broad use of "Web Linking" (compatible between OAP and openEO).
32+
Both specifications recommend the implementation of CORS.
33+
34+
The default encoding for requests and response bodies is JSON. OGC API recommends to also support
35+
HTML as an response body encoding. openEO uses client software to render HTML output from JSON.
36+
37+
Both specifications make broad use of OpenAPI 3.0 and JSON Schema for specification purposes.
38+
39+
Many API endpoints in OAP and openEO support pagination through links with the relation types `next`
40+
and `prev`. These endpoints have a `limit` parameter to enable pagination for a specific page size.
41+
**Note:** Pagination is rarely used in openEO implementations and most clients don't support it consistently.
42+
43+
## API discovery
44+
45+
Discovering the API, connecting to it and reading the capabilities is always the first step clients
46+
need to execute.
47+
48+
### Well-known document
49+
50+
- openEO: `GET /.well-known/openeo`
51+
- OAP: n/a
52+
53+
openEO clients usually connect to the well-known document first to discover different versions or
54+
implementations of a server. Thus a client can choose a suitable API versions inclusing choosing
55+
between production and development instances. Then the openEO client connects to the selected
56+
instance's [landing page](#landing-page), which OGC API - Processes clients always directly connect
57+
to. openEO clients can usually also directly connect to the landing page though.
58+
59+
This folder structure with the document resides usually outside of the actual API implementations,
60+
i.e. in the root of the host or domain.
61+
62+
### Landing page
63+
64+
- openEO: `GET /` (required)
65+
- OAP: `GET /` (required)
66+
67+
As the landing pages both are based on top of OGC API - Common, they are very similar.
68+
69+
Some differences include:
70+
- openEO requires the following additional fields:
71+
- Defined in OAP, but not required: `title`, `description`
72+
- Not defined in OAP: `api_version`, `backend_version`, `stac_version`, `id`, `endpoints`, (`type`)
73+
- The relation type to link to the conformance classes is `conformance` in openEO (originating from
74+
OGC API - Features / STAC API) and `http://www.opengis.net/def/rel/ogc/1.0/conformance` in OAP.
75+
Two links with the same target but different relation types will be required.
76+
- The existance of API endpoints in openEO is primarily checked through `endpoints`, which is
77+
not present in OAP. OAP uses links, which openEO primarily uses for non-API-related links.
78+
Nevertheless, links such as required in OAP can be added easily to an openEO implementation.
79+
The following additionl links are relevant for OAP:
80+
- One of the link relations `service-desc` or `service-doc` is required in OAP. They should link
81+
to an API description (e.g. OpenAPI or rendered HTML version).
82+
- A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/processes` to `/processes` is
83+
required for OAP, but not in openEO.
84+
- A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/job-list` to `/jobs` can be
85+
added in OAP, but is not present in openEO.
86+
87+
### Conformanc classes
88+
89+
- openEO: `GET /conformance` (optional)
90+
- OAP: `GET /conformance` (required)
91+
92+
Both endpoints are 100% equivalent.
93+
OAP requires a separate endpoint that lists conformance classes.
94+
openEO additionally allows to list the conformance classes in the landing page (follows STAC API).
95+
Conformance classes are only fully defined since openEO API v1.2.0.
96+
97+
## Authentication
98+
99+
- openEO: `GET /credentials/basic` and/or `GET /credentials/oidc`
100+
- OAP: n/a
101+
102+
OpenEO defines two authentication mechanisms:
103+
- OpenID Connect (primary)
104+
- HTTP Basic (secondary, primarily for development/testing purposes)
105+
106+
OAP doesn't define any authentication machanisms, but both authentication mechanisms can also be
107+
implemented for OAP. The main issue will be that OAP clients will likely not support them.
108+
109+
The availability of the authentication mechanisms is detected through the `endpoints` in the
110+
[landing page](#landing-page) in openEO, while in OAP you need to parse the OpenAPI document for it
111+
(which implicitly requires a link to an OpenAPI 3.0 file with relation type `service-desc` in the
112+
landing page).
113+
114+
## Data Discovery
115+
116+
Data Discovery is not covered by OAP, but it can be "plugged in" through various other OGC APIs
117+
(e.g. Coverages, EDR, Features, Records, ...). Except for OGC API - Processes - Part 3, it is not
118+
clear how the processes defined in OAP can access resources from the other APIs. The processes
119+
probably need to implement data access individually through OGC API clients. As such, OAP could
120+
also be made compliant with STAC API - Collection and STAC API - Features. STAC API - Collections
121+
is required by openEO, STAC API - Features is optional in openEO, but would likely be required to
122+
allow data access through OAP processes.
123+
124+
## Process Discovery
125+
126+
OAP does not mandate the use of any specific process description to specify the interface of a
127+
process. It defines a "default" encoding in the conformance class "OGC Process Description" though.
128+
129+
TBC, there seems to be a
130+
[conflicting statement](https://github.com/opengeospatial/ogcapi-processes/issues/325) in OAP.
131+
132+
The openEO API specifies a single encoding for process descriptions.
133+
This means in principle that OAP can return openEO processes, but it has to be assumed that OAP
134+
client will expect OGC Process Descriptions and won't be able to read openEO processes by default.
135+
136+
### Pre-defined processes
137+
138+
- openEO: `GET /processes` (required)
139+
- OAP: `GET /processes`, `GET /processes/{processID}` (both required)
140+
141+
In openEO `GET /processes` returns the full process metadata, while in OAP it only returns a summary.
142+
The general structure of the response of `GET /processes` is the same (`processes` and `links`).
143+
The OGC Process Description and the openEO process description are not compatible though.
144+
145+
openEO doesn't define an endpoint yet to retrieve an indivdual process such as
146+
`GET /processes/{processID}` in OAP.
147+
There is a [proposal](https://github.com/Open-EO/openeo-api/pull/348) available to add such an endpoint.
148+
openEO has the concept of namespace for processes though and thus defines the endpoint at
149+
`GET /processes/{namespace}/{process}` which would conflict with OAP.
150+
151+
Some notable differences in the process description:
152+
- OAP defines `jobControlOptions`, which is
153+
[undefined in openEO](https://github.com/Open-EO/openeo-api/issues/429) yet
154+
- OAP defines `outputTransmission`, which is
155+
[probably](https://github.com/opengeospatial/ogcapi-processes/issues/326) not available in openEO
156+
- OAP allows multiple outputs, openEO only allows a single output
157+
(potential workaround: wrap in an array or object)
158+
159+
Below is a simple process encoded in the two variants discussed here:
160+
- [OGC Process Description](oap-echo-example.json)
161+
- [openEO Process](openeo-echo-example.json)
162+
163+
### User-defined processes
164+
165+
TBD, lower priority as it's not covered by OAP.
166+
167+
## Data Processing
168+
169+
### Synchronous processing
170+
171+
### Batch Job processing
172+
173+
### On-demand processing
174+
175+
TBD, lower priority as it's not covered by OAP.
176+
177+
## File Storage
178+
179+
- openEO: `/files` (various methods), `/files/{path}` (various methods)
180+
- OAP: n/a
181+
182+
As it is neither available in OAP nor in any of the OGC APIs, we don't make any comparisons here.
183+
184+
## Data Access and Visualization
185+
186+
TBD, lower priority as it's not covered by OAP.

‎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)