Skip to content

Commit fd26251

Browse files
m-mohrm-mohr
authored
Guidelines and processes to run OGC API - Processes / CWL / EOAP (#520)
* Implementation guidelines for EOAP #507
1 parent 4422c60 commit fd26251

File tree

5 files changed

+177
-3
lines changed

5 files changed

+177
-3
lines changed

‎CHANGELOG.md

+3
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88

99
### Added
1010

11+
- Implementation guide for implementing OGC API - Processes in openEO
1112
- `export_collection`
1213
- `export_workspace`
14+
- `run_ogcapi`
15+
- `run_ogcapi_externally`
1316
- `stac_modify`
1417

1518
### Changed

‎dev/.words

+1
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,4 @@ Hyndman
4848
date1
4949
date2
5050
favor
51+
Undeploy

‎meta/implementation.md

+69-3
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ For the data types boolean, numbers, strings and null it is recommended to log t
164164

165165
It is recommended to summarize arrays as follows:
166166

167-
```js
167+
```json5
168168
{
169169
"data": [3,1,6,4,8], // Return a reasonable excerpt of the data, e.g. the first 5 or 10 elements
170170
"length": 10, // Return the length of the array, this is important to determine whether the data above is complete or an excerpt
@@ -179,7 +179,7 @@ It is recommended to return them summarized in a structure compliant to the [STA
179179
If reasonsable, it gives a valuable benefit for users to provide all dimension labels (e.g. individual timestamps for the temporal dimension) instead of values ranges.
180180
The top-level object and/or each dimension can be enhanced with additional statstics if possible, ideally use the corresponsing openEO process names as keys.
181181

182-
```js
182+
```json5
183183
{
184184
"cube:dimensions": {
185185
"x": {
@@ -250,4 +250,70 @@ If the underlying STAC resource is part of an API, the following HTTP endpoints
250250
according to the [Transaction Extension](https://github.com/stac-api-extensions/transaction)
251251
- For STAC Collections: `PATCH /collections/{collectionId}`
252252
according to the [Collection Transaction Extension](https://github.com/stac-api-extensions/collection-transaction)
253-
- For STAC Catalogs there is no API support for updates.
253+
- For STAC Catalogs there is no API support for updates.
254+
255+
## OGC API - Processes
256+
257+
OGC API - Processes and OGC EO Application Packages (AP) can generally be utilized in openEO in three different ways:
258+
259+
1. **openEO process**
260+
261+
As a pre-defined process that exposes itself as a normal openEO process.
262+
It is not exposed to the user that in the background an AP is invoked.
263+
2. **Pre-deployment through *OGC API - Processes - Part 2: Deploy, Replace, Undeploy***
264+
265+
In addition to the openEO API, a provider can offer access to an instance of *OGC API - Processes - Part 2: Deploy, Replace, Undeploy* (OGC DRU).
266+
The OGC DRU instance is likely external to the openEO API tree due to the conflicting `GET /processes` endpoint.
267+
As such the OGC DRU instance exposes itself in the `GET /` endpoint of the openEO API instance through a link.
268+
The link must have the relation type `http://www.opengis.net/def/rel/ogc/1.0/processes`, which points to the `/processes` of the OGC API - Processes endpoint.
269+
Users can deploy APs through the OGC DRU instance and use them through the process `run_ogcapi`.
270+
271+
If the provider doesn't offer an OGC DRU instance itself, users could also deploy their AP with another provider.
272+
In this case use the process `run_ogcapi_externally` instead.
273+
274+
Example process node:
275+
276+
```json5
277+
{
278+
"process_id": "run_ogcapi",
279+
"arguments": {
280+
"data": ..., // Data, e.g. subtypes datacube or stac
281+
"id": "my-ap", // Identifier of the application package in OGC API - Processes
282+
"context": { // Parameters as defined in the CWL file
283+
"cwl_param1": true,
284+
"param2": 99
285+
}
286+
}
287+
}
288+
```
289+
3. **CWL provided at runtime (UDF runtime)**
290+
291+
Providers can also provide a UDF runtime for the language CWL (instead of e.g. Python or R).
292+
The runtime is exposed through the endpoint `GET /udf_runtimes`.
293+
294+
Example process node:
295+
296+
```json5
297+
{
298+
"process_id": "run_udf",
299+
"arguments": {
300+
"data": ..., // Data, e.g. subtypes datacube or stac
301+
"udf": "...", // CWL as YAML string/JSON object, URL, or file on the API user workspace
302+
"runtime": "cwl", // Assuming the UDF runtime is named "cwl"
303+
"context": { // Parameters as defined in the CWL file
304+
"cwl_param1": true,
305+
"param2": 99
306+
}
307+
}
308+
}
309+
```
310+
311+
Generally, we recommend to use the following types and formats for the CWL inputs and outputs:
312+
313+
- `type`: `File` or `File[]` depending on the capabilities of the CWL workflow
314+
- `format`: For STAC inputs and outputs either:
315+
- `stac`: any of the following STAC entities
316+
- `stac-catalog`: STAC Catalog
317+
- `stac-collection`: STAC Collection
318+
- `stac-item`: STAC Item
319+
- `stac-item-collection`: STAC (API) ItemCollection

‎proposals/run_ogcapi.json

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{
2+
"id": "run_ogcapi",
3+
"summary": "Run a OGC API process",
4+
"description": "Runs an OGC API - Processes process that the service provider offers through an instance of OGC API - Processes - Part 2 (Deploy, Replace, Undeploy).",
5+
"categories": [
6+
"cubes",
7+
"import",
8+
"udf"
9+
],
10+
"experimental": true,
11+
"parameters": [
12+
{
13+
"name": "data",
14+
"description": "The data to be passed to the OGC API process.\n\nThe data must be given in a way that the external process can understand it.",
15+
"schema": {
16+
"description": "A value of any data type."
17+
}
18+
},
19+
{
20+
"name": "id",
21+
"description": "The identifier of the OGC API process.",
22+
"schema": {
23+
"type": "string"
24+
}
25+
},
26+
{
27+
"name": "context",
28+
"description": "Additional parameters as defined by the OGC API process.",
29+
"schema": {
30+
"type": "object"
31+
},
32+
"default": {},
33+
"optional": true
34+
}
35+
],
36+
"exceptions": {
37+
"InvalidOgcApiProcess": {
38+
"message": "The specified OGC API process identifier does not exist."
39+
}
40+
},
41+
"returns": {
42+
"description": "The data processed by the OGC API process. The returned value can be of any data type and is exactly what the OGC API process returns.",
43+
"schema": {
44+
"description": "Any data type."
45+
}
46+
}
47+
}

‎proposals/run_ogcapi_externally.json

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"id": "run_ogcapi_externally",
3+
"summary": "Run an externally hosted OGC API process",
4+
"description": "Runs an OGC API - Processes process that is either externally hosted by a service provider or running on a local machine of the user.",
5+
"categories": [
6+
"cubes",
7+
"import",
8+
"udf"
9+
],
10+
"experimental": true,
11+
"parameters": [
12+
{
13+
"name": "data",
14+
"description": "The data to be passed to the external process.\n\nThe data must be given in a way that the external process can understand it.",
15+
"schema": {
16+
"description": "A value of any data type."
17+
}
18+
},
19+
{
20+
"name": "url",
21+
"description": "Absolute URL to the OGC API - Processes landing page.",
22+
"schema": {
23+
"type": "string",
24+
"format": "uri",
25+
"subtype": "uri",
26+
"pattern": "^https?://"
27+
}
28+
},
29+
{
30+
"name": "id",
31+
"description": "The identifier of the OGC API process.",
32+
"schema": {
33+
"type": "string"
34+
}
35+
},
36+
{
37+
"name": "context",
38+
"description": "Additional parameters as defined by the OGC API process.",
39+
"schema": {
40+
"type": "object"
41+
},
42+
"default": {},
43+
"optional": true
44+
}
45+
],
46+
"exceptions": {
47+
"InvalidOgcApiProcess": {
48+
"message": "The specified OGC API process does not exist."
49+
}
50+
},
51+
"returns": {
52+
"description": "The data processed by the OGC API process. The returned value can be of any data type and is exactly what the OGC API process returns.",
53+
"schema": {
54+
"description": "Any data type."
55+
}
56+
}
57+
}

0 commit comments

Comments
 (0)