Part 3 Deployable Workflows - Analysis and Proposals

The Part 3: Deployable Workflows proposes an alternate deployment definition based on an execution body, trying to bridge Part 1/2/3.
I would like to validate my understanding of it, and propose adjustments to improve alignments (as applicable).

Since there are 2 variants for deployment, the 2 are analyzed separately, but using an equivalent workflow example.

Variant 1: Direct Deployment with Execution Body

Analysis

POST /processes
Content-Type: application/ogc-workflow+json

{
  "id": "DeployWorkflow",
  "version": "1.0",
  "process": "https://example.com/proceses/MainProcess",
  "inputs": {
    "main-in": {
      "process": "https://example.com/proceses/NestedProcess",
      "inputs": {
        "arg": { "$input": "wf-input" }
      }
    }
  },
  "outputs": {
    "out": { "$output": "wf-output" }
  }
} 

A new process named DeployWorkflow with input wf-input and output wf-output would be created.
The schema definition of wf-input would be the same as the one of arg from NestedProcess, whereas the schema of the wf-output would be equivalent to out of MainProcess.

Proposals

1. Add an id field, which is not present in processes-workflows/execute-workflows.yaml.

   • It is normal that id was missing considering it is not required for execution only.
     However, some process ID is needed to perform the deployment.

2. Alternatively to id, reuse ?w=<id> query (https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/parameters/processes-dru/w-param.yaml)

   • This has the advantage to reuse the same processes-workflows/execute-workflows.yaml definition without any modification. However, debatable whether it is intuitive or not.

3. Other required parameter version from Part 1 needs to be added.
   Since there is no equivalent query parameter, so it might be better to have the Part 3: Deployable Workflows schema be a
   oneOf[ process-core/processSummary, processes-workflows/execute-workflows ]

   This should be added to OpenAPI path /processes.

4. Introduce application/ogc-workflow+json (or some equivalent) to distinguish from other deployment structures already supported (CWL, OGC App Pkg, etc.).

5. This variant doesn't indicate how additional metadata for the resolved wf-input and wf-output can be defined.
   Recommendations to had to the document, either:

   • Consider this acceptable, meaning that they copy entirely what arg/out defined, nothing more, nothing less.
   • Allow additional properties to be indicated next to $input/$output to extend/override what arg/out provide.
   • Recommend to use Variant 2 instead for this use case.

Variant 2: Embedded Deployment of Execution Body in Execution Unit

Analysis

POST /processes
Content-Type: application/ogcapppkg+json

{
  "processDescription": {
    "id": "DeployWorkflow",
    "version": "1.0"
  },
  "executionUnit": {
    "format": { "mediaType": "application/ogc-workflow+json" },
    "value": {
    "process": "https://example.com/proceses/MainProcess",
    "inputs": {
      "main-in": {
        "process": "https://example.com/proceses/NestedProcess",
        "inputs": {
          "arg": { "$input": "wf-input" }
        }
      }
    },
    "outputs": {
      "out": { "$output": "wf-output" }
    }
    }
  }
}

Proposals

1. Because wf-input/arg and wf-output/out schemas should be aligned to be mapped correctly, redefining inputs and outputs with schemas explicitly in processDescription is redundant. However, this would not be disallowed according to processes-core/process.yaml.

   • Recommendations should be given in the standard document about this case.

     More specifically, processDescription.inputs and processDescription.outputs could be relevant to provide additional details, such as process-core/descriptionType.yaml metadata properties.
     However, adding any inputs/outputs there would fail validation if the schema is omitted, since it is required in their definitions. Because of this, we end up going back to redundant schema definitions mentioned above.

   Possible recommendations:

   1. Use

      {
        "inputs": {
          "wf-input": {
            "title": "Workflow Input",
            "schema": {}
          }
        }
      }
      

      And indicate that schema should be inferred by $input in this deployment use case.

   2. Recommend to explicitly reference the schema:

      {
        "inputs": {
          "wf-input": {
            "title": "Workflow Input",
            "schema": {"$ref": "https://example.com/proceses/NestedProcess#/inputs/arg/schema"}
          }
        }
      }
      

2. If Part 3: Fields Modifiers are thrown in the mix of Deployable Workflows, notably for the wf-input and wf-output, then the schema mapping between wf-input/arg and wf-output/out could actually differ entirely.

   In this case, contrary to previous (1), schema under processDescription.inputs and processDescription.outputs could become mandatory. This is because, without any reference schema from DeployWorkflow (yet to be deployed), the workflow could be validated if they were omitted, since there would be no indication of the intended source and desired result for field-modifed wf-input/wf-output.

3. Improve the description of Part 3: Deployable Workflows regarding media-type.
   The requirement mentions using application/ogcapppkg+json, but this can easily be confused with the case where processes-dru/executionUnit.yaml is employed directly.
   When an embedded execution unit definition is used, it is preferable to employ the qualified value with application/ogc-workflow+json to avoid ambiguity about the package contents (or use Variant 1 directly instead).

Start with the Deployable Workflows and Fields Modifiers sections, then compare processes-workflows/execute-workflows.yaml, processes-core/process.yaml, process-core/descriptionType.yaml, processes-dru/executionUnit.yaml, and processes-dru/w-param.yaml. Review both deployment variants and their media types. Done means the alternatives and schema or documentation changes have been resolved consistently in the standard and OpenAPI definitions.