CWL guidance improvements + Multipart Deploy/Replace

.gitignore

@@ -23,9 +23,15 @@ core/18-062.err
 core/18-062.xml
 core/18-062.presentation.xml
 core/18-062.rxl
-extensions/workflows/21-009.pdf
-extensions/workflows/21-009.html
-extensions/workflows/21-009.doc
-extensions/workflows/21-009.err
-extensions/workflows/21-009.xml
-extensions/workflows/21-009.presentation.xml
+extensions/deploy_replace_undeploy/**/20-044.pdf
+extensions/deploy_replace_undeploy/**/20-044.html
+extensions/deploy_replace_undeploy/**/20-044.doc
+extensions/deploy_replace_undeploy/**/20-044.err
+extensions/deploy_replace_undeploy/**/20-044.xml
+extensions/deploy_replace_undeploy/**/20-044.presentation.xml
+extensions/workflows/**/21-009.pdf
+extensions/workflows/**/21-009.html
+extensions/workflows/**/21-009.doc
+extensions/workflows/**/21-009.err
+extensions/workflows/**/21-009.xml
+extensions/workflows/**/21-009.presentation.xml

extensions/deploy_replace_undeploy/standard/20-044.adoc

@@ -9,7 +9,7 @@
 :published-date: yyyy-mm-dd
 :received-date: yyyy-mm-dd
 :issued-date: yyyy-mm-dd
-:external-id: http://www.opengis.net/doc/IS/ogcapi-processes-2/1.0
+:external-id: https://www.opengis.net/doc/IS/ogcapi-processes-2/1.0
 :keywords: process, collection, instance, spatial, data, openapi, transactions, insert, update, delete, add, remove, deploy, undeploy, REST, PUT, POST, DELETE
 :submitting-organizations: Geolabs; CubeWerx Inc; Terradue Srl.; Wuhan University (WHU); Centre de Recherche Informatique de Montréal (CRIM)
 :editor: Panagiotis (Peter) A. Vretanos, Gérald Fenoy

extensions/deploy_replace_undeploy/standard/recommendations/cwl/deploy/REC_body-cwl-multipart.adoc

