Crosswalk with OGC API - Processes

crosswalks/oap-echo-example.json

@@ -0,0 +1,69 @@
+{
+  "id": "EchoProcess",
+  "title": "Echo Process",
+  "description": "This process accepts and number of input and simple echoes each input as an output.",
+  "version": "1.0.0",
+  "jobControlOptions": [
+    "async-execute",
+    "sync-execute"
+  ],
+  "outputTransmission": [
+    "value",
+    "reference"
+  ],
+  "inputs": {
+    "stringInput": {
+      "title": "String Literal Input Example",
+      "description": "This is an example of a STRING literal input.",
+      "schema": {
+        "type": "string",
+        "enum": [
+          "Value1",
+          "Value2",
+          "Value3"
+        ]
+      },
+      "doubleInput": {
+        "title": "Bounded Double Literal Input Example",
+        "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.",
+        "schema": {
+          "type": "number",
+          "format": "double",
+          "minimum": 0,
+          "maximum": 10,
+          "default": 5,
+          "exclusiveMinimum": true
+        }
+      }
+    }
+  },
+  "outputs": {
+    "stringOutput": {
+      "schema": {
+        "type": "string",
+        "enum": [
+          "Value1",
+          "Value2",
+          "Value3"
+        ]
+      }
+    },
+    "doubleOutput": {
+      "schema": {
+        "type": "number",
+        "format": "double",
+        "minimum": 0,
+        "maximum": 10,
+        "default": 5,
+        "exclusiveMinimum": true
+      }
+    }
+  },
+  "links": [
+    {
+      "href": "https://processing.example.org/oapi-p/processes/EchoProcess/execution",
+      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
+      "title": "Execute endpoint"
+    }
+  ]
+}

crosswalks/ogcapi-processes.md

