diff --git a/.gitignore b/.gitignore index 78a66dd8..e6f639e6 100644 --- a/.gitignore +++ b/.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 diff --git a/extensions/deploy_replace_undeploy/standard/20-044.adoc b/extensions/deploy_replace_undeploy/standard/20-044.adoc index 68660027..1090952a 100644 --- a/extensions/deploy_replace_undeploy/standard/20-044.adoc +++ b/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 diff --git a/extensions/deploy_replace_undeploy/standard/recommendations/cwl/deploy/REC_body-cwl-multipart.adoc b/extensions/deploy_replace_undeploy/standard/recommendations/cwl/deploy/REC_body-cwl-multipart.adoc new file mode 100644 index 00000000..8d01a3e2 --- /dev/null +++ b/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:: <> +description:: Recommendation for supporting multipart deployment of related CWL documents forming a process. + +[.component,class=part] +-- +If a process requires the deployment of multiple <> 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 <> 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 <> 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 <> `Workflow` documents that invokes other `steps`. +-- + +[.component,class=part] +-- +If the `start` parameter is not provided in the request `Content-Type` header, the <> part +corresponding to the main `Workflow` document MAY include a part `Content-ID` header indicating a `#main` +reference in accordance to <> +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 <> 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 <>. +-- + +[.component,class=part] +-- +Part identifiers MAY be resolved using `Content-ID` header or an embedded `id` field within the <> +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 <> definition. +-- + +[.component,class=part] +-- +Part identifiers SHOULD employ consistent values between `Content-ID`, embedded `id` field within the <> +and `steps[*].run` references of other <> parts using them. +-- + +[.component,class=part] +-- +If the main <> 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 <> 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: ` header for each part to resolve the +corresponding execution units that compose the process. +-- + +[.component,class=part] +-- +If the main <> 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 <> 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 <> parts. +Specific interpretation and parsing of such additional parts are outside the scope of this recommendation. +-- + +==== diff --git a/extensions/deploy_replace_undeploy/standard/recommendations/cwl/replace/REC_body-cwl-multipart.adoc b/extensions/deploy_replace_undeploy/standard/recommendations/cwl/replace/REC_body-cwl-multipart.adoc new file mode 100644 index 00000000..d56331a2 --- /dev/null +++ b/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 <> using the same `multipart/related` content approach +described in <>. +-- + +[.component,class=part] +-- +A server MAY support replacing only partial <> 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. +-- + +==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_body.adoc b/extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_body.adoc index 5a2c3d16..d7803361 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_body.adoc +++ b/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 <>. +The media type `application/cwl` SHALL be used to indicate that request body contains a processes description +encoded as <> of a generic encoding (JSON or YAML). +-- + +[.component,class=part] +-- +If the <> 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 <> encoding is known to be a YAML document, +the request MAY employ `application/cwl+yaml` instead of `application/cwl` to advertise it more explicitly. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_execution-unit.adoc b/extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_execution-unit.adoc index 511d0438..b59e291c 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/cwl/REQ_execution-unit.adoc +++ b/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 <>, 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 <> 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 <> provided by reference, the value of the `href` property SHALL +be a reference to the <> encoded file in JSON or YAML format in accordance to the `type` property. +-- + +[.component,class=part] +-- +If the execution unit is encoded in <> 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 <> 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 <> 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`. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_body.adoc b/extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_body.adoc index 4a56ccfb..dd0ecf71 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_body.adoc +++ b/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 <>. +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 <>. -- -==== \ No newline at end of file +[.component,class=part] +-- +If the <> 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 <> encoding is known to be a YAML document, +the request MAY employ `application/cwl+yaml` instead of `application/cwl` to advertise it more explicitly. +-- + +==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_exception-workflow-not-found.adoc b/extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_exception-workflow-not-found.adoc index 0b7e6099..a2a245ba 100755 --- a/extensions/deploy_replace_undeploy/standard/requirements/cwl/deploy/REQ_exception-workflow-not-found.adoc +++ b/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"`. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/cwl/package/REQ_response-body.adoc b/extensions/deploy_replace_undeploy/standard/requirements/cwl/package/REQ_response-body.adoc index 5d7791b6..b2e21a70 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/cwl/package/REQ_response-body.adoc +++ b/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 <> to use to deploy the process, in case the Content-Type used to deploy the process was `application/cwl`. - * the <> 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 <> 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 <> to use to deploy the process, in case the `Content-Type` used to deploy the process was `application/ogcapppkg+json`. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/cwl/replace/REQ_body.adoc b/extensions/deploy_replace_undeploy/standard/requirements/cwl/replace/REQ_body.adoc index e7b5b65c..816e6704 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/cwl/replace/REQ_body.adoc +++ b/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 <>. +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 <>. -- -==== \ No newline at end of file +[.component,class=part] +-- +If the <> 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 <> encoding is known to be a YAML document, +the request MAY employ `application/cwl+yaml` instead of `application/cwl` to advertise it more explicitly. +-- + +==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-duplicate.adoc b/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-duplicate.adoc index e4922d8e..fffe6af7 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-duplicate.adoc +++ b/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”. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-immutable.adoc b/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-immutable.adoc index 6e9267bf..9c2f12dc 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_response-immutable.adoc +++ b/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”. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_unsupported-media-type.adoc b/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_unsupported-media-type.adoc index 7f66dcc4..0965c918 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/deploy/REQ_unsupported-media-type.adoc +++ b/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”. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/replace/REQ_put-op.adoc b/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/replace/REQ_put-op.adoc index 3324f8f1..a7908a7a 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/deploy-replace-undeploy/replace/REQ_put-op.adoc +++ b/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`). -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/docker/REQ_execution-unit.adoc b/extensions/deploy_replace_undeploy/standard/requirements/docker/REQ_execution-unit.adoc index d77ab267..5435f06d 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/docker/REQ_execution-unit.adoc +++ b/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] diff --git a/extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_profile-docker.adoc b/extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_profile-docker.adoc index 18e00de4..ac20ce62 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_profile-docker.adoc +++ b/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`. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_schema.adoc b/extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_schema.adoc index e32eab3c..bf16d4b9 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/ogcapppkg/REQ_schema.adoc +++ b/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 <> document SHALL be based upon the OpenAPI schema https://schemas.opengis.net/ogcapi/processes/part2/1.0/openapi/schemas/ogcapppkg.yaml[ogcapppkg.yaml]. -- ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_cwl.adoc b/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_cwl.adoc index 93c0be13..9973af0c 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_cwl.adoc +++ b/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:: <> -inherit:: <> -inherit:: <> +inherit:: <> +inherit:: <> inherit:: Common Workflow Language <> requirement:: /req/cwl/body requirement:: /req/cwl/deploy-body diff --git a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_deploy-replace-undeploy.adoc b/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_deploy-replace-undeploy.adoc index faf54106..551087eb 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_deploy-replace-undeploy.adoc +++ b/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_deploy-replace-undeploy.adoc @@ -3,7 +3,7 @@ .Requirements Class 'Deploy, Replace, Undeploy' ==== [%metadata] -identifier:: http://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeploy +identifier:: https://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeploy obligation:: requirement subject:: Web API inherit:: <> diff --git a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_docker.adoc b/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_docker.adoc index c9afc54d..f5cb8541 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_docker.adoc +++ b/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_docker.adoc @@ -3,12 +3,12 @@ .Requirements Class 'Docker' ==== [%metadata] -identifier:: http://www.opengis.net/spec/ogcapi-processes-2/1.0/req/docker +identifier:: https://www.opengis.net/spec/ogcapi-processes-2/1.0/req/docker obligation:: requirement subject:: Web API inherit:: <> -inherit:: <> -inherit:: <> +inherit:: <> +inherit:: <> requirement:: /req/docker/execution-unit requirement:: /req/docker/schema ==== diff --git a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_ogcapppkg.adoc b/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_ogcapppkg.adoc index 0e020fc0..beffe888 100644 --- a/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_ogcapppkg.adoc +++ b/extensions/deploy_replace_undeploy/standard/requirements/requirements_class_ogcapppkg.adoc @@ -3,11 +3,11 @@ .Requirements Class 'OGC Application Package' ==== [%metadata] -identifier:: http://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkg +identifier:: https://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkg obligation:: requirement subject:: Web API inherit:: <> -inherit:: <> +inherit:: <> requirement:: /req/ogcapppkg/body requirement:: /req/ogcapppkg/deploy-body requirement:: /req/ogcapppkg/package-response-body diff --git a/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc b/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc index 44af1ba3..776a2f95 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc @@ -12,7 +12,7 @@ The following requirements apply for a server implementing the OGC API — P include::../abstract_tests/dru/ATS_mutable-process.adoc[] -In case both an OGC Application Package and CWL conformance classes are supported, the following requirement applies for a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy being tested: +In case both an <> and <> conformance classes are supported, the following requirement applies for a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy being tested: include::../abstract_tests/dru/ATS_test-process.adoc[] diff --git a/extensions/deploy_replace_undeploy/standard/sections/annex_history.adoc b/extensions/deploy_replace_undeploy/standard/sections/annex_history.adoc index 7ae2662e..8ba07364 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/annex_history.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/annex_history.adoc @@ -20,4 +20,7 @@ |2024-04-26 |None |Gérald Fenoy |all |Add section for retrieving formal description of a mutable process |2026-04-08 |None |Francis Charette-Migneault |all |Update format rendering of code snippets |2026-04-13 |None |Francis Charette-Migneault |all |Fix req/rec/per definitions format and references. +|2026-05-27 |None |Francis Charette-Migneault |all |Replace HTTP by HTTPS for requirement/conformance class references. +|2026-05-27 |None |Francis Charette-Migneault |CWL |Add multiple clarifications to CWL media-type and their operations. +|2026-05-27 |None |Francis Charette-Migneault |CWL |Add CWL multipart deployment details and guidance. |=== diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_11_media_types.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_11_media_types.adoc index 82e621ec..b30d9db0 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_11_media_types.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_11_media_types.adoc @@ -5,9 +5,10 @@ See <>, Clause 13. Additional JSON media types that would typically be used in a server that supports JSON are: -* application/ogcapppkg+json -* application/cwl+json +* `application/ogcapppkg+json` +* `application/cwl+json` Additional CWL media types that would typically be used in a server that supports CWL are: -* application/cwl \ No newline at end of file +* `application/cwl` +* `application/cwl+yaml` diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_3_references.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_3_references.adoc index 56054182..637d25c9 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_3_references.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_3_references.adoc @@ -7,3 +7,5 @@ * [[[OAFeat-1,OGC 17-069r3]]], OGC 17-069r3, OGC API - Features - Part 1: Core * [[rfc6902,IETF RFC 6902]] Bryan, P., Nottingham, M.: IETF RFC 6902, *JavaScript Object Notation (JSON) Patch*, 2013 http://tools.ietf.org/rfc/rfc6902.txt + +* [[rfc2387,IETF RFC 2387]] E. Levinson: IETF RFC 2387, *The MIME Multipart/Related Content-type*, 1998 http://tools.ietf.org/rfc/rfc2387.txt diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc index 0cb68a3c..38a7b100 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc @@ -60,12 +60,12 @@ More specific guidance is provided for each resource, where applicable. include::../recommendations/deploy-replace-undeploy/PER_additional-status-codes.adoc[] -The API Description Document describes the HTTP status codes generated by that API imeplementation instance. This should not be an exhaustive list of all possible status codes. It is not reasonable to expect an API designer to control the use of HTTP status codes which are not generated by their software. Therefore, it is recommended that the API Description Document be limited to describing HTTP status codes relevant to the proper operation of the API application logic. Client implementations should be prepared to receive HTTP status codes in addition to those described in the API Description Document. +The API Description Document describes the HTTP status codes generated by that API implementation instance. This should not be an exhaustive list of all possible status codes. It is not reasonable to expect an API designer to control the use of HTTP status codes which are not generated by their software. Therefore, it is recommended that the API Description Document be limited to describing HTTP status codes relevant to the proper operation of the API application logic. Client implementations should be prepared to receive HTTP status codes in addition to those described in the API Description Document. [[cross_origin]] ==== Cross-origin requests -See <>, section link:http://www.opengis.net/doc/IS/ogcapi-features-1/1.0#cross_origin[Support for cross-origin requests], about the importance of supporting cross-origin requests, typically via link:https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing (CORS)]. +See <>, section link:https://www.opengis.net/doc/IS/ogcapi-features-1/1.0#cross_origin[Support for cross-origin requests], about the importance of supporting cross-origin requests, typically via link:https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing (CORS)]. === Immutable processes diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc index 452dd803..f66ff8a2 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc @@ -24,7 +24,7 @@ The information contained in an `OGC Application Package` can include: include::../requirements/ogcapppkg/REQ_schema.adoc[] [[schema_ogcappkg]] -.link:http://schemas.opengis.net/ogcapi/processes/part2/1.0/openapi/schemas/ogcapppkg.yaml[Schema for the OGC Application Package] +.link:https://schemas.opengis.net/ogcapi/processes/part2/1.0/openapi/schemas/ogcapppkg.yaml[Schema for the OGC Application Package] [source,yaml] ---- include::../../../../openapi/schemas/processes-dru/ogcapppkg.yaml[] @@ -41,7 +41,7 @@ include::../requirements/ogcapppkg/REQ_process-description.adoc[] [[executionUnit]] ==== executionUnit property -If the schema defined for the executionUnit property of an OGC Application Package remains open, it can be restricted in other Requirements. +If the schema defined for the `executionUnit` property of an OGC Application Package remains open, it can be restricted in other Requirements. include::../recommendations/ogcapppkg/REC_execution-unit-docker.adoc[] @@ -63,4 +63,4 @@ include::../requirements/ogcapppkg/replace/REQ_body.adoc[] ==== OGC Application Package content -include::../requirements/ogcapppkg/package/REQ_response-body.adoc[] \ No newline at end of file +include::../requirements/ogcapppkg/package/REQ_response-body.adoc[] diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_8_docker.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_8_docker.adoc index 2dc43860..13cbf902 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_8_docker.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_8_docker.adoc @@ -7,7 +7,7 @@ include::../requirements/requirements_class_docker.adoc[] A server that implements the Docker Requirement Class supports the management of Docker image as execution units by implementing the Processes API Part2 deploy-replace-undeploy extension. -=== OGC Application Package +=== OGC Application Package as Docker ==== executionUnit property diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc index 92b35bb7..edc129f1 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc @@ -7,18 +7,18 @@ include::../requirements/requirements_class_cwl.adoc[] A server that implements the CWL Requirement Class SHALL support the use of CWL encoding when interacting with the Processes API Part 2 deploy-replace-undeploy extension endpoint. -=== OGC Application Package +=== OGC Application Package as CWL ==== executionUnit property -In case the OGC Application Package encoding is used, the following Requirement applies. +In case the <> encoding is used to provide a <> definition, the following Requirement applies. include::../requirements/cwl/REQ_execution-unit.adoc[] -Below is an example of a deploy body request using a CWL-encoded execution unit by reference. +Below is an example of a deploy body request using a <>-encoded execution unit by reference. -[[cwl_ogcapppkg_example1]] -[source%unnumbered] +[[cwl_ogcapppkg_example_reference]] +[source%unnumbered,json] ---- { "executionUnit": { @@ -28,28 +28,183 @@ Below is an example of a deploy body request using a CWL-encoded execution unit } ---- -Below is an example of a deploy body request using a CWL-encoded execution unit by value. The value is not included for readability and results from converting from the original CWL format (YAML) into JSON. +Below is an example of a deploy body request using a <>-encoded execution unit by value. +The <> value is not included entirely for readability. It is to be noted that the JSON object is directly +included in the same JSON structure as the execution unit parameter. +Therefore, the <> additional encoding (i.e.: JSON) does not need to be explicitly indicated in this case +because it can be inferred from the body structure itself. -[[cwl_ogcapppkg_example2]] -[source%unnumbered] +[[cwl_ogcapppkg_example_object]] +[source%unnumbered,json] ---- { "executionUnit": { - "value": { ... }, + "value": { "cwlVersion": "v1.2", "class": "CommandLineTool", ... }, + "mediaType": "application/cwl" + } +} +---- + +Below are other examples of deploy body request using a <>-encoded execution unit by value. +However, the <> content is included as an embedded string within the execution unit parameter. +In these cases, the <> additional encoding (i.e.: JSON or YAML) needs to be provided to disambiguate the content structure. + +[[cwl_ogcapppkg_example_string_json]] +[source%unnumbered,json] +---- +{ + "executionUnit": { + "value": "{ \"cwlVersion\": \"v1.2\", \"class\": \"CommandLineTool\", ... }", "mediaType": "application/cwl+json" } } ---- +[[cwl_ogcapppkg_example_string_yaml]] +[source%unnumbered,json] +---- +{ + "executionUnit": { + "value": "cwlVersion: 'v1.2'\nclass: CommandLineTool\n...", + "mediaType": "application/cwl+yaml" + } +} +---- + === Deploy ==== CWL body +In case a <> document is provided directly as body content of the request, the following Requirement applies. + include::../requirements/cwl/deploy/REQ_body.adoc[] +==== Multipart CWL body + +include::../recommendations/cwl/deploy/REC_body-cwl-multipart.adoc[] + +The following multipart example illustrates one request payload with a root workflow selected by the `start` parameter, +with supporting documents referenced by `filename`, `cid:` URI and remote URL combinations. The full contents of the +individual <> documents are not included for simplification. Note that the <> YAML representation +are employed to provide a concise example, but other <> media-types are permitted in any desired combination. + +In the example, the `Content-ID` headers and embedded `id` fields of respective parts are provided to illustrate the +expected interpretation of equivalent definitions, but some might be omitted as described in the recommendation text. + +The last <> part illustrates how its corresponding definition can be omitted because of the +provided `Content-Location` header. However, each part (including the ones providing the content directly), +could also include the `Content-Location` header for complementary identification of their origin if desired. + +The last process description part illustrates how additional metadata can be included in the multipart body +to refine the definition of the process being deployed, irrespective of its <> encoding. + +[[cwl_deploy_multipart_generic_example]] +[source%unnumbered,http] +---- +POST /processes HTTP/1.1 +Host: example.org +Content-Type: multipart/related; type="application/cwl+yaml"; start=""; boundary="===CWL-BUNDLE===" +Content-ID: + +--===CWL-BUNDLE=== +Content-Type: application/cwl+yaml +Content-ID: +Content-Disposition: attachment; filename="workflows/main.cwl" + +cwlVersion: v1.2 +class: Workflow +id: workflow-main +steps: + by_filename: + run: "tools/tool-1.cwl" + ... # rest of the definition + by_cid_host: + run: "cid:tool-2@example.org" + ... # rest of the definition + by_cid_uuid: + run: "cid:urn:uuid:550e8400-e29b-41d4-a716-446655440002" + ... # rest of the definition + by_remote_url: + run: "https://example.org/cwl/tools/tool-4.cwl" + ... # rest of the definition + +--===CWL-BUNDLE=== +Content-Type: application/cwl+yaml +Content-Disposition: attachment; filename="tools/tool-1.cwl" +Content-ID: + +cwlVersion: v1.2 +class: CommandLineTool +id: tool-1 +... # rest of the definition + +--===CWL-BUNDLE=== +Content-Type: application/cwl+yaml +Content-ID: +Content-Disposition: attachment; filename="tools/tool-2.cwl" + +cwlVersion: v1.2 +class: CommandLineTool +id: tool-2 +... # rest of the definition + +--===CWL-BUNDLE=== +Content-Type: application/cwl+yaml +Content-ID: +Content-Disposition: attachment; filename="tools/tool-3.cwl" + +cwlVersion: v1.2 +class: CommandLineTool +id: tool-3 +... # rest of the definition + +--===CWL-BUNDLE=== +Content-Type: application/cwl+yaml +Content-Location: https://example.org/cwl/tools/tool-4.cwl +Content-Disposition: attachment; filename="tools/tool-4.cwl" + +--===CWL-BUNDLE=== +Content-Type: application/json +Content-Profile: + +... # additional metadata for the process being deployed +--===CWL-BUNDLE===-- +---- + +The following partial example illustrates how the main <> part can be represented by the `#main` identifier +in accordance to the <> +representation, instead of using the multipart `start` parameter. In this case, the `Content-ID` header of the entire +request (i.e.: ``) indicates that the `{processID}` should be `workflow-main`, while the +`Content-ID` within the part (i.e.: `<#main@example.com>`) indicates that this part is the main <> document. +The rest of the definition is identical to the previous example. + +[[cwl_deploy_multipart_main_ref_example]] +[source%unnumbered,http] +---- +POST /processes HTTP/1.1 +Host: example.org +Content-Type: multipart/related; type="application/cwl+yaml"; boundary="===CWL-BUNDLE===" +Content-ID: + +--===CWL-BUNDLE=== +Content-Type: application/cwl+yaml +Content-ID: <#main@example.org> +Content-Disposition: attachment; filename="workflows/main.cwl" + +cwlVersion: v1.2 +class: Workflow +id: workflow-main +... # rest of the definition + +--===CWL-BUNDLE=== +... # other parts are identical to the previous example +--===CWL-BUNDLE===-- +---- + + ==== w parameter -When encoded in CWL, processes are identified as instances of the workflow class. +When encoded in <>, processes are identified as instances of the workflow class. include::../requirements/cwl/deploy/REQ_w-param.adoc[] @@ -61,10 +216,18 @@ include::../requirements/cwl/deploy/REQ_exception-workflow-not-found.adoc[] ==== CWL body +In case a <> document is provided directly as body content of the request, the following Requirement applies. + include::../requirements/cwl/replace/REQ_body.adoc[] +==== Multipart CWL body + +include::../recommendations/cwl/replace/REC_body-cwl-multipart.adoc[] + === Formal description ==== CWL content -include::../requirements/cwl/package/REQ_response-body.adoc[] \ No newline at end of file +include::../requirements/cwl/package/REQ_response-body.adoc[] + +include::../recommendations/deploy-replace-undeploy/package/REC_response-cwl.adoc[]