@@ -0,0 +1,99 @@
+[[rec_deploy-replace-undeploy_deploy_body_cwl_multipart]]
+[recommendation]
+====
+[%metadata]
+identifier:: /rec/deploy-replace-undeploy/deploy-body-cwl-multipart
+inherit:: <<rfc2387,RFC 2387 (The MIME Multipart/Related Content-type)>>
+description:: Recommendation for supporting multipart deployment of related CWL documents forming a process.
+
+[.component,class=part]
+--
+If a process requires the deployment of multiple <<rc_cwl,CWL>> documents to represent its execution unit
+(e.g.: a `class: Workflow` that depends on multiple other `steps` referring to separate `class: CommandLineTool` documents),
+a server MAY support a HTTP POST operation using `multipart/related` media-type (https://datatracker.ietf.org/doc/html/rfc2387[RFC 2387])
+as request `Content-Type` header.
+--
+
+[.component,class=part]
+--
+The media-type of each individual <<rc_cwl,CWL>> part in the multipart body SHOULD be specified by their
+respective part `Content-Type` header using `application/cwl`, `application/cwl+json` or `application/cwl+yaml`
+media-types in accordance to their respective content encoding.
+--
+
+[.component,class=part]
+--
+The <<rc_cwl,CWL>> parts of the multipart body SHOULD employ the `start`
+parameter (https://datatracker.ietf.org/doc/html/rfc2387#section-3.2[RFC 2387, section 3.2])
+within the request `Content-Type` header to indicate a part identifier of the part consisting
+of the main <<rc_cwl,CWL>> `Workflow` documents that invokes other `steps`.
+--
+
+[.component,class=part]
+--
+If the `start` parameter is not provided in the request `Content-Type` header, the <<rc_cwl,CWL>> part
+corresponding to the main `Workflow` document MAY include a part `Content-ID` header indicating a `#main`
+reference in accordance to <<https://www.commonwl.org/v1.2/CommandLineTool.html#Packed_documents,CWL Packed documents>>
+specification to identify itself as the main part of the multipart body.
+--
+
+[.component,class=part]
+--
+If no indication of `start` or `Content-ID` parameter can be resolved to identify the main <<rc_cwl,CWL>> part,
+the server MAY assume that the **first** part of the multipart body is the main one or use other means of
+identification outside the multipart body such as using <<req_cwl_w-param,/req/cwl/w-param>>.
+--
+
+[.component,class=part]
+--
+Part identifiers MAY be resolved using `Content-ID` header or an embedded `id` field within the <<rc_cwl,CWL>>
+content of each respective part, while request-level `Content-ID` header SHOULD be reserved for identifying
+the main `{processID}` resulting from the deployment of this multipart <<rc_cwl,CWL>> definition.
+--
+
+[.component,class=part]
+--
+Part identifiers SHOULD employ consistent values between `Content-ID`, embedded `id` field within the <<rc_cwl,CWL>>
+and `steps[*].run` references of other <<rc_cwl,CWL>> parts using them.
+--
+
+[.component,class=part]
+--
+If the main <<rc_cwl,CWL>> part employs `run` references to other `steps` referring to documents by file names
+(e.g.: `run: tools/tool-1.cwl`), the server
+SHOULD consider supporting a `Content-Disposition: attachment; filename="tools/tool-1.cwl"` header for each part
+to resolve the corresponding execution units that compose the process.
+--
+
+[.component,class=part]
+--
+If the main <<rc_cwl,CWL>> part employs `run` references to other `steps` referring to documents by unique IDs
+(e.g.: `run: "cid:tool-2@bundle.example"` or `run: "cid:urn:uuid:550e8400-e29b-41d4-a716-446655440002"`), the server
+SHOULD consider supporting a `Content-ID: <CID-ref@server>` header for each part to resolve the
+corresponding execution units that compose the process.
+--
+
+[.component,class=part]
+--
+If the main <<rc_cwl,CWL>> part employs `run` references to other `steps` referring to external document URIs
+(e.g.: `run: "https://repo.example.org/cwl/tools/tool-4.cwl"`), the server
+SHOULD consider supporting a `Content-Location` header that indicates the location of the original
+part content for traceability.
+--
+
+[.component,class=part]
+--
+A <<rc_cwl,CWL>> part that provides a `Content-Location` header
+MAY omit its corresponding content to let the server retrieve it from the indicated location,
+or include it explicitly to provide an alternative local copy of the content.
+--
+
+[.component,class=part]
+--
+Additional parts providing supplementary metadata information about the overall process being deployed
+(e.g.: using a process description or other profile negotiation by `Content-Profile` header) MAY be included
+using `Content-Type` media-types other than the ones reserved by the <<rc_cwl,CWL>> parts.
+Specific interpretation and parsing of such additional parts are outside the scope of this recommendation.
+--
+
+====

extensions/deploy_replace_undeploy/standard/recommendations/cwl/replace/REC_body-cwl-multipart.adoc

@@ -0,0 +1,20 @@
+[[rec_deploy-replace-undeploy_replace_body_cwl_multipart]]
+[recommendation]
+====
+[%metadata]
+identifier:: /rec/deploy-replace-undeploy/replace-body-cwl-multipart
+
+[.component,class=part]
+--
+A server MAY support process replacement encoded as <<rc_cwl,CWL>> using the same `multipart/related` content approach
+described in <<rec_deploy-replace-undeploy_deploy_body_cwl_multipart,/rec/deploy-replace-undeploy/deploy-body-cwl-multipart>>.
+--
+
+[.component,class=part]
+--
+A server MAY support replacing only partial <<rc_cwl,CWL>> parts of the full process definition
+by supplying only the relevant parts that require an update. Omitted parts SHOULD be considered as unchanged
+and retained from previous process definition deployment or updates.
+--
+
+====

extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_body.adoc

@@ -6,7 +6,20 @@ identifier:: /req/cwl/body
 
 [.component,class=part]
 --
-The media type `application/cwl` SHALL be used to indicate that request body contains a processes description encoded as <<rc_cwl,CWL>>.
+The media type `application/cwl` SHALL be used to indicate that request body contains a processes description
+encoded as <<rc_cwl,CWL>> of a generic encoding (JSON or YAML).
+--
+
+[.component,class=part]
+--
+If the <<rc_cwl,CWL>> encoding is known to be a JSON document,
+the request MAY employ `application/cwl+json` instead of `application/cwl` to advertise it more explicitly.
+--
+
+[.component,class=part]
+--
+If the <<rc_cwl,CWL>> encoding is known to be a YAML document,
+the request MAY employ `application/cwl+yaml` instead of `application/cwl` to advertise it more explicitly.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_execution-unit.adoc

@@ -6,19 +6,46 @@ identifier:: /req/cwl/execution-unit
 
 [.component,class=part]
 --
-If the execution unit is encoded in CWL, the content of the `executionUnit` parameter SHALL be an object with the following properties:
- * `type`  and `href` if passed by reference
- * `value` and `mediaType` property if passed by value
+If the execution unit is encoded in <<rc_cwl,CWL>>, the content of the `executionUnit` parameter SHALL be an object
+with the following properties:
+
+* `type` and `href` if passed by reference
+* `value` and `mediaType` if passed by qualified value
+--
+
+[.component,class=part]
+--
+If the execution unit is encoded in <<rc_cwl,CWL>> provided by reference with the `href` property,
+the value of the `type` property SHALL be `application/cwl` for a generic encoding (either JSON or YAML),
+`application/cwl+json` if the encoding is known to be a JSON document,
+or `application/cwl+yaml` if the encoding is known to be a YAML document.
+--
+
+[.component,class=part]
+--
+If the execution unit is encoded in <<rc_cwl,CWL>> provided by reference, the value of the `href` property SHALL
+be a reference to the <<rc_cwl,CWL>> encoded file in JSON or YAML format in accordance to the `type` property.
+--
+
+[.component,class=part]
+--
+If the execution unit is encoded in <<rc_cwl,CWL>> provided by qualified value with the `value` property,
+and content of that `value` are directly encoded as JSON object within the execution unit parameter,
+the value of the `mediaType` property SHALL be `application/cwl` or `application/cwl+json`.
 --
 
 [.component,class=part]
 --
-If the execution unit is encoded in CWL, the value of the `type` property SHALL be `application/cwl`, when for `mediaType` it should be `application/cwl+json`.
+If the execution unit is encoded in <<rc_cwl,CWL>> provided by qualified value with the `value` property,
+and content of that `value` are encoded as an embedded string representing JSON within the execution unit parameter,
+the value of the `mediaType` property SHALL be `application/cwl+json`.
 --
 
 [.component,class=part]
 --
-If the execution unit is encoded in CWL, the value of the `href` property SHALL be a reference to the CWL encoded file, when the value of the `value` property shall be the CWL encoded in JSON format.
+If the execution unit is encoded in <<rc_cwl,CWL>> provided by qualified value with the `value` property,
+and content of that `value` are encoded as an embedded string representing YAML within the execution unit parameter,
+the value of the `mediaType` property SHALL be `application/cwl+yaml`.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_body.adoc

@@ -6,7 +6,20 @@ identifier:: /req/cwl/deploy-body
 
 [.component,class=part]
 --
-The media type `application/cwl` SHALL be used to indicate that request body contains a processes description encoded as <<rc_ogcapppkg,CWL>>.
+The media type `application/cwl` indicated by the `Content-Type` header
+SHALL be used to indicate that request body contains a processes description encoded as <<rc_cwl,CWL>>.
 --
 
-====
+[.component,class=part]
+--
+If the <<rc_cwl,CWL>> encoding is known to be a JSON document,
+the request MAY employ `application/cwl+json` instead of `application/cwl` to advertise it more explicitly.
+--
+
+[.component,class=part]
+--
+If the <<rc_cwl,CWL>> encoding is known to be a YAML document,
+the request MAY employ `application/cwl+yaml` instead of `application/cwl` to advertise it more explicitly.
+--
+
+====

extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_exception-workflow-not-found.adoc

@@ -6,7 +6,8 @@ identifier:: /req/cwl/deploy-exception-workflow-not-found
 
 [.component,class=part]
 --
-If the `w` parameter has a value and the server cannot find the `w` identifier in the worflows from the body POST request, the status code SHALL be `400`.
+If the `w` parameter has a value and the server cannot find the `w` identifier in the workflows from the
+body `POST` request, the status code SHALL be `400`.
 --
 
 [.component,class=part]
@@ -16,7 +17,7 @@ The content of that response SHALL be based upon the schema https://raw.githubus
 
 [.component,class=part]
 --
-The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/workflow-not-found”.
+The `type` of the exception SHALL be `"https://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/workflow-not-found"`.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/cwl/package/REQ_response-body.adoc

@@ -6,10 +6,10 @@ identifier:: /req/cwl/package-response-body
 
 [.component,class=part]
 --
-A response with HTTP status code `200` SHALL include a body that contains:
- * the <<rc_cwl,CWL>> to use to deploy the process, in case the Content-Type used to deploy the process was `application/cwl`. 
- * the <<rc_ogcapppkg,OGC Application Package>> to use to deploy the process, in case the Content-Type used to deploy the process was `application/ogcapppkg+json`.
- 
+A response with HTTP status code `200` SHALL include a body that contains, by default:
+
+* the <<rc_cwl,CWL>> to use to deploy the process, in case the `Content-Type` used to deploy the process was `application/cwl`, `application/cwl+json`, or `application/cwl+yaml`.
+* the <<rc_ogcapppkg,OGC Application Package>> to use to deploy the process, in case the `Content-Type` used to deploy the process was `application/ogcapppkg+json`.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/cwl/replace/REQ_body.adoc

@@ -6,7 +6,20 @@ identifier:: /req/cwl/replace-body
 
 [.component,class=part]
 --
-The media type `application/cwl` SHALL be used to indicate that request body contains a processes description encoded as <<rc_ogcapppkg,CWL>>.
+The media type `application/cwl` indicated by the `Content-Type` header
+SHALL be used to indicate that request body contains a processes description encoded as <<rc_cwl,CWL>>.
 --
 
-====
+[.component,class=part]
+--
+If the <<rc_cwl,CWL>> encoding is known to be a JSON document,
+the request MAY employ `application/cwl+json` instead of `application/cwl` to advertise it more explicitly.
+--
+
+[.component,class=part]
+--
+If the <<rc_cwl,CWL>> encoding is known to be a YAML document,
+the request MAY employ `application/cwl+yaml` instead of `application/cwl` to advertise it more explicitly.
+--
+
+====

extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-duplicate.adoc

@@ -22,7 +22,7 @@ The content of that response SHALL be based upon the OpenAPI
 
 [.component,class=part]
 --
-The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/duplicated-process”.
+The `type` of the exception SHALL be “https://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/duplicated-process”.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-immutable.adoc

@@ -22,7 +22,7 @@ The content of that response shall be based upon the OpenAPI
 
 [.component,class=part]
 --
-The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/immutable-process”.
+The `type` of the exception SHALL be “https://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/immutable-process”.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_unsupported-media-type.adoc

@@ -17,7 +17,7 @@ The content of that response SHALL be based upon the OpenAPI
 
 [.component,class=part]
 --
-The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/unsupported-media-type”.
+The `type` of the exception SHALL be “https://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/unsupported-media-type”.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/replace/REQ_put-op.adoc

@@ -6,12 +6,12 @@ identifier:: /req/deploy-replace-undeploy/replace-put-op
 
 [.component,class=part]
 --
-For every dynamically deployed processes (path '/processes/{processID}'), the server SHALL support the HTTP PUT operation.
+For every dynamically deployed processes (path `/processes/{processID}`), the server SHALL support the HTTP PUT operation.
 --
 
 [.component,class=part]
 --
-The parameter 'processID' is each 'id' property in the process collection response (JSONPath: `$.processes[*].id`).
+The parameter `processID` is each `id` property in the process collection response (JSONPath: `$.processes[*].id`).
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/docker/REQ_execution-unit.adoc

@@ -6,7 +6,9 @@ identifier:: /req/docker/execution-unit
 
 [.component,class=part]
 --
-If the execution unit is specified as a Docker image, the  value of the `type` property SHALL be `docker'.
+If the execution unit is specified as a Docker image, the value of the `type` property from the
+https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-dru/executionUnit.yaml[executionUnit.yaml]
+schema SHALL be `docker`.
 --
 
 [.component,class=part]

extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_profile-docker.adoc

@@ -6,7 +6,7 @@ identifier:: /req/ogcapppkg/profile-docker
 
 [.component,class=part]
 --
-If the execution unit is a Docker image, the value of the `deploymentProfile` property shall be `http://www.opengis.net/profiles/eoc/dockerizedApplication`.
+If the execution unit is a Docker image, the value of the `deploymentProfile` property shall be `https://www.opengis.net/profiles/eoc/dockerizedApplication`.
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_schema.adoc

@@ -6,7 +6,7 @@ identifier:: /req/ogcapppkg/schema
 
 [.component,class=part]
 --
-An `OGC Application Package` document SHALL be based upon the OpenAPI schema http://schemas.opengis.net/ogcapi/processes/part2/1.0/openapi/schemas/ogcapppkg.yaml[ogcapppkg.yaml].
+An <<rc_ogcapppkg,OGC Application Package>> document SHALL be based upon the OpenAPI schema https://schemas.opengis.net/ogcapi/processes/part2/1.0/openapi/schemas/ogcapppkg.yaml[ogcapppkg.yaml].
 --
 
 ====

extensions/deploy_replace_undeploy/standard/requirements/requirements_class_cwl.adoc

@@ -3,12 +3,12 @@
 .Requirements Class 'CWL'
 ====
 [%metadata]
-identifier:: http://www.opengis.net/spec/ogcapi-processes-2/1.0/req/cwl
+identifier:: https://www.opengis.net/spec/ogcapi-processes-2/1.0/req/cwl
 obligation:: requirement
 subject:: Web API
 inherit:: <<OAProc-1,OGC API - Processes - Part 1: Core>>
-inherit:: <<rc_deploy-replace-undeploy,http://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeploy>>
-inherit:: <<rc_ogcapppkg,http://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkg>>
+inherit:: <<rc_deploy-replace-undeploy,https://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeploy>>
+inherit:: <<rc_ogcapppkg,https://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkg>>
 inherit:: Common Workflow Language <<Common_Workflow_Language>>
 requirement:: /req/cwl/body
 requirement:: /req/cwl/deploy-body