@@ -0,0 +1,186 @@
+# Crosswalk between openEO API and OGC API - Processes
+
+This document gives a brief overview over similarities and differences between
+- **openEO API, v1.2.0**
+- **OGC API - Processes - Part 1: Core, v1.0.0**
+
+In the following I use **OAP** as an abbreviation for **OGC API - Processes - Part 1**.
+
+## General
+
+OCG API - Processes defines just processing, while the openEO API has a much broader scope.
+openEO covers many parts that other OGC API specifications define, some are aligned some are not.
+
+The openEO API covers the following "categories" of endpoints:
+- [API discovery](#api-discovery) - partially covered by OGC API - Processes - Part 1
+- [Authentication](#authentication) - not defined by OGC
+- [Data Discovery](#data-discovery) - covered by various other OGC APIs (Coverages, EDR, Features, Records, ...)
+- [Process Discovery](#process-discovery) - covered by OGC API - Processes - Part 1
+  - [Pre-defined processes](#pre-defined-processes) - covered by OGC API - Processes - Part 1
+  - [User-defined processes](#user-defined-processes) - covered by OGC API - Processes - Part 2 and 3
+- [Data Processing](#data-processing) - covered by OGC API - Processes - Part 1 and 3
+  - [Synchronous processing](#synchronous-processing) - covered by OGC API - Processes - Part 1
+  - [Batch Job processing](#batch-job-processing) - covered by OGC API - Processes - Part 1
+  - [On-demand processing](#on-demand-processing) - covered by other OGC APIs (Maps, Tiles, ...)
+- [File Storage](#file-storage) - not covered by OGC APIs
+- [Data Access and Visualization](#data-access-and-visualization) - covered by other OGC APIs (Coverages, Features, Maps, Tiles, ...)
+
+Both APIs use HTTP as the basis and encourage HTTPS.
+HTTP 1.1 is required for OAP, while openEO doesn't specify a specific HTTP version.
+The APIs follow REST principles and make use of HTTP content negotiation.
+The APIs make broad use of "Web Linking" (compatible between OAP and openEO).
+Both specifications recommend the implementation of CORS.
+
+The default encoding for requests and response bodies is JSON. OGC API recommends to also support
+HTML as an response body encoding. openEO uses client software to render HTML output from JSON.
+
+Both specifications make broad use of OpenAPI 3.0 and JSON Schema for specification purposes.
+
+Many API endpoints in OAP and openEO support pagination through links with the relation types `next`
+and `prev`. These endpoints have a `limit` parameter to enable pagination for a specific page size.
+**Note:** Pagination is rarely used in openEO implementations and most clients don't support it consistently.
+
+## API discovery
+
+Discovering the API, connecting to it and reading the capabilities is always the first step clients
+need to execute.
+
+### Well-known document
+
+- openEO: `GET /.well-known/openeo`
+- OAP: n/a
+
+openEO clients usually connect to the well-known document first to discover different versions or 
+implementations of a server. Thus a client can choose a suitable API versions inclusing choosing
+between production and development instances. Then the openEO client connects to the selected
+instance's [landing page](#landing-page), which OGC API - Processes clients always directly connect
+to. openEO clients can usually also directly connect to the landing page though.
+
+This folder structure with the document resides usually outside of the actual API implementations,
+i.e. in the root of the host or domain.
+
+### Landing page
+
+- openEO: `GET /` (required)
+- OAP: `GET /` (required)
+
+As the landing pages both are based on top of OGC API - Common, they are very similar.
+
+Some differences include:
+- openEO requires the following additional fields:
+  - Defined in OAP, but not required: `title`, `description`
+  - Not defined in OAP: `api_version`, `backend_version`, `stac_version`, `id`, `endpoints`, (`type`)
+- The relation type to link to the conformance classes is `conformance` in openEO (originating from
+  OGC API - Features / STAC API) and `http://www.opengis.net/def/rel/ogc/1.0/conformance` in OAP.
+  Two links with the same target but different relation types will be required.
+- The existance of API endpoints in openEO is primarily checked through `endpoints`, which is
+  not present in OAP. OAP uses links, which openEO primarily uses for non-API-related links.
+  Nevertheless, links such as required in OAP can be added easily to an openEO implementation.
+  The following additionl links are relevant for OAP:
+  - One of the link relations `service-desc` or `service-doc` is required in OAP. They should link
+    to an API description (e.g. OpenAPI or rendered HTML version).
+  - A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/processes` to `/processes` is 
+    required for OAP, but not in openEO.
+  - A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/job-list` to `/jobs` can be
+    added in OAP, but is not present in openEO.
+
+### Conformanc classes
+
+- openEO: `GET /conformance` (optional)
+- OAP: `GET /conformance` (required)
+
+Both endpoints are 100% equivalent.
+OAP requires a separate endpoint that lists conformance classes. 
+openEO additionally allows to list the conformance classes in the landing page (follows STAC API).
+Conformance classes are only fully defined since openEO API v1.2.0.
+
+## Authentication
+
+- openEO: `GET /credentials/basic` and/or `GET /credentials/oidc`
+- OAP: n/a
+
+OpenEO defines two authentication mechanisms:
+- OpenID Connect (primary)
+- HTTP Basic (secondary, primarily for development/testing purposes)
+
+OAP doesn't define any authentication machanisms, but both authentication mechanisms can also be
+implemented for OAP. The main issue will be that OAP clients will likely not support them.
+
+The availability of the authentication mechanisms is detected through the `endpoints` in the 
+[landing page](#landing-page) in openEO, while in OAP you need to parse the OpenAPI document for it
+(which implicitly requires a link to an OpenAPI 3.0 file with relation type `service-desc` in the
+landing page).
+
+## Data Discovery
+
+Data Discovery is not covered by OAP, but it can be "plugged in" through various other OGC APIs
+(e.g. Coverages, EDR, Features, Records, ...). Except for OGC API - Processes - Part 3, it is not
+clear how the processes defined in OAP can access resources from the other APIs. The processes 
+probably need to implement data access individually through OGC API clients. As such, OAP could
+also be made compliant with STAC API - Collection and STAC API - Features. STAC API - Collections
+is required by openEO, STAC API - Features is optional in openEO, but would likely be required to
+allow data access through OAP processes.
+
+## Process Discovery
+
+OAP does not mandate the use of any specific process description to specify the interface of a
+process. It defines a "default" encoding in the conformance class "OGC Process Description" though.
+
+  TBC, there seems to be a
+  [conflicting statement](https://github.com/opengeospatial/ogcapi-processes/issues/325) in OAP.
+
+The openEO API specifies a single encoding for process descriptions.
+This means in principle that OAP can return openEO processes, but it has to be assumed that OAP 
+client will expect OGC Process Descriptions and won't be able to read openEO processes by default.
+
+### Pre-defined processes
+
+- openEO: `GET /processes` (required)
+- OAP: `GET /processes`,  `GET /processes/{processID}` (both required)
+
+In openEO `GET /processes` returns the full process metadata, while in OAP it only returns a summary.
+The general structure of the response of `GET /processes` is the same (`processes` and `links`).
+The OGC Process Description and the openEO process description are not compatible though.
+
+openEO doesn't define an endpoint yet to retrieve an indivdual process such as
+`GET /processes/{processID}` in OAP.
+There is a [proposal](https://github.com/Open-EO/openeo-api/pull/348) available to add such an endpoint.
+openEO has the concept of namespace for processes though and thus defines the endpoint at   
+`GET /processes/{namespace}/{process}` which would conflict with OAP.
+
+Some notable differences in the process description:
+- OAP defines `jobControlOptions`, which is
+  [undefined in openEO](https://github.com/Open-EO/openeo-api/issues/429) yet
+- OAP defines `outputTransmission`, which is
+  [probably](https://github.com/opengeospatial/ogcapi-processes/issues/326) not available in openEO
+- OAP allows multiple outputs, openEO only allows a single output
+  (potential workaround: wrap in an array or object)
+
+Below is a simple process encoded in the two variants discussed here:
+- [OGC Process Description](oap-echo-example.json)
+- [openEO Process](openeo-echo-example.json)
+
+### User-defined processes
+
+  TBD, lower priority as it's not covered by OAP.
+
+## Data Processing
+
+### Synchronous processing
+
+### Batch Job processing
+
+### On-demand processing
+
+  TBD, lower priority as it's not covered by OAP.
+
+## File Storage
+
+- openEO: `/files` (various methods),  `/files/{path}` (various methods)
+- OAP: n/a
+
+As it is neither available in OAP nor in any of the OGC APIs, we don't make any comparisons here.
+
+## Data Access and Visualization
+
+  TBD, lower priority as it's not covered by OAP.

crosswalks/openeo-echo-example.json

@@ -0,0 +1,59 @@
+{
+  "id": "EchoProcess",
+  "summary": "Echo Process",
+  "description": "This process accepts and number of input and simple echoes each input as an output.",
+  "parameters": [
+    {
+      "name": "stringInput",
+      "description": "This is an example of a STRING literal input.",
+      "schema": {
+        "type": "string",
+        "enum": [
+          "Value1",
+          "Value2",
+          "Value3"
+        ]
+      }
+    },
+    {
+      "name": "doubleInput",
+      "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.",
+      "schema": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 10,
+        "exclusiveMinimum": true
+      },
+      "optional": true,
+      "default": 5
+    }
+  ],
+  "returns": {
+    "schema": {
+      "type": "array",
+      "items": [
+        {
+          "type": "string",
+          "enum": [
+            "Value1",
+            "Value2",
+            "Value3"
+          ]
+        },
+        {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10,
+          "exclusiveMinimum": true
+        }
+      ]
+    }
+  },
+  "links": [
+    {
+      "href": "https://processing.example.org/openeo/processes/EchoProcess/execution",
+      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
+      "title": "Execute endpoint"
+    }
+  ]
+}