From 717321ae999884fb6c74414ad58e840ca84b3547 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 16:09:10 +0200 Subject: [PATCH 01/29] Boostrap part 4 (with wrong document number) --- extensions/job_management/.DS_Store | Bin 0 -> 8196 bytes extensions/job_management/README.md | 12 + .../job_management/examples/json/README.md | 1 + .../job_management/examples/xml/README.md | 1 + .../job_management/standard/20-044.adoc | 58 + .../standard/20-044.presentation.xml | 2154 +++++++++++++++++ extensions/job_management/standard/20-044.xml | 1087 +++++++++ .../job_management/standard/20-044.xml.abort | 1509 ++++++++++++ extensions/job_management/standard/README.md | 1 + .../standard/abstract_tests/ATS_class_jm.adoc | 14 + .../standard/abstract_tests/README.md | 27 + .../standard/abstract_tests/cc/TEST001.adoc | 15 + .../abstract_tests/jm/create/ATS_post-op.adoc | 19 + .../job_management/standard/figures/README.md | 5 + .../job_management/standard/images/README.md | 9 + .../standard/recommendations/README.md | 2 + .../PER_additional-status-codes.adoc | 7 + .../job-management/create/PER_body.adoc | 7 + .../create/REC_body-ogcapi-processes.adoc | 8 + .../create/REC_body-openeo.adoc | 8 + .../definition/REC_response-cwl.adoc | 9 + .../definition/REC_response-ogcapppkg.adoc | 8 + .../job-management/update/PER_body.adoc | 7 + .../job-management/update/REC_body-cwl.adoc | 9 + .../update/REC_body-ogcapi-processes.adoc | 9 + .../update/REC_body-openeo.adoc | 9 + .../job-management/create/REQ_body.adoc | 7 + .../create/REQ_content-type.adoc | 7 + .../job-management/create/REQ_post-op.adoc | 7 + .../create/REQ_response-body.adoc | 8 + .../create/REQ_response-jobid.adoc | 7 + .../create/REQ_response-success.adoc | 8 + .../create/REQ_unsupported-media-type.adoc | 11 + .../job-management/definition/REQ_get-op.adoc | 9 + .../definition/REQ_response-body.adoc | 7 + .../definition/REQ_response-success.adoc | 7 + .../job-management/start/REQ_response.adoc | 8 + .../job-management/start/REQ_start-op.adoc | 8 + .../job-management/update/REQ_body.adoc | 7 + .../update/REQ_content-type.adoc | 7 + .../job-management/update/REQ_put-op.adoc | 8 + .../job-management/update/REQ_response.adoc | 8 + .../ogcapi-processes/REQ_body.adoc | 7 + .../REQ_process-description.adoc | 7 + .../ogcapi-processes/REQ_profile-docker.adoc | 7 + .../ogcapi-processes/REQ_schema.adoc | 7 + .../ogcapi-processes/create/REQ_body.adoc | 8 + .../definition/REQ_response-body.adoc | 7 + .../ogcapi-processes/update/REQ_body.adoc | 7 + .../requirements/openeo/REQ_body.adoc | 7 + .../openeo/REQ_process-description.adoc | 7 + .../openeo/REQ_profile-docker.adoc | 7 + .../requirements/openeo/REQ_schema.adoc | 7 + .../requirements/openeo/create/REQ_body.adoc | 7 + .../openeo/definition/REQ_response-body.adoc | 7 + .../requirements/openeo/update/REQ_body.adoc | 7 + .../provenance/inputs/REQ_get-op.adoc | 8 + .../provenance/inputs/REQ_response.adoc | 8 + .../provenance/outputs/REQ_get-op.adoc | 8 + .../provenance/outputs/REQ_response.adoc | 8 + .../provenance/run/REQ_get-op.adoc | 8 + .../requirements_class_job-management.adoc | 10 + .../requirements_class_ogcapi-processes.adoc | 10 + .../requirements_class_openeo.adoc | 10 + .../requirements_class_provenance.adoc | 9 + .../requirements_class_quotation.adoc | 11 + .../standard/sections/annex_ats.adoc | 15 + .../standard/sections/annex_bibliography.adoc | 29 + .../standard/sections/annex_history.adoc | 8 + .../sections/clause_0_front_material.adoc | 26 + .../sections/clause_10_provenance.adoc | 43 + .../standard/sections/clause_11_oas.adoc | 5 + .../sections/clause_12_media_types.adoc | 13 + .../clause_13_security_considerations.adoc | 119 + .../standard/sections/clause_1_scope.adoc | 13 + .../sections/clause_2_conformance.adoc | 29 + .../sections/clause_3_references.adoc | 13 + .../clause_4_terms_and_definitions.adoc | 25 + .../sections/clause_5_conventions.adoc | 4 + .../sections/clause_6_job_management.adoc | 248 ++ .../sections/clause_7_ogcapi-processes.adoc | 33 + .../standard/sections/clause_8_openeo.adoc | 40 + .../standard/sections/clause_9_quotation.adoc | 8 + .../job_management/standard/standard.css | 2134 ++++++++++++++++ extensions/job_management/xml/README.md | 1 + .../processes-job-management/inputs.yaml | 3 + .../openeo-process-graph.yaml | 10 + .../processes-job-management/outputs.yaml | 3 + .../processes-job-management/statusCode.yaml | 9 + 89 files changed, 8139 insertions(+) create mode 100644 extensions/job_management/.DS_Store create mode 100644 extensions/job_management/README.md create mode 100644 extensions/job_management/examples/json/README.md create mode 100644 extensions/job_management/examples/xml/README.md create mode 100644 extensions/job_management/standard/20-044.adoc create mode 100644 extensions/job_management/standard/20-044.presentation.xml create mode 100644 extensions/job_management/standard/20-044.xml create mode 100644 extensions/job_management/standard/20-044.xml.abort create mode 100644 extensions/job_management/standard/README.md create mode 100644 extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc create mode 100644 extensions/job_management/standard/abstract_tests/README.md create mode 100644 extensions/job_management/standard/abstract_tests/cc/TEST001.adoc create mode 100644 extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc create mode 100644 extensions/job_management/standard/figures/README.md create mode 100644 extensions/job_management/standard/images/README.md create mode 100644 extensions/job_management/standard/recommendations/README.md create mode 100644 extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/update/REQ_put-op.adoc create mode 100644 extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc create mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc create mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc create mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc create mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc create mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/openeo/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc create mode 100644 extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc create mode 100644 extensions/job_management/standard/requirements/openeo/REQ_schema.adoc create mode 100644 extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc create mode 100644 extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc create mode 100644 extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc create mode 100644 extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc create mode 100644 extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc create mode 100644 extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc create mode 100644 extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc create mode 100644 extensions/job_management/standard/requirements/requirements_class_job-management.adoc create mode 100644 extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc create mode 100644 extensions/job_management/standard/requirements/requirements_class_openeo.adoc create mode 100644 extensions/job_management/standard/requirements/requirements_class_provenance.adoc create mode 100644 extensions/job_management/standard/requirements/requirements_class_quotation.adoc create mode 100644 extensions/job_management/standard/sections/annex_ats.adoc create mode 100644 extensions/job_management/standard/sections/annex_bibliography.adoc create mode 100644 extensions/job_management/standard/sections/annex_history.adoc create mode 100644 extensions/job_management/standard/sections/clause_0_front_material.adoc create mode 100644 extensions/job_management/standard/sections/clause_10_provenance.adoc create mode 100644 extensions/job_management/standard/sections/clause_11_oas.adoc create mode 100644 extensions/job_management/standard/sections/clause_12_media_types.adoc create mode 100644 extensions/job_management/standard/sections/clause_13_security_considerations.adoc create mode 100644 extensions/job_management/standard/sections/clause_1_scope.adoc create mode 100644 extensions/job_management/standard/sections/clause_2_conformance.adoc create mode 100644 extensions/job_management/standard/sections/clause_3_references.adoc create mode 100644 extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc create mode 100644 extensions/job_management/standard/sections/clause_5_conventions.adoc create mode 100644 extensions/job_management/standard/sections/clause_6_job_management.adoc create mode 100644 extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc create mode 100644 extensions/job_management/standard/sections/clause_8_openeo.adoc create mode 100644 extensions/job_management/standard/sections/clause_9_quotation.adoc create mode 100644 extensions/job_management/standard/standard.css create mode 100644 extensions/job_management/xml/README.md create mode 100644 openapi/schemas/processes-job-management/inputs.yaml create mode 100644 openapi/schemas/processes-job-management/openeo-process-graph.yaml create mode 100644 openapi/schemas/processes-job-management/outputs.yaml create mode 100644 openapi/schemas/processes-job-management/statusCode.yaml diff --git a/extensions/job_management/.DS_Store b/extensions/job_management/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..af55a34c49d9869bc5141e4ae331815e6a78c28e GIT binary patch literal 8196 zcmeHMU2GIp6u#fIz|54|DYj5{0&HjmEL&-j7AY9E?H2hFLAIr(fa~ne028J&WoLF5 zB*aGJivdhD#wYRrQ4(YH0VTqd#5YYrRgB6*XulVCLX2%0D z0x<$H0x<$H0x<&j0s{2S=1rdCyDzM9A0rSWa9<+8-w#Q;xJ*ZKLdfvdL0wn^kmMym z*yx_>fY2uy$#f(qgbZEjnWB0?!l20d@j^u=p!kt05Gej#Rs!$NFPJYR7 zIzw8>xQ`Kt5txYpPam22ETGEWy|aGLJ6@h_pXJ9L+YdTAzJpX#J8%91d4XIfAI={0 zD%rpYN`9YFJjk^{&vWwCdn3Q!wkkQTso!%0!*;D==wO=`O*u4dyQWv^^GdGihrU^1 zkQG_UY5M8Y?VVj+kEW9Co4U@VlBYX6HguZe6_ezwpYzuYfEt4UNtyIu`VQS0>KkppT@TU4g~?->tl&-M3PMW19&Yw#(~9R<(b zTeP@+xZpXZG1t#&jRnIglpG_ldL1WgKWF(Pfps$AccZ>n4En=~BR2W+v7Dxrd~2UY z4tCkfkelB$ZSznrE^J=5a@E?7uAZ%#9lM{Ntbd?EYh0wNqXd>4*hg%uI8?FC;Mf7f zFIcW=yGMu1wr}ShYtS{utVU!MWwL(pl9r_jU7u^}NGWfhDA~a&tyPx8HI}c?)k7xj zX}4$cRZQ&@nVv(dx319jgWS?zw5T^Dht+Fzb + + +OGC API - Processes - Part 4: Job Management +http://www.opengis.net/doc/IS/ogcapi-processes-4/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd +Geolabs + +Terradue Srl. + +Computer Research Institute of Montréal (CRIM). + +Gérald Fenoy + +Open Geospatial Consortium +OGC1.0en

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

+ +

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

+ +

The OGC API - Processes - Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [OGC 18-062r2] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard.

+ +

The OGC API - Processes - Part 3: Workflows draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [OGC 18-062r2] with the ability to …​

+ +

The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [OGC 18-062r2] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

+ +CAUTION

This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion.

+draftDraft2019 +Open Geospatial Consortium +OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementationScopeSymbols and abbreviated termsAbbreviated termsSymbolsContentsIntroductionPrefaceAbstractAcknowledgementsTerms and definitionsTerms, definitions, symbols and abbreviated termsTerms, definitions and symbolsTerms, definitions and abbreviated termsNormative referencesBibliographyPrefaceSectionClauseAnnexAppendixcontinued

No terms and definitions are listed in this document.

+

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

+

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

+

For the purposes of this document, the following additional terms and definitions apply.

+The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.There are no normative references in this document.

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

+

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

+

For the purposes of this document, the terms and definitions given in % additionally apply.

+

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

+

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

+

For the purposes of this document, the terms and definitions given in % and the following additionally apply.

+[NO INFORMATION AVAILABLE](%)%1 and %2%1, and %2%1 or %2%1, or %2%1 and %2%1 or %2%1 from %2%1 to %2%1, %2%1 %2spellout-ordinaldigits-ordinalNOTENoteNote % to entryListDefinition ListFigureDiagramFormulaFormulaTableRequirementRecommendationPermissionBox(NO ID)Recommendation testRequirement testPermission testRecommendations classRequirements classPermissions classAbstract testConformance classKeyExampleExamplewherewhereWhole of textdraftinformativenormativemodifiedadaptedDEPRECATEDSOURCEandAll Parts{{ var1 | ordinal_word: '', '' }} editioneditionversionList of FiguresList of TablesList of RecommendationsJanuaryFebruaryMarchAprilMayJuneJulyAugustSeptemberOctoberNovemberDecemberObligationDangerWarningCautionImportantSafety PrecautionsEditorial NoteSectionClausePartParagraphChapterPageTableAnnexFigureExampleNoteFormulamfncommonsgdualplpreppartadjadvnounverbdeprecatessupersedesnarrowerbroaderequivalentcomparecontrastseesee alsoClauseClausesAnnexAnnexesAppendixAppendixesNoteNotesNote % to entryNotes % to entryListListsFigureFiguresFormulaFormulasTableTablesRequirementRequirementsRecommendationRecommendationsPermissionPermissionsExampleExamplesPartPartsSectionSectionsParagraphParagraphsChapterChaptersPagePagesALTERNATIVESubmittersContributorsRevision historyListingTable of FiguresNo security considerations have been made for this document.Submission DateApproval DatePublication DateAuthorEditorContributorDraftWork Item DraftCandidate SWG DraftCandidate OAB Review DraftCandidate Public RFC DraftCandidate TC Vote DraftApprovedPublishedDeprecatedRescindedRetiredenLatnTable
ats_druhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
_99e940ea-ac12-4895-8c4c-7ab0fba8b43d/conf/dru/deploy/post-op
ats_dru_deploy_post-op/conf/jm/create/post-op
TOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 + +OGC API - Processes - Part 4: Job Management +http://www.opengis.net/doc/IS/ogcapi-processes-4/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd +Geolabs + +Terradue Srl. + +Computer Research Institute of Montréal (CRIM). + +Gérald Fenoy + +Open Geospatial Consortium +OGC1.0enLatnOGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. + +The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard. + +The OGC API - Processes - Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard. + +The OGC API - Processes - Part 3: Workflows draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to …​ + +The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable. + +This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion. +draft2019 +Open Geospatial Consortium +OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementationats_druhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management_99e940ea-ac12-4895-8c4c-7ab0fba8b43d/conf/dru/deploy/post-opats_dru_deploy_post-op/conf/jm/create/post-opTOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 + + + +Copyright notice +Copyright © 2019 Open Geospatial Consortium To obtain additional rights of use, visit + + + +Note +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. + +Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation. + + + + + + +License Agreement +Use of this document is subject to the license agreement at + + + + + + +Notice for Drafts +This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard. + +Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation. + + + + + + +Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site: + + +AbstractOGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. + +The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard. + +The OGC API — Processes — Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard. + +The OGC API — Processes — Part 3: Workflows draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to …​ + +The OGC API — Processes — Part 4: Job Management draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable. + +This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion. + +Security Considerations +See OGC API — Processes — Part 1: Core, Clause 10.4. + +Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations. + +Users making modifications to process resources need to: + +Be authenticated, + +Have “modification privileges” on the processes offered through the API, + +Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints. + + + +The API definition, as defined in Clause 7.3 from , must reflect this in the resource paths and their available methods. + +Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance: + +The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation). + +A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation. + + +Example OpenAPI definition with security requirements +The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user. + +{ + "openapi" : "3.0.3", + "info" : { + "title" : "My API", + "description" : "This API ...", + "version" : "1.0.0" + }, + "servers" : [ { + "url" : "https://example.com/api/v1" + } ], + "security" : [ { + "JWT" : [ ], + "api_key": [ ] + } ], + "paths" : { }, + "components" : { + "securitySchemes": { + "JWT" : { + "type" : "http", + "scheme" : "bearer", + "bearerFormat" : "JWT" + }, + "api_key" : { + "type": "apiKey", + "name": "X-API-Key", + "in": "header" + } + } + } +} + + + +If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error. + +In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided. + +Unauthorized requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | ----------------------------------------------------------->| + | | + | HTTP/1.1 401 Unauthorized | + | Date: Mon, 23 May 2022 11:18:45 GMT | + | WWW-Authenticate: Bearer realm="my-realm" | + | WWW-Authenticate: ApiKey header="X-API-Key" | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 86 | + | | + | { | + | "status": 401, | + | "title": "Unauthorized", | + | "detail": "HTTP 401 Unauthorized" | + | } | + | <-----------------------------------------------------------| + + +HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023) + + +If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”). + +Forbidden requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | Host: example.com | + | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | + |------------------------------------------------------------------>| + | | + | HTTP/1.1 403 Forbidden | + | Date: Mon, 23 May 2022 11:18:55 GMT | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 80 | + | | + | { | + | "status" : 403, | + | "title" : "Forbidden", | + | "detail" : "HTTP 403 Forbidden" | + | } | + |<------------------------------------------------------------------| + + +However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation. + +Submitters +All questions regarding this submission should be directed to the editors or the submitters: + +Name +Affiliation + +Gérald Fenoy (editor) +GeoLabs + + + + + +Scope +The OGC API — Processes — Part 4 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [] and defines the behavior of a server that supports the ability to create jobs without implying the process execution starts right away. + +Specifically, the Processes Part 4 Standard specifies: + +How to manage job. + +How to handle provenenance information associated with a job. + + + + + +Conformance +The OGC API — Processes — Part 4 Standard defines the following requirements classes. + +The main requirements class is: + +Job Management. + + + +This class specifies requirements that any Web API implementing Processes Part 4 must conform with. + +The Job Management class does mandate a specific encoding and format for the job definition. However, the Part 4 extension defines the following conformance class: + +OpenEO graph + + + +The OpenEO grap class defines that jobs can be created from an OpenEO graph. + +The provenance information associated with a job is not mandated to be supported by the server. A dedicated requirements class Provenance is defined for this feature. + +The standardization target for all Conformance class defined in this Standard is “Web API”. + +Conformance with this Standard shall be checked using all the relevant tests specified in of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site. + + + + + +Terms, definitions and abbreviated termsThis document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2. +This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec. +For the purposes of this document, the following additional terms and definitions apply. + + +Terms and definitions + +Execution unit + + +A component containing a process that an implementation of the Processes API Part 1 can run. + + + +Deploy + + +Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard. + + + +Replace + + +Replace refers to upgrading a deployed process from a Processes API implementation. + + + +Undeploy + + +Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process. + + + + +Abbreviated terms +CWLCommon Workflow Language + +DRUDeploy, Replace, Undeploy + + + + +Conventions and background +See , Clause 5. + + + +Requirements Class “Job Management” + +Overview + Web APIOGC API — Processes — Part 1: Core, Conformance Class ‘core’RFC 2616 (HTTP/1.1)label + + +A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs. + +The HTTP POST method is used to create new jobs. + +The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint. + +Finally, the HTTP POST method is used to start a job. + +Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standard does mandate that a specific jobs schema be used. However, this extension defines the following conformance classe: + +OpenEO Process Graph, that enables support for OpenEO-encoded jobs definition. + + + + +HTTP status codes +Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code. + +The Status Codes listed in are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations. + + +Typical HTTP status codes +Status code +Description + +200 +A successful request. +201 +The server has successfully completed the operation and a new resource has been created. +202 +The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. +204 +A successful request with no additional content to send in the response. +400 +The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value. +401 +The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource. +403 +The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource. +404 +The requested resource does not exist on the server. For example, a path parameter had an incorrect value. +405 +The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests. +406 +Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource. +412 +The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server. +413 +The server is refusing to process the request because the request content is larger than the server is willing or able to process. +415 +The server is refusing to service the request because the content is in a format not supported by this method on the target resource. +422 +The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing. +500 +An internal error occurred in the server. + +Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”. + + + + +More specific guidance is provided for each resource, where applicable. + + label/per/core/additional-status-codesServers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in . + + + +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. + + + +Cross-origin requests +See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS). + + + + +Creating a new job + +Sequence diagram +The following diagram illustrates the sequence diagram for deploying a new process to the API: + +Client Server + | | + | POST /jobs HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 201 Created | + | Location: /jobs/{jobId} | + |<------------------------------------------------------------| + + + + +Operation + label/req/job-management/create/post-opThe server SHALL support the HTTP POST operation at the path /jobs. + + + + + +Request body + +Overview + label/req/job-management/create/bodyThe body of the POST request SHALL be in JSON format. + + + + label/per/job-management/create/bodyA server MAY support any encoding in the body of a HTTP POST operation. + + + + label/req/job-management/create/content-typeThe Content-Type header SHALL be used to declare the media type of the request. + + + +See section 3.1.1.5 of RFC 7231 for details. + + + +OGC API — Processes — Workflow Execute Request body + label/rec/job-management/create/body-ogcapi-processesIf the job can be encoded as an OGC API — Processes — Workflow Execute Request, implementation SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding. + + + + + +OpenEO Process Graph body + label/rec/job-management/create/body-openeoIf the job can be encoded as an OpenEO graph, implementation SHOULD consider supporting the OpenEO graph encoding. + + + + + + +Response + label/req/job-management/create/response-jobidIf the operation completes, the server SHALL generate a job identifier (i.e. {jobId}) for the created job. + + + + label/req/job-management/create/response-successA successful execution of the operation SHALL be reported as a response with a HTTP status code 201. +A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /jobs/{jobId}). + + + + label/req/job-management/create/response-bodyThe response SHALL include a body that contains a status information of the created job conforms to the statusInfo.yaml schema. +The response SHALL contains a pending status code and the jobId property that contains the job identifier. + + + + + +Exceptions +See for general guidance. + +If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from . + + + + +Updating an existing job + +Sequence diagram +The following diagram illustrates the sequence diagram for updating a +previously created job. The identifier of the job does not change.The new job definition replaces the old job definition. Version control is not discussed in this Standard. + + + + +Client Server + | | + | PUT /jobs/{jobId} HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +Operation + label/req/job-management/update/put-opFor every created jobs (path ‘/jobs/{jobId}’), the server SHALL support the HTTP PUT operation. +The parameter ‘jobId’ is each ‘jobID’ property in the jobs list response (JSONPath: $.jobs[*].jobID). + + + + + +Request body + + + +Overview + label/req/job-management/update/body*The body of a PUT request SHALL be in JSON format. + + + + label/per/job-management/update/bodyA server MAY support any encoding in the body of a HTTP PUT operation. + + + + label/req/job-management/update/content-typeAs per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes. + + + + +OGC API — Processes — Workflow Execute Request body + label/rec/job-management/update/body-ogcapi-processesIf a job can be created from an rc_ogcapi-processes,OGC API — Processes — Workflow Execute Request>>, implementations SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding. + + + + + +OpenEO Process Graph body + label/rec/job-management/update/body-openeoIf a job can be created from an OpenEO graph, implementations SHOULD consider supporting the OpenEO graph encoding. + + + + + + +Response + label/req/job-management/update/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204. +If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202. + + + +The status code depends on the server. If the server has replaced the job, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content). + +If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client. + + + +Exceptions +See for general guidance. + +If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from . + +If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from . + + + + +Staring a job + +Sequence diagram +The following diagram illustrates the sequence diagram for starting the execution of a previously created jobs. + +Client Server + | | + | POST /jobs/{jobId} HTTP/1.1 | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +Operation + label/req/job-management/start/start-opFor every created jobs (path: /jobs/{jobId}/results), the server SHALL support the HTTP POST operation. +The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). + + + + + +Response + label/req/job-management/start/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’. +A response SHALL be a document that conforms to statusInfo.yaml. + + + + + +Exceptions +See HTTP status codes for general guidance. + +If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from . + + + + +Job definition +For every job, it is possible to retrieve its original definition. It corresponds to the request’s body used to create or update the jobs. + + +Operation + label/req/deploy-replace-undeploy/package/get-opFor every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package. +The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id). + + + + + +Response + +Overview + label/req/deploy-replace-undeploy/package/response-successA successful access to the resource SHALL be reported as a response with a HTTP status code 200. + + + + label/req/deploy-replace-undeploy/package/response-bodyA response with HTTP status code 200 SHALL include a body that contains the request body used to create or update the job. + + + + + + +Exceptions +See HTTP status codes for general guidance. + +If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from . + + + + + +Requirements Class “OGC API — Process — Workflow Execute Request” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel + + +This requirements class defines that the OGC API — Process — Workflow Execute Request is supported as an encoding for job definitions. + + + +OGC API — Processes + +Overview + label/req/ogcapi-processes/schemaAn OGC API - Processes document SHALL be based upon the JSON schema execute-workflow.yaml. + + + + + + +Create + +OGC API — Processes body + label/req/ogcapi-processes/create/bodyThe body of the POST request SHALL be based upon the OpenAPI 3.0 schema execute-workflows.yaml +The media type application/json SHALL be used to indicate that request body contains a processes description encoded as an OGC API — Processes. + + + + + + +Update + +OGC API — Processes body + label/req/ogcapi-processes/update/bodyThe media type application/ogcapi-processes+json SHALL be used to indicate that request body contains a job encoded as an OGC API — Processes. + + + + + + +Job definition + +OGC API — Processes content + label/req/ogcapi-processes/definition/response-bodyA response with HTTP status code 200 SHALL include a body that contains the OGC API — Processes to use to deploy the process. + + + + + + + +Requirements Class “OpenEO Process Graph” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel + + +This requirements class defines that the server supports the OpenEO Process Graph as an encoding for job definitions. + + + +OpenEO Process Graph + +Overview + label/req/openeo/schemaAn OpenEO Process Graph document SHALL be based upon the JSON schema . + + + + +Schema for OpenEO Process Graph +type: object +additionalProperties: + type: object + required: + - process_id + - arguments + properties: + process_id: + type: string + arguments: {} + + + + + +Create + +OpenEO body + label/req/openeo/create/bodyThe media type application/openeo+json SHALL be used to indicate that request body contains a processes description encoded as an OpenEO Process Graph. + + + + + + +Update + +OpenEO body + label/req/openeo/update/bodyThe media type application/openeo+json SHALL be used to indicate that request body contains a job encoded as an OpenEO Process Graph. + + + + + + +Job definition + +OpenEO content + label/req/openeo/definition/response-bodyA response with HTTP status code 200 SHALL include a body that contains the OpenEO Process Graph to use to deploy the process. + + + + + + + +Requirements Class “Quotation” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeolabel + + + + + +Requirements Class “Provenance” + +Overview +This requirements class defines how to allow client application accessing the provenance of a job run. + + Web APIOGC API — Processes — Part 1: Corelabel + + + + +Additional endpoints + +Inputs +The server MUST provide an endpoint to retrieve the inputs of a job run. + + +Operation + label/req/provenance/inputs/get-opFor every created jobs (path: /jobs/{jobId}/inputs), the server SHALL support the HTTP GET operation. +The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). + + + + + +Response + label/req/provenance/inputs/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’. +The response SHALL contains a JSON document that conforms to the schema inputs.yaml. + + + + + + +Outputs +The server MUST provide an endpoint to retrieve the outputs of a job run. + + +Operation + label/req/provenance/outputs/get-opFor every created jobs (path: /jobs/{jobId}/outputs), the server SHALL support the HTTP GET operation. +The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). + + + + + +Response + label/req/provenance/outputs/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’. +The response SHALL contains a JSON document that conforms to the schema outputs.yaml. + + + + + + +Run +The server MUST provide an endpoint to retrieve the run of a job. + + +Operation + label/req/provenance/run/get-opFor every created jobs (path: /jobs/{jobId}/run), the server SHALL support the HTTP GET operation. +The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). + + + + + + + + +OpenAPI 3.0 +See , Clause 9. + + + +Media Types +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 + + + +Additional CWL media types that would typically be used in a server that supports CWL are: + +application/cwl + + + + + + + + + + + + +Abstract Test Suite + +Introduction +OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested. + +The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”. + + + +Conformance Class Deploy, Replace, Undeploy + +Job Managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementTarget TypeWeb API /conf/dru/deploy/post-op + + + + +Create operation + /conf/jm/create/post-optarget/req/job-management/create/post-opValidate that the server support HTTP POST operation at the path /jobs/ +Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/job-list” link on the landing page as well as for the {root}/jobs path. + +Issue an HTTP POST request for each path. + +Validate that the response header does not contain 405 Method not allowed + + + + + + + +Revision History +Date +Release +Editor +Primary clauses modified +Description + +2024-08-22 +None +Gérald Fenoy +all +Boostraping the document + + + +Normative referencesThe following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. + + 2024-08-29 + +OGC API + + +Processes + + +Part 1: Core + + +OGC API — Processes — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 + https://docs.ogc.org/is/18-062r2/18-062r2.html + OGC 18-062r2OGC 18-062r2 + + 2021-12-20 + + + + + + Benjamin Pross + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + +Open Geospatial Consortium + + + + 2 + en + Latn + The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. + +By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. + +The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. + +The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. + + +Pross, B.: OGC 18-062, OGC API — Processes — Part 2: Deploy, Replace, UndeployOGC 20-044OGC 20-04420-044 + + 2024-08-29 + +OGC API + + +Processes + + +Part 1: Core + + +OGC API — Processes — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 + https://docs.ogc.org/is/18-062r2/18-062r2.html + OGC 18-062r2OGC 18-062r2 + + 2021-12-20 + + + + + + Benjamin Pross + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + +Open Geospatial Consortium + + + + 2 + en + Latn + The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. + +By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. + +The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. + +The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. + + + + 2024-08-29 + +OGC API + + +Features + + +Part 1: Core + + +OGC API — Features — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0 + https://docs.ogc.org/is/17-069r3/17-069r3.html + OGC 17-069r3OGC 17-069r3 + + 2019-10-07 + + + + + + Clemens Portele + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + + Charles Heazel + + + + + + + +Open Geospatial Consortium + + + + 3 + en + Latn + OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. + +The OGC API family of standards is organized by resource type. This standard specifies the fundamental API building blocks for interacting with features. The spatial data community uses the term ‘feature’ for things in the real world that are of interest. + + + +Bibliography + OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: +. + OpenAPI Specification 3.0.2OpenAPI Specification 3.0.2 + 3.0.2 + + Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. + [2] + + OpenEO: OpenEO Developers API Reference / Process Graphs. + [3] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + : + + + + +sourcecode table td { padding: 5px; } +sourcecode table pre { margin: 0; } +sourcecode, sourcecode .w { + color: #444444; +} +sourcecode .cp { + color: #CC00A3; +} +sourcecode .cs { + color: #CC00A3; +} +sourcecode .c, sourcecode .ch, sourcecode .cd, sourcecode .cm, sourcecode .cpf, sourcecode .c1 { + color: #1E90FF; +} +sourcecode .kc { + color: #C34E00; +} +sourcecode .kd { + color: #0000FF; +} +sourcecode .kr { + color: #007575; +} +sourcecode .k, sourcecode .kn, sourcecode .kp, sourcecode .kt, sourcecode .kv { + color: #0000FF; +} +sourcecode .s, sourcecode .sb, sourcecode .sc, sourcecode .ld, sourcecode .sd, sourcecode .s2, sourcecode .se, sourcecode .sh, sourcecode .si, sourcecode .sx, sourcecode .sr, sourcecode .s1, sourcecode .ss { + color: #009C00; +} +sourcecode .sa { + color: #0000FF; +} +sourcecode .nb, sourcecode .bp { + color: #C34E00; +} +sourcecode .nt { + color: #0000FF; +} + + + + +Copyright notice +

Copyright © 2019 Open Geospatial Consortium
To obtain additional rights of use, visit

+ + + +Note +

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

+ +

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

+ + + + + + +License Agreement +

Use of this document is subject to the license agreement at

+ + + + + + +Notice for Drafts +

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

+ +

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

+ + + + + + +

Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site:

+ + +Contents +I.<tab/>Abstract

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

+ +

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

+ +

The OGC API — Processes — Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [OGC 18-062r2] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard.

+ +

The OGC API — Processes — Part 3: Workflows draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [OGC 18-062r2] with the ability to …​

+ +

The OGC API — Processes — Part 4: Job Management draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [OGC 18-062r2] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

+ +CAUTION

This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion.

+ +II.<tab/>Keywords +

The following are keywords to be used by search engines and document catalogues.

+

process, collection, instance, spatial, data, openapi, transactions, insert, update, delete, add, remove, deploy, undeploy, REST, PUT, POST, DELETE

 + +III.<tab/>Security Considerations +

See OGC API — Processes — Part 1: Core, Clause 10.4.

+ +

Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations.

+ +

Users making modifications to process resources need to:

+ +

  1. Be authenticated,

    +
    2. +

  2. Have “modification privileges” on the processes offered through the API,

    +
    3. +

  3. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints.

    +
    4. +
+ +

The API definition, as defined in Clause 7.3 from OGC 18-062r2, must reflect this in the resource paths and their available methods.

+ +

Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance:

+ +

The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation).

+ +

A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation.

+ + +Example — Example OpenAPI definition with security requirements +

The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user.

+ +{ + "openapi" : "3.0.3", + "info" : { + "title" : "My API", + "description" : "This API ...", + "version" : "1.0.0" + }, + "servers" : [ { + "url" : "https://example.com/api/v1" + } ], + "security" : [ { + "JWT" : [ ], + "api_key": [ ] + } ], + "paths" : { }, + "components" : { + "securitySchemes": { + "JWT" : { + "type" : "http", + "scheme" : "bearer", + "bearerFormat" : "JWT" + }, + "api_key" : { + "type": "apiKey", + "name": "X-API-Key", + "in": "header" + } + } + } +} + + + +

If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.

+ +

In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided.

+ +Listing 1 — Unauthorized requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | ----------------------------------------------------------->| + | | + | HTTP/1.1 401 Unauthorized | + | Date: Mon, 23 May 2022 11:18:45 GMT | + | WWW-Authenticate: Bearer realm="my-realm" | + | WWW-Authenticate: ApiKey header="X-API-Key" | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 86 | + | | + | { | + | "status": 401, | + | "title": "Unauthorized", | + | "detail": "HTTP 401 Unauthorized" | + | } | + | <-----------------------------------------------------------| + + +NOTE

HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023)

+ + +

If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”).

+ +Listing 2 — Forbidden requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | Host: example.com | + | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | + |------------------------------------------------------------------>| + | | + | HTTP/1.1 403 Forbidden | + | Date: Mon, 23 May 2022 11:18:55 GMT | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 80 | + | | + | { | + | "status" : 403, | + | "title" : "Forbidden", | + | "detail" : "HTTP 403 Forbidden" | + | } | + |<------------------------------------------------------------------| + + +

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

+ +IV.<tab/>Submitting Organizations +

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

+
  • Geolabs
    • +
  • Terradue Srl.
    • +
  • Computer Research Institute of Montréal (CRIM).
+ + +V.<tab/>Submitters +

All questions regarding this submission should be directed to the editors or the submitters:

+ + + + + + + +
NameAffiliation
Gérald Fenoy (editor)GeoLabs
+ + + +1.<tab/>Scope +

The OGC API — Processes — Part 4 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [OGC 18-062r2] and defines the behavior of a server that supports the ability to create jobs without implying the process execution starts right away.

+ +

Specifically, the Processes Part 4 Standard specifies:

+ +

  • How to manage job.

    +
    • +

  • How to handle provenenance information associated with a job.

    +
    • +
+ + + +2.<tab/>Conformance +

The OGC API — Processes — Part 4 Standard defines the following requirements classes.

+ +

The main requirements class is:

+ +

  • Job Management.

    +
    • +
+ +

This class specifies requirements that any Web API implementing Processes Part 4 must conform with.

+ +

The Job Management class does mandate a specific encoding and format for the job definition. However, the Part 4 extension defines the following conformance class:

+ +

  • OpenEO graph

    +
    • +
+ +

The OpenEO grap class defines that jobs can be created from an OpenEO graph.

+ +

The provenance information associated with a job is not mandated to be supported by the server. A dedicated requirements class Provenance is defined for this feature.

+ +

The standardization target for all Conformance class defined in this Standard is “Web API”.

+ +

Conformance with this Standard shall be checked using all the relevant tests specified in Annex A of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.

+ + + + + +4.<tab/>Terms, definitions and abbreviated terms

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

+

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

+

For the purposes of this document, the following additional terms and definitions apply.

+ + +4.1.<tab/>Terms and definitions +4.1.1.Execution unit +

A component containing a process that an implementation of the Processes API Part 1 can run.

 + + +4.1.2.Deploy +

Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard.

 + + +4.1.3.Replace +

Replace refers to upgrading a deployed process from a Processes API implementation.

 + + +4.1.4.Undeploy +

Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process.

 + + + + +4.2.<tab/>Abbreviated terms +
CWL

Common Workflow Language

+
+
DRU

Deploy, Replace, Undeploy

+
+ + + +5.<tab/>Conventions and background +

See OGC 18-062r2, Clause 5.

+ + + +6.<tab/>Requirements Class “Job Management” + +6.1.<tab/>Overview + +

Requirements class 1

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core, Conformance Class ‘core’
RFC 2616 (HTTP/1.1)
Label
+ +

A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs.

+ +

The HTTP POST method is used to create new jobs.

+ +

The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint.

+ +

Finally, the HTTP POST method is used to start a job.

+ +

Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standard does mandate that a specific jobs schema be used. However, this extension defines the following conformance classe:

+ +

  • OpenEO Process Graph, that enables support for OpenEO-encoded jobs definition.

    +
    • +
+ + +6.1.1.<tab/>HTTP status codes +

Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code.

+ +

The Status Codes listed in Table 1 are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in Table 1 are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations.

+ + +Table 1 — Typical HTTP status codes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +NOTE

Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”.

+
Status codeDescription
200A successful request.
201The server has successfully completed the operation and a new resource has been created.
202The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
204A successful request with no additional content to send in the response.
400The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.
401The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource.
404The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
405The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.
406Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource.
412The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server.
413The server is refusing to process the request because the request content is larger than the server is willing or able to process.
415The server is refusing to service the request because the content is in a format not supported by this method on the target resource.
422The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing.
500An internal error occurred in the server.
+ + + +

More specific guidance is provided for each resource, where applicable.

+ + +

Permission 1

Label/per/core/additional-status-codes
A

Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in Table 1.

+
+ +

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.

+ + + +6.1.2.<tab/>Cross-origin requests +

See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).

+ + + + +6.2.<tab/>Creating a new job + +6.2.1.<tab/>Sequence diagram +

The following diagram illustrates the sequence diagram for deploying a new process to the API:

+ +Listing 3Client Server + | | + | POST /jobs HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 201 Created | + | Location: /jobs/{jobId} | + |<------------------------------------------------------------| + + + + +6.2.2.<tab/>Operation + +

Requirement 1

Label/req/job-management/create/post-op
A

The server SHALL support the HTTP POST operation at the path /jobs.

+
+ + + +6.2.3.<tab/>Request body + +6.2.3.1.<tab/>Overview + +

Requirement 2

Label/req/job-management/create/body
A

The body of the POST request SHALL be in JSON format.

+
+ + +

Permission 2

Label/per/job-management/create/body
A

A server MAY support any encoding in the body of a HTTP POST operation.

+
+ + +

Requirement 3

Label/req/job-management/create/content-type
A

The Content-Type header SHALL be used to declare the media type of the request.

+
+ +

See section 3.1.1.5 of RFC 7231 for details.

+ + + +6.2.3.2.<tab/>OGC API — Processes — Workflow Execute Request body + +

Recommendation 1

Label/rec/job-management/create/body-ogcapi-processes
A

If the job can be encoded as an OGC API — Processes — Workflow Execute Request, implementation SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

+
+ + + +6.2.3.3.<tab/>OpenEO Process Graph body + +

Recommendation 2

Label/rec/job-management/create/body-openeo
A

If the job can be encoded as an OpenEO graph, implementation SHOULD consider supporting the OpenEO graph encoding.

+
+ + + + +6.2.4.<tab/>Response + +

Requirement 4

Label/req/job-management/create/response-jobid
A

If the operation completes, the server SHALL generate a job identifier (i.e. {jobId}) for the created job.

+
+ + +

Requirement 5

Label/req/job-management/create/response-success
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code 201.

+
B

A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /jobs/{jobId}).

+
+ + +

Requirement 6

Label/req/job-management/create/response-body
A

The response SHALL include a body that contains a status information of the created job conforms to the statusInfo.yaml schema.

+
B

The response SHALL contains a pending status code and the jobId property that contains the job identifier.

+
+ + + +6.2.5.<tab/>Exceptions +

See Clause 6.1.1 for general guidance.

+ +

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from OGC 20-044.

+ + + + +6.3.<tab/>Updating an existing job + +6.3.1.<tab/>Sequence diagram +

The following diagram illustrates the sequence diagram for updating a +previously created job. The identifier of the job does not change.NOTE

The new job definition replaces the old job definition. Version control is not discussed in this Standard.

+

+ + + +Listing 4Client Server + | | + | PUT /jobs/{jobId} HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +6.3.2.<tab/>Operation + +

Requirement 7

Label/req/job-management/update/put-op
A

For every created jobs (path ‘/jobs/{jobId}’), the server SHALL support the HTTP PUT operation.

+
B

The parameter ‘jobId’ is each ‘jobID’ property in the jobs list response (JSONPath: $.jobs[*].jobID).

+
+ + + +6.3.3.<tab/>Request body + + + +6.3.4.<tab/>Overview + +

Requirement 8

Label/req/job-management/update/body*
A

The body of a PUT request SHALL be in JSON format.

+
+ + +

Permission 3

Label/per/job-management/update/body
A

A server MAY support any encoding in the body of a HTTP PUT operation.

+
+ + +

Requirement 9

Label/req/job-management/update/content-type
A

As per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes.

+
+ + +6.3.4.1.<tab/>OGC API — Processes — Workflow Execute Request body + +

Recommendation 3

Label/rec/job-management/update/body-ogcapi-processes
A

If a job can be created from an rc_ogcapi-processes,OGC API — Processes — Workflow Execute Request>>, implementations SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

+
+ + + +6.3.4.2.<tab/>OpenEO Process Graph body + +

Recommendation 4

Label/rec/job-management/update/body-openeo
A

If a job can be created from an OpenEO graph, implementations SHOULD consider supporting the OpenEO graph encoding.

+
+ + + + +6.3.5.<tab/>Response + +

Requirement 10

Label/req/job-management/update/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204.

+
B

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

+
+ +

The status code depends on the server. If the server has replaced the job, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content).

+ +

If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client.

+ + + +6.3.6.<tab/>Exceptions +

See Clause 6.1.1 for general guidance.

+ +

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from OGC 20-044.

+ +

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from OGC 18-062r2.

+ + + + +6.4.<tab/>Staring a job + +6.4.1.<tab/>Sequence diagram +

The following diagram illustrates the sequence diagram for starting the execution of a previously created jobs.

+ +Listing 5Client Server + | | + | POST /jobs/{jobId} HTTP/1.1 | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +6.4.2.<tab/>Operation + +

Requirement 11

Label/req/job-management/start/start-op
A

For every created jobs (path: /jobs/{jobId}/results), the server SHALL support the HTTP POST operation.

+
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+
+ + + +6.4.3.<tab/>Response + +

Requirement 12

Label/req/job-management/start/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

+
B

A response SHALL be a document that conforms to statusInfo.yaml.

+
+ + + +6.4.4.<tab/>Exceptions +

See HTTP status codes for general guidance.

+ +

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from OGC 18-062r2.

+ + + + +6.5.<tab/>Job definition +

For every job, it is possible to retrieve its original definition. It corresponds to the request’s body used to create or update the jobs.

+ + +6.5.1.<tab/>Operation + +

Requirement 13

Label/req/deploy-replace-undeploy/package/get-op
A

For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package.

+
B

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

+
+ + + +6.5.2.<tab/>Response + +6.5.2.1.<tab/>Overview + +

Requirement 14

Label/req/deploy-replace-undeploy/package/response-success
A

A successful access to the resource SHALL be reported as a response with a HTTP status code 200.

+
+ + +

Requirement 15

Label/req/deploy-replace-undeploy/package/response-body
A

A response with HTTP status code 200 SHALL include a body that contains the request body used to create or update the job.

+
+ + + + +6.5.3.<tab/>Exceptions +

See HTTP status codes for general guidance.

+ +

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from OGC 18-062r2.

+ + + + + +7.<tab/>Requirements Class “OGC API — Process — Workflow Execute Request” + +7.1.<tab/>Overview + +

Requirements class 2

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-management
Label
+ +

This requirements class defines that the OGC API — Process — Workflow Execute Request is supported as an encoding for job definitions.

+ + + +7.2.<tab/>OGC API — Processes + +7.2.1.<tab/>Overview + +

Requirement 16

Label/req/ogcapi-processes/schema
A

An OGC API - Processes document SHALL be based upon the JSON schema execute-workflow.yaml.

+
+ + + + +7.3.<tab/>Create + +7.3.1.<tab/>OGC API — Processes body + +

Requirement 17

Label/req/ogcapi-processes/create/body
A

The body of the POST request SHALL be based upon the OpenAPI 3.0 schema execute-workflows.yaml

+
B

The media type application/json SHALL be used to indicate that request body contains a processes description encoded as an OGC API — Processes.

+
+ + + + +7.4.<tab/>Update + +7.4.1.<tab/>OGC API — Processes body + +

Requirement 18

Label/req/ogcapi-processes/update/body
A

The media type application/ogcapi-processes+json SHALL be used to indicate that request body contains a job encoded as an OGC API — Processes.

+
+ + + + +7.5.<tab/>Job definition + +7.5.1.<tab/>OGC API — Processes content + +

Requirement 19

Label/req/ogcapi-processes/definition/response-body
A

A response with HTTP status code 200 SHALL include a body that contains the OGC API — Processes to use to deploy the process.

+
+ + + + + +8.<tab/>Requirements Class “OpenEO Process Graph” + +8.1.<tab/>Overview + +

Requirements class 3

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-management
Label
+ +

This requirements class defines that the server supports the OpenEO Process Graph as an encoding for job definitions.

+ + + +8.2.<tab/>OpenEO Process Graph + +8.2.1.<tab/>Overview + +

Requirement 20

Label/req/openeo/schema
A

An OpenEO Process Graph document SHALL be based upon the JSON schema .

+
+ +Listing 6 — + Schema for OpenEO Process Graph + + +type: object +additionalProperties: + type: object + required: + - process_id + - arguments + properties: + process_id: + type: string + arguments: {} + + + + + +8.3.<tab/>Create + +8.3.1.<tab/>OpenEO body + +

Requirement 21

Label/req/openeo/create/body
A

The media type application/openeo+json SHALL be used to indicate that request body contains a processes description encoded as an OpenEO Process Graph.

+
+ + + + +8.4.<tab/>Update + +8.4.1.<tab/>OpenEO body + +

Requirement 22

Label/req/openeo/update/body
A

The media type application/openeo+json SHALL be used to indicate that request body contains a job encoded as an OpenEO Process Graph.

+
+ + + + +8.5.<tab/>Job definition + +8.5.1.<tab/>OpenEO content + +

Requirement 23

Label/req/openeo/definition/response-body
A

A response with HTTP status code 200 SHALL include a body that contains the OpenEO Process Graph to use to deploy the process.

+
+ + + + + +9.<tab/>Requirements Class “Quotation” + +9.1.<tab/>Overview + +

Requirements class 4

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-management
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeo
Label
+ + + + +10.<tab/>Requirements Class “Provenance” + +10.1.<tab/>Overview +

This requirements class defines how to allow client application accessing the provenance of a job run.

+ + +

Requirements class 5

Obligationrequirement
Target typeWeb API
PrerequisiteOGC API — Processes — Part 1: Core
Label
+ + + +10.2.<tab/>Additional endpoints + +10.2.1.<tab/>Inputs +

The server MUST provide an endpoint to retrieve the inputs of a job run.

+ + +10.2.1.1.<tab/>Operation + +

Requirement 24

Label/req/provenance/inputs/get-op
A

For every created jobs (path: /jobs/{jobId}/inputs), the server SHALL support the HTTP GET operation.

+
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+
+ + + +10.2.1.2.<tab/>Response + +

Requirement 25

Label/req/provenance/inputs/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

+
B

The response SHALL contains a JSON document that conforms to the schema inputs.yaml.

+
+ + + + +10.2.2.<tab/>Outputs +

The server MUST provide an endpoint to retrieve the outputs of a job run.

+ + +10.2.2.1.<tab/>Operation + +

Requirement 26

Label/req/provenance/outputs/get-op
A

For every created jobs (path: /jobs/{jobId}/outputs), the server SHALL support the HTTP GET operation.

+
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+
+ + + +10.2.2.2.<tab/>Response + +

Requirement 27

Label/req/provenance/outputs/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

+
B

The response SHALL contains a JSON document that conforms to the schema outputs.yaml.

+
+ + + + +10.2.3.<tab/>Run +

The server MUST provide an endpoint to retrieve the run of a job.

+ + +10.2.3.1.<tab/>Operation + +

Requirement 28

Label/req/provenance/run/get-op
A

For every created jobs (path: /jobs/{jobId}/run), the server SHALL support the HTTP GET operation.

+
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+
+ + + + + + +11.<tab/>OpenAPI 3.0 +

See OGC 18-062r2, Clause 9.

+ + + +12.<tab/>Media Types +

See OGC 18-062r2, Clause 13.

+ +

Additional JSON media types that would typically be used in a server that supports JSON are:

+ +

  • application/ogcapppkg+json

    +
    • +

  • application/cwl+json

    +
    • +
+ +

Additional CWL media types that would typically be used in a server that supports CWL are:

+ +

  • application/cwl

    +
    • +
+ + + + + + + + + + +3.<tab/>Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

+Benjamin Pross, Panagiotis (Peter) A. Vretanos: OGC 18-062r2, OGC API — Processes — Part 1: Core. Open Geospatial Consortium (2021). http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0.http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0https://docs.ogc.org/is/18-062r2/18-062r2.htmlOGC 18-062r2OGC 18-062r2 +Pross, B.: OGC 18-062, OGC API — Processes — Part 2: Deploy, Replace, UndeployOGC 20-044OGC 20-04420-044 +Benjamin Pross, Panagiotis (Peter) A. Vretanos: OGC 18-062r2, OGC API — Processes — Part 1: Core. Open Geospatial Consortium (2021). http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0.http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0https://docs.ogc.org/is/18-062r2/18-062r2.htmlOGC 18-062r2OGC 18-062r2 +Clemens Portele, Panagiotis (Peter) A. Vretanos, Charles Heazel: OGC 17-069r3, OGC API — Features — Part 1: Core. Open Geospatial Consortium (2019). http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0.http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0https://docs.ogc.org/is/17-069r3/17-069r3.htmlOGC 17-069r3OGC 17-069r3 + +<strong>Annex A</strong><br/>(normative)<br/><strong>Abstract Test Suite</strong> + +A.1.<tab/>Introduction +

OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested.

+ +

The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”.

+ + + +A.2.<tab/>Conformance Class Deploy, Replace, Undeploy + + + +

Conformance class A.1: Job Management

Identifierhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
Subjecthttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
Target TypeWeb API
Conformance testConformance test A.1-1: /conf/dru/deploy/post-op
+ + +A.2.1.<tab/>Create operation + + + +

Abstract test A.1

Identifier/conf/jm/create/post-op
Requirement/req/job-management/create/post-op
Test purpose

Validate that the server support HTTP POST operation at the path /jobs/

+
Test method

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/job-list” link on the landing page as well as for the {root}/jobs path.

    +
    2. +

  2. Issue an HTTP POST request for each path.

    +
    3. +

  3. Validate that the response header does not contain 405 Method not allowed

    +
    4. +
+
+ + + +<strong>Annex B</strong><br/>(informative)<br/><strong>Revision History</strong> + + + + + + + + + + + + +
DateReleaseEditorPrimary clauses modifiedDescription
2024-08-22NoneGérald FenoyallBoostraping the document
+ +Bibliography + OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: +.[1] + OpenAPI Specification 3.0.2OpenAPI Specification 3.0.2 + 3.0.2 +[1] + Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. [2] + +[2] + OpenEO: OpenEO Developers API Reference / Process Graphs. [3] + +[3] + + + + + diff --git a/extensions/job_management/standard/20-044.xml b/extensions/job_management/standard/20-044.xml new file mode 100644 index 00000000..9745f8bb --- /dev/null +++ b/extensions/job_management/standard/20-044.xml @@ -0,0 +1,1087 @@ + + + +OGC API - Processes - Part 4: Job Management +http://www.opengis.net/doc/IS/ogcapi-processes-4/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd +Geolabs + +Terradue Srl. + +Computer Research Institute of Montréal (CRIM). + +Gérald Fenoy + +Open Geospatial Consortium +OGC1.0en

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

+ +

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

+ +

The OGC API - Processes - Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard.

+ +

The OGC API - Processes - Part 3: Workflows draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to …​

+ +

The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

+ +

This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion.

+draft2019 +Open Geospatial Consortium +OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementation
ats_druhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
_99e940ea-ac12-4895-8c4c-7ab0fba8b43d/conf/dru/deploy/post-op
ats_dru_deploy_post-op/conf/jm/create/post-op
TOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 + + + +Copyright notice +

Copyright © 2019 Open Geospatial Consortium
To obtain additional rights of use, visit

+ + + +Note +

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

+ +

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

+ + + + + + +License Agreement +

Use of this document is subject to the license agreement at

+ + + + + + +Notice for Drafts +

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

+ +

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

+ + + + + + +

Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site:

+ + +Abstract

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

+ +

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

+ +

The OGC API — Processes — Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard.

+ +

The OGC API — Processes — Part 3: Workflows draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to …​

+ +

The OGC API — Processes — Part 4: Job Management draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

+ +

This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion.

+ +Security Considerations +

See OGC API — Processes — Part 1: Core, Clause 10.4.

+ +

Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations.

+ +

Users making modifications to process resources need to:

+ +

  1. Be authenticated,

    +
    2. +

  2. Have “modification privileges” on the processes offered through the API,

    +
    3. +

  3. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints.

    +
    4. +
+ +

The API definition, as defined in Clause 7.3 from , must reflect this in the resource paths and their available methods.

+ +

Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance:

+ +

The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation).

+ +

A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation.

+ + +Example OpenAPI definition with security requirements +

The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user.

+ +{ + "openapi" : "3.0.3", + "info" : { + "title" : "My API", + "description" : "This API ...", + "version" : "1.0.0" + }, + "servers" : [ { + "url" : "https://example.com/api/v1" + } ], + "security" : [ { + "JWT" : [ ], + "api_key": [ ] + } ], + "paths" : { }, + "components" : { + "securitySchemes": { + "JWT" : { + "type" : "http", + "scheme" : "bearer", + "bearerFormat" : "JWT" + }, + "api_key" : { + "type": "apiKey", + "name": "X-API-Key", + "in": "header" + } + } + } +} + + + +

If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.

+ +

In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided.

+ +Unauthorized requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | ----------------------------------------------------------->| + | | + | HTTP/1.1 401 Unauthorized | + | Date: Mon, 23 May 2022 11:18:45 GMT | + | WWW-Authenticate: Bearer realm="my-realm" | + | WWW-Authenticate: ApiKey header="X-API-Key" | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 86 | + | | + | { | + | "status": 401, | + | "title": "Unauthorized", | + | "detail": "HTTP 401 Unauthorized" | + | } | + | <-----------------------------------------------------------| + + +

HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023)

+ + +

If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”).

+ +Forbidden requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | Host: example.com | + | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | + |------------------------------------------------------------------>| + | | + | HTTP/1.1 403 Forbidden | + | Date: Mon, 23 May 2022 11:18:55 GMT | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 80 | + | | + | { | + | "status" : 403, | + | "title" : "Forbidden", | + | "detail" : "HTTP 403 Forbidden" | + | } | + |<------------------------------------------------------------------| + + +

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

+ +Submitters +

All questions regarding this submission should be directed to the editors or the submitters:

+ + + + + + + +
NameAffiliation
Gérald Fenoy (editor)GeoLabs
+ + + +Scope +

The OGC API — Processes — Part 4 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [] and defines the behavior of a server that supports the ability to create jobs without implying the process execution starts right away.

+ +

Specifically, the Processes Part 4 Standard specifies:

+ +

  • How to manage job.

    +
    • +

  • How to handle provenenance information associated with a job.

    +
    • +
+ + + +Conformance +

The OGC API — Processes — Part 4 Standard defines the following requirements classes.

+ +

The main requirements class is:

+ +

  • Job Management.

    +
    • +
+ +

This class specifies requirements that any Web API implementing Processes Part 4 must conform with.

+ +

The Job Management class does mandate a specific encoding and format for the job definition. However, the Part 4 extension defines the following conformance class:

+ +

  • OpenEO graph

    +
    • +
+ +

The OpenEO grap class defines that jobs can be created from an OpenEO graph.

+ +

The provenance information associated with a job is not mandated to be supported by the server. A dedicated requirements class Provenance is defined for this feature.

+ +

The standardization target for all Conformance class defined in this Standard is “Web API”.

+ +

Conformance with this Standard shall be checked using all the relevant tests specified in of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.

+ + + + + +Terms, definitions and abbreviated terms

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

+

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

+

For the purposes of this document, the following additional terms and definitions apply.

+ + +Terms and definitions + +Execution unit + + +

A component containing a process that an implementation of the Processes API Part 1 can run.

 + + + +Deploy + + +

Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard.

 + + + +Replace + + +

Replace refers to upgrading a deployed process from a Processes API implementation.

 + + + +Undeploy + + +

Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process.

 + + + + +Abbreviated terms +
CWL

Common Workflow Language

+
+
DRU

Deploy, Replace, Undeploy

+
+ + + +Conventions and background +

See , Clause 5.

+ + + +Requirements Class “Job Management” + +Overview + Web APIOGC API — Processes — Part 1: Core, Conformance Class ‘core’RFC 2616 (HTTP/1.1)label + + +

A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs.

+ +

The HTTP POST method is used to create new jobs.

+ +

The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint.

+ +

Finally, the HTTP POST method is used to start a job.

+ +

Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standard does mandate that a specific jobs schema be used. However, this extension defines the following conformance classe:

+ +

  • OpenEO Process Graph, that enables support for OpenEO-encoded jobs definition.

    +
    • +
+ + +HTTP status codes +

Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code.

+ +

The Status Codes listed in are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations.

+ + +Typical HTTP status codes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”.

+
Status codeDescription
200A successful request.
201The server has successfully completed the operation and a new resource has been created.
202The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
204A successful request with no additional content to send in the response.
400The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.
401The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource.
404The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
405The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.
406Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource.
412The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server.
413The server is refusing to process the request because the request content is larger than the server is willing or able to process.
415The server is refusing to service the request because the content is in a format not supported by this method on the target resource.
422The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing.
500An internal error occurred in the server.
+ + + +

More specific guidance is provided for each resource, where applicable.

+ + label/per/core/additional-status-codes

Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in .

+ + + +

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.

+ + + +Cross-origin requests +

See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).

+ + + + +Creating a new job + +Sequence diagram +

The following diagram illustrates the sequence diagram for deploying a new process to the API:

+ +Client Server + | | + | POST /jobs HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 201 Created | + | Location: /jobs/{jobId} | + |<------------------------------------------------------------| + + + + +Operation + label/req/job-management/create/post-op

The server SHALL support the HTTP POST operation at the path /jobs.

+ + + + + +Request body + +Overview + label/req/job-management/create/body

The body of the POST request SHALL be in JSON format.

+ + + + label/per/job-management/create/body

A server MAY support any encoding in the body of a HTTP POST operation.

+ + + + label/req/job-management/create/content-type

The Content-Type header SHALL be used to declare the media type of the request.

+ + + +

See section 3.1.1.5 of RFC 7231 for details.

+ + + +OGC API — Processes — Workflow Execute Request body + label/rec/job-management/create/body-ogcapi-processes

If the job can be encoded as an OGC API — Processes — Workflow Execute Request, implementation SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

+ + + + + +OpenEO Process Graph body + label/rec/job-management/create/body-openeo

If the job can be encoded as an OpenEO graph, implementation SHOULD consider supporting the OpenEO graph encoding.

+ + + + + + +Response + label/req/job-management/create/response-jobid

If the operation completes, the server SHALL generate a job identifier (i.e. {jobId}) for the created job.

+ + + + label/req/job-management/create/response-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 201.

+

A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /jobs/{jobId}).

+ + + + label/req/job-management/create/response-body

The response SHALL include a body that contains a status information of the created job conforms to the statusInfo.yaml schema.

+

The response SHALL contains a pending status code and the jobId property that contains the job identifier.

+ + + + + +Exceptions +

See for general guidance.

+ +

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from .

+ + + + +Updating an existing job + +Sequence diagram +

The following diagram illustrates the sequence diagram for updating a +previously created job. The identifier of the job does not change.

The new job definition replaces the old job definition. Version control is not discussed in this Standard.

+

+ + + +Client Server + | | + | PUT /jobs/{jobId} HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +Operation + label/req/job-management/update/put-op

For every created jobs (path ‘/jobs/{jobId}’), the server SHALL support the HTTP PUT operation.

+

The parameter ‘jobId’ is each ‘jobID’ property in the jobs list response (JSONPath: $.jobs[*].jobID).

+ + + + + +Request body + + + +Overview + label/req/job-management/update/body*

The body of a PUT request SHALL be in JSON format.

+ + + + label/per/job-management/update/body

A server MAY support any encoding in the body of a HTTP PUT operation.

+ + + + label/req/job-management/update/content-type

As per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes.

+ + + + +OGC API — Processes — Workflow Execute Request body + label/rec/job-management/update/body-ogcapi-processes

If a job can be created from an rc_ogcapi-processes,OGC API — Processes — Workflow Execute Request>>, implementations SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

+ + + + + +OpenEO Process Graph body + label/rec/job-management/update/body-openeo

If a job can be created from an OpenEO graph, implementations SHOULD consider supporting the OpenEO graph encoding.

+ + + + + + +Response + label/req/job-management/update/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204.

+

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

+ + + +

The status code depends on the server. If the server has replaced the job, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content).

+ +

If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client.

+ + + +Exceptions +

See for general guidance.

+ +

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from .

+ +

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from .

+ + + + +Staring a job + +Sequence diagram +

The following diagram illustrates the sequence diagram for starting the execution of a previously created jobs.

+ +Client Server + | | + | POST /jobs/{jobId} HTTP/1.1 | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +Operation + label/req/job-management/start/start-op

For every created jobs (path: /jobs/{jobId}/results), the server SHALL support the HTTP POST operation.

+

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+ + + + + +Response + label/req/job-management/start/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

+

A response SHALL be a document that conforms to statusInfo.yaml.

+ + + + + +Exceptions +

See HTTP status codes for general guidance.

+ +

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from .

+ + + + +Job definition +

For every job, it is possible to retrieve its original definition. It corresponds to the request’s body used to create or update the jobs.

+ + +Operation + label/req/deploy-replace-undeploy/package/get-op

For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package.

+

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

+ + + + + +Response + +Overview + label/req/deploy-replace-undeploy/package/response-success

A successful access to the resource SHALL be reported as a response with a HTTP status code 200.

+ + + + label/req/deploy-replace-undeploy/package/response-body

A response with HTTP status code 200 SHALL include a body that contains the request body used to create or update the job.

+ + + + + + +Exceptions +

See HTTP status codes for general guidance.

+ +

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from .

+ + + + + +Requirements Class “OGC API — Process — Workflow Execute Request” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel + + +

This requirements class defines that the OGC API — Process — Workflow Execute Request is supported as an encoding for job definitions.

+ + + +OGC API — Processes + +Overview + label/req/ogcapi-processes/schema

An OGC API - Processes document SHALL be based upon the JSON schema execute-workflow.yaml.

+ + + + + + +Create + +OGC API — Processes body + label/req/ogcapi-processes/create/body

The body of the POST request SHALL be based upon the OpenAPI 3.0 schema execute-workflows.yaml

+

The media type application/json SHALL be used to indicate that request body contains a processes description encoded as an OGC API — Processes.

+ + + + + + +Update + +OGC API — Processes body + label/req/ogcapi-processes/update/body

The media type application/ogcapi-processes+json SHALL be used to indicate that request body contains a job encoded as an OGC API — Processes.

+ + + + + + +Job definition + +OGC API — Processes content + label/req/ogcapi-processes/definition/response-body

A response with HTTP status code 200 SHALL include a body that contains the OGC API — Processes to use to deploy the process.

+ + + + + + + +Requirements Class “OpenEO Process Graph” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel + + +

This requirements class defines that the server supports the OpenEO Process Graph as an encoding for job definitions.

+ + + +OpenEO Process Graph + +Overview + label/req/openeo/schema

An OpenEO Process Graph document SHALL be based upon the JSON schema .

+ + + + +Schema for OpenEO Process Graph +type: object +additionalProperties: + type: object + required: + - process_id + - arguments + properties: + process_id: + type: string + arguments: {} + + + + + +Create + +OpenEO body + label/req/openeo/create/body

The media type application/openeo+json SHALL be used to indicate that request body contains a processes description encoded as an OpenEO Process Graph.

+ + + + + + +Update + +OpenEO body + label/req/openeo/update/body

The media type application/openeo+json SHALL be used to indicate that request body contains a job encoded as an OpenEO Process Graph.

+ + + + + + +Job definition + +OpenEO content + label/req/openeo/definition/response-body

A response with HTTP status code 200 SHALL include a body that contains the OpenEO Process Graph to use to deploy the process.

+ + + + + + + +Requirements Class “Quotation” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeolabel + + + + + +Requirements Class “Provenance” + +Overview +

This requirements class defines how to allow client application accessing the provenance of a job run.

+ + Web APIOGC API — Processes — Part 1: Corelabel + + + + +Additional endpoints + +Inputs +

The server MUST provide an endpoint to retrieve the inputs of a job run.

+ + +Operation + label/req/provenance/inputs/get-op

For every created jobs (path: /jobs/{jobId}/inputs), the server SHALL support the HTTP GET operation.

+

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+ + + + + +Response + label/req/provenance/inputs/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

+

The response SHALL contains a JSON document that conforms to the schema inputs.yaml.

+ + + + + + +Outputs +

The server MUST provide an endpoint to retrieve the outputs of a job run.

+ + +Operation + label/req/provenance/outputs/get-op

For every created jobs (path: /jobs/{jobId}/outputs), the server SHALL support the HTTP GET operation.

+

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+ + + + + +Response + label/req/provenance/outputs/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

+

The response SHALL contains a JSON document that conforms to the schema outputs.yaml.

+ + + + + + +Run +

The server MUST provide an endpoint to retrieve the run of a job.

+ + +Operation + label/req/provenance/run/get-op

For every created jobs (path: /jobs/{jobId}/run), the server SHALL support the HTTP GET operation.

+

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

+ + + + + + + + +OpenAPI 3.0 +

See , Clause 9.

+ + + +Media Types +

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

    +
    • +
+ +

Additional CWL media types that would typically be used in a server that supports CWL are:

+ +

  • application/cwl

    +
    • +
+ + + + + + + + + + +Abstract Test Suite + +Introduction +

OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested.

+ +

The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”.

+ + + +Conformance Class Deploy, Replace, Undeploy + +Job Managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementTarget TypeWeb API /conf/dru/deploy/post-op + + + + +Create operation + /conf/jm/create/post-optarget/req/job-management/create/post-op

Validate that the server support HTTP POST operation at the path /jobs/

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/job-list” link on the landing page as well as for the {root}/jobs path.

    +
    2. +

  2. Issue an HTTP POST request for each path.

    +
    3. +

  3. Validate that the response header does not contain 405 Method not allowed

    +
    4. +
+ + + + + +Revision History + + + + + + + + + + + + +
DateReleaseEditorPrimary clauses modifiedDescription
2024-08-22NoneGérald FenoyallBoostraping the document
+ +Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

+ + 2024-08-29 + +OGC API + + +Processes + + +Part 1: Core + + +OGC API — Processes — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 + https://docs.ogc.org/is/18-062r2/18-062r2.html + 18-062r2 + + 2021-12-20 + + + + + + Benjamin Pross + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + +Open Geospatial Consortium + + + + 2 + en + + The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. + +By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. + +The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. + +The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. + + +Pross, B.: OGC 18-062, OGC API — Processes — Part 2: Deploy, Replace, UndeployOGC 20-04420-044 + + 2024-08-29 + +OGC API + + +Processes + + +Part 1: Core + + +OGC API — Processes — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 + https://docs.ogc.org/is/18-062r2/18-062r2.html + 18-062r2 + + 2021-12-20 + + + + + + Benjamin Pross + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + +Open Geospatial Consortium + + + + 2 + en + + The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. + +By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. + +The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. + +The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. + + + + 2024-08-29 + +OGC API + + +Features + + +Part 1: Core + + +OGC API — Features — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0 + https://docs.ogc.org/is/17-069r3/17-069r3.html + 17-069r3 + + 2019-10-07 + + + + + + Clemens Portele + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + + Charles Heazel + + + + + + + +Open Geospatial Consortium + + + + 3 + en + + OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. + +The OGC API family of standards is organized by resource type. This standard specifies the fundamental API building blocks for interacting with features. The spatial data community uses the term ‘feature’ for things in the real world that are of interest. + + + +Bibliography + OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: +. + OpenAPI Specification 3.0.2 + 3.0.2 + + Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. + [2] + + OpenEO: OpenEO Developers API Reference / Process Graphs. + [3] + + + + + + diff --git a/extensions/job_management/standard/20-044.xml.abort b/extensions/job_management/standard/20-044.xml.abort new file mode 100644 index 00000000..0744cadd --- /dev/null +++ b/extensions/job_management/standard/20-044.xml.abort @@ -0,0 +1,1509 @@ + + + +OGC API - Processes - Part 4: Job Management +http://www.opengis.net/doc/IS/ogcapi-processes-2/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd +Geolabs + +CubeWerx Inc + +Terradue Srl. + +Wuhan University (WHU). + +Computer Research Institute of Montréal (CRIM). + +Gérald Fenoy + +Open Geospatial Consortium +OGC1.0en

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

+ +

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

+ +

OGC API - Processes - Part 2: Deploy, Replace, Undeploy extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard.

+ +

This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion.

+draft2019 +Open Geospatial Consortium +OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementation
ats_dru_mutable-process/req/dru/mutable-process
ats_dru_test-process/req/dru/test-process
ats_druhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/deploy-replace-undeploy
_f7ee31b4-f02b-4ada-a34f-569b063612d1/conf/dru/static-indicator
_2c99dc51-ecdc-4480-b23e-d5f831205920/conf/dru/deploy/post-op
_5b5ebd3a-cd9f-408a-9905-09b91d420c6d/conf/dru/deploy/content-type
_8e36ae58-5789-4dd1-80b9-956967dc8c22/conf/dru/deploy/unsupported-content-type
_7843c6bd-67d7-4dc9-83da-c11f9cfe41a1/conf/dru/replace/put-op
_231f2a7f-6dd1-4bfe-b304-5c64040f15d8/conf/dru/replace/content-type
_79103ae8-bdc4-4213-98b6-32a8b280f7c3/conf/dru/undeploy/delete-op
_64a67495-1e74-46e8-990a-ad273a56a7e2/conf/dru/undeploy/response
_2ca56830-1a16-4fae-9722-8eca5cd08d27/conf/dru/undeploy/response-immutable
ats_dru_static-indicator/conf/dru/static-indicator
ats_dru_deploy_post-op/conf/dru/deploy/post-op
ats_dru_deploy_content-type/conf/dru/deploy/content-type
ats_dru_deploy_unsupported-content-type/conf/dru/deploy/unsupported-content-type
ats_dru_replace_put-op/conf/dru/replace/put-op
ats_dru_replace_content-type/conf/dru/replace/content-type
ats_dru_undeploy_delete-op/conf/dru/undeploy/delete-op
ats_dru_undeploy_response/conf/dru/undeploy/response
ats_dru_undeploy_response-immutable/conf/dru/undeploy/response-immutable
ats_ogcapppkghttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/ogcapppkg
_b663cbca-b5f5-44f3-a97c-246087f2c4e3/conf/ogcapppkg/deploy/body
_682969d9-d3b8-46ed-a88e-2fe35852baa3/conf/ogcapppkg/deploy/response
_d3f14213-fdd8-489e-a3ca-935b8f764f40/conf/ogcapppkg/deploy/response-success
_ead29a44-1dc5-4fd3-99a9-c92103b5d9e3/conf/ogcapppkg/deploy/response-duplicate
_981d7d56-4bdc-4ed2-8d10-e3a1988a2423/conf/ogcapppkg/replace/body
_6f6e06b2-ccf3-4b2a-bba0-0e4f72efcd51/conf/ogcapppkg/replace/response
ats_ogcapppkg_deploy_body/conf/ogcapppkg/deploy/body
ats_ogcapppkg_deploy_response/conf/ogcapppkg/deploy/response
ats_ogcapppkg_deploy_response-success/conf/ogcapppkg/deploy/response-success
ats_ogcapppkg_deploy_response-duplicate/conf/ogcapppkg/deploy/response-duplicate
ats_ogcapppkg_replace_body/conf/ogcapppkg/replace/body
ats_ogcapppkg_replace_response/conf/ogcapppkg/replace/response
ats_dockerhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/docker
_8abd0775-f4a6-4530-8633-3a1ec8a28c99/conf/docker/deploy/body
_92183e95-5148-414b-abe9-44bb78da02b5/conf/docker/replace/body
ats_docker_deploy_body/conf/docker/deploy/body
ats_docker_replace_body/conf/docker/replace/body
ats_cwlhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/cwl
_e5c50d2f-dec9-4c90-a1de-5d61ad8e454b/conf/cwl/deploy/body
_0274eb63-ac42-4f63-8e23-c6b9e1affcbb/conf/cwl/replace/body
ats_cwl_deploy_body/conf/cwl/deploy/body
ats_cwl_replace_body/conf/cwl/replace/body
TOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 + + + +Copyright notice +

Copyright © 2019 Open Geospatial Consortium
To obtain additional rights of use, visit

+ + + +Note +

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

+ +

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

+ + + + + + +License Agreement +

Use of this document is subject to the license agreement at

+ + + + + + +Notice for Drafts +

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

+ +

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

+ + + + + + +

Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site:

+ + +Abstract

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

+ +

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

+ +

OGC API — Processes — Part 2: Deploy, Replace, Undeploy extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard.

+ +

This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion.

+ +Security Considerations +

See OGC API — Processes — Part 1: Core, Clause 10.4.

+ +

Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations.

+ +

Users making modifications to process resources need to:

+ +

  1. Be authenticated,

    +
    2. +

  2. Have “modification privileges” on the processes offered through the API,

    +
    3. +

  3. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints.

    +
    4. +
+ +

The API definition, as defined in Clause 7.3 from , must reflect this in the resource paths and their available methods.

+ +

Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance:

+ +

The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation).

+ +

A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation.

+ + +Example OpenAPI definition with security requirements +

The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user.

+ +{ + "openapi" : "3.0.3", + "info" : { + "title" : "My API", + "description" : "This API ...", + "version" : "1.0.0" + }, + "servers" : [ { + "url" : "https://example.com/api/v1" + } ], + "security" : [ { + "JWT" : [ ], + "api_key": [ ] + } ], + "paths" : { }, + "components" : { + "securitySchemes": { + "JWT" : { + "type" : "http", + "scheme" : "bearer", + "bearerFormat" : "JWT" + }, + "api_key" : { + "type": "apiKey", + "name": "X-API-Key", + "in": "header" + } + } + } +} + + + +

If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.

+ +

In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided.

+ +Unauthorized requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | ----------------------------------------------------------->| + | | + | HTTP/1.1 401 Unauthorized | + | Date: Mon, 23 May 2022 11:18:45 GMT | + | WWW-Authenticate: Bearer realm="my-realm" | + | WWW-Authenticate: ApiKey header="X-API-Key" | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 86 | + | | + | { | + | "status": 401, | + | "title": "Unauthorized", | + | "detail": "HTTP 401 Unauthorized" | + | } | + | <-----------------------------------------------------------| + + +

HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023)

+ + +

If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”).

+ +Forbidden requestClient Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | Host: example.com | + | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | + |------------------------------------------------------------------>| + | | + | HTTP/1.1 403 Forbidden | + | Date: Mon, 23 May 2022 11:18:55 GMT | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 80 | + | | + | { | + | "status" : 403, | + | "title" : "Forbidden", | + | "detail" : "HTTP 403 Forbidden" | + | } | + |<------------------------------------------------------------------| + + +

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

+ +Submitters +

All questions regarding this submission should be directed to the editors or the submitters:

+ + + + + + + + + + + +
NameAffiliation
Panagiotis (Peter) A. Vretanos (editor)CubeWerx Inc.
Gérald Fenoy (editor)GeoLabs
Pedro GonçalvesTerradue Srl.
+ + + +Scope +

The OGC API — Processes — Part 2 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [] and defines the behavior of a server that supports the ability to dynamically add, replace and/or undeploy processes via an OGC API — Processes implementation instance.

+ +

Specifically, the Processes Part 2 Standard specifies:

+ +

  • How to deploy a new process.

    +
    • +

  • How to replace an existing process.

    +
    • +

  • How to undeploy an existing process.

    +
    • +
+ +

The following table crosswalks each of the resource endpoints discussed in this Standard with the HTTP methods POST, PUT and DELETE. Each intersecting cell in the table either contains the name of the operation for that combination of resource endpoint and HTTP method, or it contains the phrase “n/a” which is used to indicate that this Standard does not specify any behavior for that combination of resource endpoints and the HTTP method.

+ + +Supported HTTP methods by resource + + + + + + + + + + + + + + + +
Resource endpointHTTP method
POSTPUTDELETE
/processesdeployn/an/a
/processes/{processId}n/areplaceundeploy
+ + + +Conformance +

The OGC API — Processes — Part 2 Standard defines the following requirements classes.

+ +

The main requirements class is:

+ +

  • Deploy, Replace, Undeploy.

    +
    • +
+ +

This class specifies requirements that any Web API implementing Processes Part 2 must conform with.

+ +

The Deploy, Replace, Undeploy class does not mandate a specific encoding or format for the formal definition of a process. However, the Part 2 extension defines the following conformance class:

+ +

  • OGC Application Package

    +
    • +
+ +

The OGC Application Package class defines the schema of a document that formally defines the inputs, outputs and other necessary metadata about a process that is to be dynamically deployed through the API.

+ +

The Application Package encoding is not mandatory. An implementation of this extension may choose to implement some other process description instead. That said, the Deploy, Replace, Undeploy conformance class includes recommendations to support the OGC Application Package.

+ +

A requirement class is dedicated to the deployment of containers as processes:

+ +

  • Docker

    +
    • +
+ +

In addition to the previous encoding, another conformance class is provided to enable support for the Common Workflow Language (CWL):

+ +

  • CWL

    +
    • +
+ +

The standardization target for all Conformance class defined in this Standard is “Web API”.

+ +

Conformance with this Standard shall be checked using all the relevant tests specified in of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.

+ + + + + +Terms, definitions and abbreviated terms

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

+

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

+

For the purposes of this document, the following additional terms and definitions apply.

+ + +Terms and definitions + +Execution unit + + +

A component containing a process that an implementation of the Processes API Part 1 can run.

 + + + +Deploy + + +

Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard.

 + + + +Replace + + +

Replace refers to upgrading a deployed process from a Processes API implementation.

 + + + +Undeploy + + +

Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process.

 + + + + +Abbreviated terms +
CWL

Common Workflow Language

+
+
DRU

Deploy, Replace, Undeploy

+
+ + + +Conventions and background +

See , Clause 5.

+ + + +Requirements Class “Deploy, Replace, Undeploy (DRU)” + +Overview + Web APIOGC API — Processes — Part 1: Core, Conformance Class ‘core’RFC 2616 (HTTP/1.1)label + + +

A server that implements the DRU Requirements Class provides the ability to dynamically deploy, replace and undeploy processes.

+ +

The HTTP POST method is used to deploy a new process to the API.

+ +

The HTTP PUT method is used to replace the definition of a previously deployed processes that are accessible via the Processes API endpoint.

+ +

Finally, the HTTP DELETE method is used to undeploy a previously deployed process that is accessible via the Processes API endpoint.

+ +

Deploying or replacing a process requires that a formal description of the new or replacement process be provided by the client. This Standard does not mandate that a specific processes description language or vocabulary be used. However, to promote interoperability, this extension defines two conformance classes:

+ +

  • OGC Application Package, that defines a formal process description language encoded using JSON,

    +
    • +

  • CWL, that enables support for CWL-encoded process definition.

    +
    • +
+ +

A recommendation is made later in this Standard that all implementations of Processes API Part 2 extension support the OGC Application Package.

+ + +HTTP status codes +

Clients implementing the Processes API Part 2 should be prepared to handle any legal HTTP or HTTPS status code.

+ +

The Status Codes listed in are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations.

+ + +Typical HTTP status codes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”.

+
Status codeDescription
200A successful request.
201The server has successfully completed the operation and a new resource has been created.
202The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
204A successful request with no additional content to send in the response.
400The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.
401The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource.
404The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
405The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.
406Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource.
412The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server.
413The server is refusing to process the request because the request content is larger than the server is willing or able to process.
415The server is refusing to service the request because the content is in a format not supported by this method on the target resource.
422The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing.
500An internal error occurred in the server.
+ + + +

More specific guidance is provided for each resource, where applicable.

+ + label/per/core/additional-status-codes

Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in .

+ + + +

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.

+ + + +Cross-origin requests +

See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).

+ + + + +Immutable processes +

The Processes API Part 2 extension recognizes that an OGC web processing API may be deployed with a set of static, built-in processes that are immutable and cannot be removed or modified via requests from a deploy-replace-undeploy API implementation. In an API Description Document (e.g. OpenAPI), such process paths would not include support for the HTTP POST, PUT or DELETE methods.

+ +

However, to make it clear which processes in a collection (path: /processes) are built-in — and thus immutable — and which have been dynamically deployed, the processes collection schema is modified to add a flag indicating this aspect of a process.

+ + label/req/deploy-replace-undeploy/static-indicator

The optional property mutable SHALL be used to indicate whether a process is a static or built-in process that is immutable or a dynamically added process that is mutable.

+

A value of true SHALL be used to indicate that a processes is mutable and can thus be manipulated through an API request.

+

A value of false SHALL be used to indicate that a processes is immutable and can thus not be manipulated through an API request.

+

The default value SHALL be true.

+ + + +

The following schema fragment extends the process summary accessible via the /processes path to add the mutable property.

+ +allOf: + - $ref: "https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/processSummary.yaml" + - type: object + properties: + mutable: + type: boolean + default: true + + + + +Deploying a new process to the API + +Sequence diagram +

The following diagram illustrates the sequence diagram for deploying a new process to the API:

+ +Client Server + | | + | POST /processes HTTP/1.1 | + | Content-Type: application/ogcapppkg+json | + | | + | ... Body contains a formal description of the process to | + | add (e.g. OGC Application Package) ... | + |------------------------------------------------------------>| + | | + | HTTP/1.1 201 Created | + | Location: /processes/{processId} | + |<------------------------------------------------------------| + + + + +Operation + label/req/deploy-replace-undeploy/deploy/post-op

The server SHALL support the HTTP POST operation at the path /processes.

+ + + + + +Request body + +Overview + label/req/deploy-replace-undeploy/deploy/body

The body of the POST request SHALL contain a formal description of the process to be dynamically deployed to the API.

+ + + + label/per/deploy-replace-undeploy/deploy/body

A server MAY support any processes description encoding in the body of a HTTP POST operation.

+ + + + label/req/deploy-replace-undeploy/deploy/content-type

The Content-Type header SHALL be used to declare the media type of the request body containing a description of the processes to be added to the API.

+ + + +

See section 3.1.1.5 of RFC 7231 for details.

+ + + +OGC Application Package body + label/rec/deploy-replace-undeploy/deploy/body-ogcapppkg

If a process can be represented for the intended use as an OGC Application Package, implementations SHOULD consider supporting the OGC Application Package encoding for describing the process to be added to the API.

+ + + + + +CWL body + label/rec/deploy-replace-undeploy/deploy/body-cwl

If a process can be encoded for the intended use in CWL, implementations SHOULD consider supporting the CWL encoding for describing the process to be deployed to the API.

+ + + + + + +Response + label/req/deploy-replace-undeploy/deploy/response-pid

If the operation completes, the server SHALL assign the processes identifier (i.e. {processId}) specified in the processes description for the newly added processes.

+ + + + label/req/deploy-replace-undeploy/deploy/response-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 201.

+

A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /processes/{processId}).

+

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

+ + + + label/req/deploy-replace-undeploy/deploy/response-body

The response SHALL include a body that contains a summary description of the added process conforms to the processSummary.yaml schema.

+ + + + + +Exceptions +

See for general guidance.

+ + label/req/deploy-replace-undeploy/deploy/unsupported-media-type

If the server does not support the Content-Type header associated with the request body, the code of the response SHALL be 415 Unsupported Media Type.

+

The content of that response SHALL be based upon the OpenAPI 3.0 schema exception.yaml.

+

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/unsupported-media-type”.

+ + + + label/req/deploy-replace-undeploy/deploy/response-duplicate

If a process with the same identifier already exists on the server, the code of the response SHALL be 409.

+

A response with HTTP status code 409 MAY include a Location header with the URI of the duplicated processes (path: /processes/{processId}).

+

The content of that response SHALL be based upon the OpenAPI 3.0 schema exception.yaml.

+

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/duplicated-process”.

+ + + + label/req/deploy-replace-undeploy/deploy/response-immutable

If a process with the same identifier already exists on the server and is immutable, the code of the response SHALL be 403.

+

A response with HTTP status code 403 MAY include a Location header with the URI of the existing process (path: /processes/{processId}).

+

The content of that response shall be based upon the OpenAPI 3.0 schema exception.yaml.

+

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/immutable-process”.

+ + + + + + +Replacing an existing processes + +Sequence diagram +

The following diagram illustrates the sequence diagram for replacing a +previously deployed processes. The identifier of the process does not change.

The new process definition replaces the old process definition. Version control is not discussed in this Standard.

+

+ + + +Client Server + | | + | PUT /processes/{processId} HTTP/1.1 | + | Content-Type: application/ogcapppkg+json | + | | + | ... Body contains a formal description of the process to | + | replace the existing process (e.g. OGC Application | + | Package) ... | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +Operation + label/req/deploy-replace-undeploy/replace/put-op

For every dynamically deployed processes (path ‘/processes/{processId}’), the server SHALL support the HTTP PUT operation.

+

The parameter ‘processId’ is each ‘id’ property in the process collection response (JSONPath: $.processes[*].id).

+ + + + + +Request body + + + +Overview + label/req/deploy-replace-undeploy/replace/body*

The body of a PUT request SHALL contain a formal description of the replacement process.

+ + + + label/per/deploy-replace-undeploy/replace/body

A server MAY support any processes description encoding in the body of a HTTP PUT operation.

+ + + + label/req/deploy-replace-undeploy/replace/content-type

As per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes.

+ + + + +OGC Application Package body + label/rec/deploy-replace-undeploy/replace/body-ogcapppkg

If a process can be described for the intended use as an OGC Application Package, implementations SHOULD consider supporting the OGC Application Package encoding for describing the replacement process.

+ + + + + +CWL body + label/rec/deploy-replace-undeploy/replace/body-cwl

If a process can be encoded for the intended use in CWL, implementations SHOULD consider supporting the CWL encoding for describing the replacement process.

+ + + + + + +Response + label/req/deploy-replace-undeploy/replace/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204.

+

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

+ + + +

The status code depends on the server. If the server has replaced the process, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content).

+ +

If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client.

+ + + +Exceptions +

See for general guidance.

+ +

If the request body’s media type is not supported by the server, then /req/deploy-replace-undeploy/deploy/unsupported-media-type applies.

+ +

If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process from .

+ +

If the process exist but is immutable then /req/deploy-replace-undeploy/deploy/response-immutable applies.

+ + + + +Removing a processes from the API (undeployProcess) + +Sequence diagram +

The following diagram illustrates the sequence diagram for undeploying a previously deployed process.

+ +Client Server + | | + | DELETE /processes/{processId} HTTP/1.1 | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| + + + + +Operation + label/req/deploy-replace-undeploy/undeploy/delete-op

For every dynamically added process (path: /processes/{processId}), the server SHALL support the HTTP DELETE operation.

+

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

+ + + + + +Response + label/req/deploy-replace-undeploy/undeploy/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘204’.

+ + + + + +Exceptions +

See HTTP status codes for general guidance.

+ +

If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process from .

+ +

If the process exist but is immutable then /req/deploy-replace-undeploy/deploy/response-immutable applies.

+ + + + +Retrieving the formal description +

For every mutable process, it is possible to retrieve its formal description. It corresponds to the request’s body used to deploy or replace the process.

+ + +Operation + label/req/deploy-replace-undeploy/package/get-op

For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package.

+

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

+ + + + + +Response + +Overview + label/req/deploy-replace-undeploy/package/response-success

A successful access to the resource SHALL be reported as a response with a HTTP status code 200.

+ + + + label/req/deploy-replace-undeploy/package/response-body

A response with HTTP status code 200 SHALL include a body that contains the request body used to deploy or replace the process.

+ + + + + + +Exceptions +

See HTTP status codes for general guidance.

+ +

If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process from .

+ +

If the process exist but is immutable then /req/deploy-replace-undeploy/deploy/response-immutable applies.

+ + + + + +Requirements Class “OGC Application Package” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeploylabel + + +

This requirements class defines the schema of an OGC Application Package. An OGC Application Package is a document that describes a process in sufficient detail so that an implementation of this extension can dynamically deploy the process and make it accessible via an OGC API — Processes implementation.

+ +

The information contained in an OGC Application Package can include:

+ +

  • A formal description of the process including what inputs the process takes and what outputs the process generates.

    +
    • +

  • Either an inline or by reference execution unit which is the code that the server needs to execute whenever the process is invoked.

    +
    • +

  • Additional resource information required by the execution unit.

    +
    • +
+ + + +OGC Application Package schema + +Overview + label/req/ogcapppkg/schema

An OGC Application Package document SHALL be based upon the OpenAPI schema ogcapppkg.yaml.

+ + + + +Schema for the OGC Application Package +Unresolved directive in sections/clause_7_apppkg.adoc - include::../../../../openapi/schemas/processes-dru/ogcapppkg.yaml[] + + + + +processDescription property +

The formal process description (i.e. its inputs, its output, etc.) is provided, either in-line using the processDescription property or may be inferred from the information provided in the execution unit.

+ + label/req/ogcapppkg/process-description

The value of the processDescription property SHALL be based upon the OpenAPI schema process.yaml.

+ + + + + +executionUnit property +

If the schema defined for the executionUnit property of an OGC Application Package remains open, it can be restricted in other Requirements.

+ + label/rec/ogcapppkg/execution-unit-docker

If the execution unit is a Docker image, implementations SHOULD consider supporting the Docker Requirements class.

+ + + + label/rec/ogcapppkg/execution-unit-cwl

If the execution unit is encoded in CWL, implementations SHOULD consider supporting the CWL Requirement class.

+ + + + + + +Deploy + +OGC Application Package body + label/req/ogcapppkg/deploy/body

The media type application/ogcapppkg+json SHALL be used to indicate that request body contains a processes description encoded as an OGC Application Package.

+ + + + + + +Replace + +OGC Application Package body + label/req/ogcapppkg/replace/body

The media type application/ogcapppkg+json SHALL be used to indicate that request body contains a processes description encoded as an OGC Application Package.

+ + + + + + +Formal description + +OGC Application Package content + label/req/ogcapppkg/package/response-body

A response with HTTP status code 200 SHALL include a body that contains the OGC Application Package to use to deploy the process.

+ + + + + + + +Requirements Class “Docker” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkglabel + + +

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 + +executionUnit property + +Overview + label/req/docker/schema

The executionUnit property of an OGC Application Package document SHALL be based upon the schema executionUnit.yaml.

+ + + + +Schema for the Docker execution unit parameter +Unresolved directive in sections/clause_8_docker.adoc - include::../../../../openapi/schemas/processes-dru/executionUnit.yaml[] + + + + +type and image properties +

The execution unit can be specified by reference, using a Docker image reference.

+ + label/req/docker/execution-unit

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 image property SHALL be a reference to the Docker image.

+ + + + + + + + +Requirements Class “CWL” + +Overview + Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkgCommon Workflow Language label + + +

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 + +executionUnit property +

In case the OGC Application Package encoding is used, the following Requirement applies.

+ + label/req/cwl/execution-unit

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 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 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.

+ + + +

Below is an example of a deploy body request using a CWL-encoded execution unit by reference.

+ +{ + "executionUnit": { + "href": "https://raw.githubusercontent.com/EOEPCA/app-snuggs/main/app-package.cwl", + "type": "application/cwl" + } +} + + +

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.

+ +{ + "executionUnit": { + "value": { ... }, + "mediaType": "application/cwl+json" + } +} + + + + + +Deploy + +CWL body + label/req/cwl/deploy/body

The media type application/cwl SHALL be used to indicate that request body contains a processes description encoded as CWL.

+ + + + + +w parameter +

When encoded in CWL, processes are identified as instances of the workflow class.

+ + label/req/cwl/deploy/w-param

If the CWL contains more than a single workflow identifier, an additional w query parameter MAY be used to target a specific workflow id to be deployed. If not used, the first process found SHALL be deployed.

+ + + + + +Exception + label/req/cwl/deploy/exception-workflow-not-found

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.

+

The content of that response SHALL be based upon the schema exception.yaml.

+

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/workflow-not-found”.

+ + + + + + +Replace + +CWL body + label/req/cwl/replace/body

The media type application/cwl SHALL be used to indicate that request body contains a processes description encoded as CWL.

+ + + + + + +Formal description + +CWL content + label/req/cwl/package/response-body

A response with HTTP status code 200 SHALL include a body that contains:

+

  • the CWL to use to deploy the process, in case the Content-Type used to deploy the process was application/cwl.

    +
    • +

  • the OGC Application Package to use to deploy the process, in case the Content-Type used to deploy the process was application/ogcapppkg+json.

    +
    • +
+ + + + + + + +OpenAPI 3.0 +

See , Clause 9.

+ + + +Media Types +

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

    +
    • +
+ +

Additional CWL media types that would typically be used in a server that supports CWL are:

+ +

  • application/cwl

    +
    • +
+ + + + + + + + + + +Abstract Test Suite + +Introduction +

OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested.

+ +

The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”.

+ +

The following requirements apply for a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy under test:

+ + /req/dru/mutable-process

Ensure that a mutable process is offered by the server being tested.

+

If a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy is tested using CITE tests, the server SHALL offer at least one mutable process.

+ + + +

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:

+ + /req/dru/test-process

Ensure that an application package URL can be provided in CWL encodig to test deploying processes using OGC Application Package and CWL conformance classes.

+

If a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy is tested using CITE tests, it should provide a URL to an example application package encoded in CWL for tests against the OGC Application Package and CWL conformance classes.

+ + + + + +Conformance Class Deploy, Replace, Undeploy + +Deploy, Replace, Undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/deploy-replace-undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/deploy-replace-undeployTarget TypeWeb API /conf/dru/static-indicator /conf/dru/deploy/post-op /conf/dru/deploy/content-type /conf/dru/deploy/unsupported-content-type /conf/dru/replace/put-op /conf/dru/replace/content-type /conf/dru/undeploy/delete-op /conf/dru/undeploy/response /conf/dru/undeploy/response-immutable + + + + +Immutable processes + /conf/dru/static-indicatortarget/req/deploy-replace-undeploy/static-indicator

Validate that the process list contains processes with the mutable property.

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Issue an HTTP GET request for each path

    +
    3. +

  3. Validate the process list is composed of processes that get the mutable Boolean parameter set to true or false

    +
    4. +
+ + + + + +Deploy operation + /conf/dru/deploy/post-optarget/req/deploy-replace-undeploy/deploy/post-op

Validate that the server support HTTP POST operation at the path /processes

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Issue an HTTP POST request for each path.

    +
    3. +

  3. Validate that the response header does not contain 405 Method not allowed

    +
    4. +
+ + + + /conf/dru/deploy/content-typetarget/req/deploy-replace-undeploy/deploy/content-type

Validate that the server support the Content-type header to declare the media type of the request body

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Issue an HTTP POST request associated with an unsupported media type, i.e. text/plain.

    +
    3. +

  3. Validate the response using /conf/dru/deploy/unsupported-content-type

    +
    4. +
+ + + + /conf/dru/deploy/unsupported-content-typetarget/req/deploy-replace-undeploy/deploy/unsupported-content-type

Validate that the server returns a 415 status code with a relevant exception

+

  1. Validate that a document was returned with an HTTP status code of 415.

    +
    2. +

  2. Validate that the document in the response body is conform to the exception.yaml schema.

    +
    3. +

  3. Validate that the type of the exception is “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/unsupported-media-type”.

    +
    4. +
+ + + + + +Replace operation + /conf/dru/replace/put-optarget/req/deploy-replace-undeploy/replace/put-op

Validate that the server supports HTTP PUT operation at the path /processes

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is not an existing process id, i.e. not-existing-process.

    +
    3. +

  3. Issue an HTTP PUT request for each path.

    +
    4. +

  4. Validate that the response header does not contain 405 Method not allowed.

    +
    5. +
+ + + + /conf/dru/replace/content-typetarget/req/deploy-replace-undeploy/replace/content-type

Validate that the server supports the Content-type header to declare the media type of the request body

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is a mutable process id.

    +
    3. +

  3. Issue an HTTP PUT request with an unsupported media type, i.e. text/plain, on each path.

    +
    4. +

  4. Validate the response using /conf/dru/deploy/unsupported-content-type

    +
    5. +
+ + + + + +Undeploy operation + /conf/dru/undeploy/delete-optarget/req/deploy-replace-undeploy/undeploy/delete-op

Validate that the server supports HTTP DELETE operation at the path /processes/{processId}

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is not an existing process id, i.e. not-existing-process.

    +
    3. +

  3. Issue an HTTP DELETE request for each path.

    +
    4. +

  4. Validate that the response header does not contain 405 Method not allowed.

    +
    5. +
+ + + + /conf/dru/undeploy/responsetarget/req/deploy-replace-undeploy/undeploy/response

Validate that the server returns a 204 status code when removing a mutable process

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is a mutable process id.

    +
    3. +

  3. Issue an HTTP DELETE request on one path.

    +
    4. +

  4. Validate that no content was returned with an HTTP status code of 204.

    +
    5. +
+ + + + /conf/dru/undeploy/response-immutabletarget/req/deploy-replace-undeploy/deploy/response-immutable

Validate that the server returns a 403 status code when removing an immutable process

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is not a mutable process id.

    +
    3. +

  3. Issue an HTTP DELETE request on each path.

    +
    4. +

  4. Validate the response contains a document content, and was returned with an HTTP status code of 403

    +
    5. +

  5. Validate the document is conform to the exception.yaml schema.

    +
    6. +

  6. Validate the type of the exception is “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/immutable-process”.

    +
    7. +
+ + + + + + +Conformance Class OGC Application Package + +OGC Application Packagehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/ogcapppkghttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/ogcapppkgTarget TypeWeb API /conf/ogcapppkg/deploy/body /conf/ogcapppkg/deploy/response /conf/ogcapppkg/deploy/response-success /conf/ogcapppkg/deploy/response-duplicate /conf/ogcapppkg/replace/body /conf/ogcapppkg/replace/response + + + + +Deploy operation + /conf/ogcapppkg/deploy/bodytarget/req/ogcapppkg/deploy/body

Validate that the server supports OGC Application Package encoding

+

  1. Retrieve all links from the landing page with “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” and /processes

    +
    2. +

  2. Issue an HTTP POST request using the content type “application/ogcapppkg+json” with as body a default OGC Application Package or the application package as reference, if any, on one path

    +
    3. +

  3. Validate the response with /conf/ogcapppkg/deploy/response

    +
    4. +

  4. Send the same POST request again

    +
    5. +

  5. Validate the response with /conf/ogcapppkg/deploy/response-duplicate

    +
    6. +
+ + + + /conf/ogcapppkg/deploy/responsetarget/req/deploy-replace-undeploy/deploy/response-success

Validate that the server returns HTTP Status code 201 or 202

+

  1. Validate that a document is returned and the status code is 201 or 202

    +
    2. +

  2. If status code was 201, validate the document using /conf/ogcapppkg/deploy/response-success

    +
    3. +
+ + + + /conf/ogcapppkg/deploy/response-successtarget/req/deploy-replace-undeploy/deploy/response-success

Validate that the server returns a Location header and a process summary

+

  1. Validate the Location header contains a URI of the deployed process.

    +
    2. +

  2. Validate the document conforms to the processSummary.yaml schema.

    +
    3. +
+ + + + /conf/ogcapppkg/deploy/response-duplicatetarget/req/deploy-replace-undeploy/deploy/response-duplicate

Validate that the server return HTTP Status code 409

+

  1. Validate that the response contains a document content was returned with an HTTP status code of 409

    +
    2. +

  2. Validate that the document is conform to the JSON Schema: exception.yaml

    +
    3. +

  3. Validate that the type of the exception is “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/duplicated-process”.

    +
    4. +
+ + + + + +Replace operation + /conf/ogcapppkg/replace/bodytarget/req/ogcapppkg/replace/body

Validate that the server supports OGC Application Package encoding

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is the process id retrieved from /conf/ogcapppkg/deploy/response-success.

    +
    3. +

  3. Issue an HTTP PUT request using the media type “application/ogcapppkg+json” with as body a default OGC Application Package or the application package URL, if any, for each path

    +
    4. +

  4. Validate the response with /conf/ogcapppkg/replace/response

    +
    5. +
+ + + + /conf/ogcapppkg/replace/responsetarget/req/deploy-replace-undeploy/response-success

Validate that the server returns HTTP Status code 200, 202 or 204

+

  1. Validate that the status code is 200, 202 or 204.

    +
    2. +
+ + + + + + +Conformance Class Docker + +Dockerhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/dockerhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/dockerTarget TypeWeb API /conf/docker/deploy/body /conf/docker/replace/body + + + + +Deploy operation + /conf/docker/deploy/bodytarget/rec/deploy-replace-undeploy/deploy/body-docker

Validate that the server supports deploy operation using a Docker image as execution unit

+

  1. Retrieve all links from the landing page with “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” and /processes

    +
    2. +

  2. Issue an HTTP POST request using the media type “application/ogcapppkg+json” with as body a default OGC Application Package

    +
    3. +

  3. Validate the response with /conf/ogcapppkg/deploy/response

    +
    4. +

  4. Send the same POST request again

    +
    5. +

  5. Validate the response with /conf/ogcapppkg/deploy/response-duplicate

    +
    6. +
+ + + + + +Replace operation + /conf/docker/replace/bodytarget/req/docker/replace/body

Validate that the server support replace operation using a Docker image as execution unit

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is the process id retrieved from /conf/ogcapppkg/deploy/response-success.

    +
    3. +

  3. Send a PUT request for one path using the media type “application/ogcapppkg+json” with as body a default OGC Application Package

    +
    4. +

  4. Validate the response with /conf/ogcapppkg/replace/response

    +
    5. +
+ + + + + + +Conformance Class CWL + +Common Workflow Languagehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/cwlhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/cwlTarget TypeWeb API /conf/cwl/deploy/body /conf/cwl/replace/body + + + + +Deploy operation + /conf/cwl/deploy/bodytarget/req/cwl/deploy/body

Validate that the server support deploy operation using the Common Workflow Language encoding

+

  1. Retrieve all links from the landing page with “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” and /processes

    +
    2. +

  2. Issue an HTTP POST request using the media type “application/cwl” and the application package content

    +
    3. +

  3. Validate the response with /conf/ogcapppkg/deploy/response

    +
    4. +

  4. Send the same POST request again

    +
    5. +

  5. Validate the response with /conf/ogcapppkg/deploy/response-duplicate

    +
    6. +
+ + + + + +Replace operation + /conf/cwl/replace/bodytarget/req/cwl/replace/body

Validate that the server support replace operation using the Common Workflow Language encoding

+

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    +
    2. +

  2. Append /{processId} to each path, where {processId} is a mutable process id.

    +
    3. +

  3. Send a PUT request for one path using the media type “application/cwl” and the application package content

    +
    4. +

  4. Validate the response with /conf/ogcapppkg/replace/response

    +
    5. +
+ + + + + +Revision History + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DateReleaseEditorPrimary clauses modifiedDescription
2020-05-19NonePanagiotis (Peter) A. VretanosallInitial check in of draft transactions extension.
2020-06-23NonePanagiotis (Peter) A. VretanosallAdd initial draft of an example Open API document
2021-10-18NonePanagiotis (Peter) A. VretanosallRename transaction directory to deploy_replace_undeploy.
2022-10-04NoneGérald FenoyallUse relative path to exception and problem+json
2022-10-05NoneGérald FenoyallUpdate the Deploy, Replace, Undeploy extension
2022-12-12NoneGérald FenoyallChange the status code to be returned (immutable)
2023-02-20NonePanagiotis (Peter) A. VretanosallRealign abstract test with requirements.
2023-05-30NoneGérald FenoyallUpdate status code and schema.
2023-10-16NoneGérald FenoyallAdd content to the Abstract Test Suite
2023-11-28NoneGérald FenoyallUpdate test for validating support of a given HTTP method
2023-12-06NoneGérald FenoyallAbstract Test Suite Updates
2023-12-07NoneGérald FenoyallFix mixed status code and value in security consideration
2023-12-08NoneGérald FenoyallAdd requirements for managing docker image as execution unit
2024-04-26NoneGérald FenoyallAdd section for retrieving formal description of a mutable process
+ +Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

+ + 2024-08-28 + +OGC API + + +Processes + + +Part 1: Core + + +OGC API — Processes — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 + https://docs.ogc.org/is/18-062r2/18-062r2.html + 18-062r2 + + 2021-12-20 + + + + + + Benjamin Pross + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + +Open Geospatial Consortium + + + + 2 + en + + The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. + +By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. + +The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. + +The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. + + + + 2024-08-28 + +OGC API + + +Features + + +Part 1: Core + + +OGC API — Features — Part 1: Core + + http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0 + https://docs.ogc.org/is/17-069r3/17-069r3.html + 17-069r3 + + 2019-10-07 + + + + + + Clemens Portele + + + + + + + + Panagiotis (Peter) A. Vretanos + + + + + + + + Charles Heazel + + + + + + + +Open Geospatial Consortium + + + + 3 + en + + OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. + +The OGC API family of standards is organized by resource type. This standard specifies the fundamental API building blocks for interacting with features. The spatial data community uses the term ‘feature’ for things in the real world that are of interest. + + + +Bibliography + OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: +. + OpenAPI Specification 3.0.2 + 3.0.2 + + Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. + [2] + + OpenEO: OpenEO Developers API Reference / Process Graphs. + [3] + + + + + + diff --git a/extensions/job_management/standard/README.md b/extensions/job_management/standard/README.md new file mode 100644 index 00000000..58b7db93 --- /dev/null +++ b/extensions/job_management/standard/README.md @@ -0,0 +1 @@ +This folder contains the text for part 3 of the OGC API Features standard. diff --git a/extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc b/extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc new file mode 100644 index 00000000..d6aaf738 --- /dev/null +++ b/extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc @@ -0,0 +1,14 @@ +[[ats_dru]] +[conformance_class] +.Job Management +==== +[%metadata] +identifier:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management +subject:: <> +classification:: Target Type:Web API +conformance-test:: /conf/dru/deploy/post-op +==== + +==== Create operation + +include::jm/create/ATS_post-op.adoc[] diff --git a/extensions/job_management/standard/abstract_tests/README.md b/extensions/job_management/standard/abstract_tests/README.md new file mode 100644 index 00000000..ee9b6e6d --- /dev/null +++ b/extensions/job_management/standard/abstract_tests/README.md @@ -0,0 +1,27 @@ +This folder contains the Abstract Test Suite. + +Each file describes a single test. The naming convention for these files is: + +"cc/TESTn.adoc" where "cc" corresponds to the identifier for the requirements class and "n" corresponds to the test number. Numbers should have preceeding zeros appropriate for the total number of tests in the conformance class (e.g., the first test could be TEST001 if less than 1000 tests are anticipated). + +The test is expressed according to this pattern: + +```` +===== Test case title + +(( additional discussion, if needed )) + +====== a) Test Purpose: +(( description )) + +====== b) Pre-conditions: +* (( list all preconditions )) + +====== c) Test Method: +* (( steps to execute and assertions to test )) + +====== d) References: +* <> +```` + +NOTE: for each test, there must be one or more requirements in the "requirements" folder. diff --git a/extensions/job_management/standard/abstract_tests/cc/TEST001.adoc b/extensions/job_management/standard/abstract_tests/cc/TEST001.adoc new file mode 100644 index 00000000..1c3db3b0 --- /dev/null +++ b/extensions/job_management/standard/abstract_tests/cc/TEST001.adoc @@ -0,0 +1,15 @@ +===== Test case title + +(( additional discussion, if needed )) + +====== a) Test Purpose: +(( description )) + +====== b) Pre-conditions: +* (( list all preconditions )) + +====== c) Test Method: +* (( steps to execute and assertions to test )) + +====== d) References: +* <> diff --git a/extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc b/extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc new file mode 100644 index 00000000..a4e1809b --- /dev/null +++ b/extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc @@ -0,0 +1,19 @@ +[[ats_dru_deploy_post-op]] + +[abstract_test] +==== +[%metadata] +identifier:: /conf/jm/create/post-op +target:: <> +test-purpose:: Validate that the server support HTTP POST operation at the path /jobs/ +test-method:: ++ +-- +1. Construct a path for each "rel=http://www.opengis.net/def/rel/ogc/1.0/job-list" link on the landing page as well as for the {root}/jobs path. + +2. Issue an HTTP POST request for each path. + +3. Validate that the response header does not contain `405 Method not allowed` +-- +==== + diff --git a/extensions/job_management/standard/figures/README.md b/extensions/job_management/standard/figures/README.md new file mode 100644 index 00000000..e5d667f5 --- /dev/null +++ b/extensions/job_management/standard/figures/README.md @@ -0,0 +1,5 @@ +Figures go here. + +Each figure is a separate file with the naming convention: + +"PTm_FIGn.xxx" where "m" is a number with leading zeroes appropriate for the total number of parts, "n" is a number with leading zeroes appropriate for the total number of figures and "xxx" is the appropriate extension for the file type. \ No newline at end of file diff --git a/extensions/job_management/standard/images/README.md b/extensions/job_management/standard/images/README.md new file mode 100644 index 00000000..c8f34049 --- /dev/null +++ b/extensions/job_management/standard/images/README.md @@ -0,0 +1,9 @@ +Image files for graphics go here. + +Each graphic is a separate file with the naming convention: + +"FIGn.xxx" where "n" is a number with leading zeroes appropriate for the total number of figures and "xxx" is the appropriate extension for the file type. + +or, for other graphics not associated with figures: + +"GRPn.xxx" where "n" is a sequential number with leading zeroes appropriate for the total number of graphics and "xxx" is the appropriate extension for the file type. diff --git a/extensions/job_management/standard/recommendations/README.md b/extensions/job_management/standard/recommendations/README.md new file mode 100644 index 00000000..a9a6cb66 --- /dev/null +++ b/extensions/job_management/standard/recommendations/README.md @@ -0,0 +1,2 @@ +OGC API - Processes - Part 2: Transactions recommendations. + diff --git a/extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc b/extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc new file mode 100644 index 00000000..0c57ebb4 --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc @@ -0,0 +1,7 @@ +[[per_deploy-replace-undeploy_additional-status-codes]] +[permission] +==== +[%metadata] +label:: /per/core/additional-status-codes +part:: Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in <>. +==== diff --git a/extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc b/extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc new file mode 100644 index 00000000..bda2f16c --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc @@ -0,0 +1,7 @@ +[[per_job-management_create_body]] +[permission] +==== +[%metadata] +label:: /per/job-management/create/body +part:: A server MAY support any encoding in the body of a HTTP POST operation. +==== diff --git a/extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc b/extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc new file mode 100644 index 00000000..fc7a9df8 --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc @@ -0,0 +1,8 @@ +[[rec_job-management_create_body-ogcapi-processes]] +[recommendation] +==== +[%metadata] +label:: /rec/job-management/create/body-ogcapi-processes + +part:: If the job can be encoded as an <>, implementation SHOULD consider supporting the <> encoding. +==== diff --git a/extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc b/extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc new file mode 100644 index 00000000..bc924f5c --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc @@ -0,0 +1,8 @@ +[[rec_job-management_create_body-openeo]] +[recommendation] +==== +[%metadata] +label:: /rec/job-management/create/body-openeo + +part:: If the job can be encoded as an <>, implementation SHOULD consider supporting the <> encoding. +==== diff --git a/extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc b/extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc new file mode 100644 index 00000000..8ff745f3 --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc @@ -0,0 +1,9 @@ +[[rec_deploy-replace-undeploy_package_response-cwl]] +[recommendation] +==== +[%metadata] +label:: /rec/deploy-replace-undeploy/package/response-cwl + +part:: If a process deployed as a <>, implementations SHOULD consider supporting the <> encoding. + +==== diff --git a/extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc b/extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc new file mode 100644 index 00000000..0de7b211 --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc @@ -0,0 +1,8 @@ +[[rec_deploy-replace-undeploy_package_response-ogcapppkg]] +[recommendation] +==== +[%metadata] +label:: /rec/deploy-replace-undeploy/package/response-ogcapppkg + +part:: If a process was deployed as an <>, implementations SHOULD consider supporting the <> encoding. +==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc b/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc new file mode 100644 index 00000000..e380f46e --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc @@ -0,0 +1,7 @@ +[[per_job-management_update_body]] +[permission] +==== +[%metadata] +label:: /per/job-management/update/body +part:: A server MAY support any encoding in the body of a HTTP PUT operation. +==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc new file mode 100644 index 00000000..8972765a --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc @@ -0,0 +1,9 @@ +[[rec_deploy-replace-undeploy_replace_body-cwl]] +[recommendation] +==== +[%metadata] +label:: /rec/deploy-replace-undeploy/replace/body-cwl + +part:: If a process can be encoded for the intended use in <>, implementations SHOULD consider supporting the <> encoding for describing the replacement process. + +==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc new file mode 100644 index 00000000..31f42316 --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc @@ -0,0 +1,9 @@ +[[rec_job-management_update-ogcapi-processes]] +[recommendation] +==== +[%metadata] +label:: /rec/job-management/update/body-ogcapi-processes + +part:: If a job can be created from an rc_ogcapi-processes,OGC API - Processes - Workflow Execute Request>>, implementations SHOULD consider supporting the <> encoding. + +==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc new file mode 100644 index 00000000..317dbabc --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc @@ -0,0 +1,9 @@ +[[rec_job-management_update-openeo]] +[recommendation] +==== +[%metadata] +label:: /rec/job-management/update/body-openeo + +part:: If a job can be created from an <>, implementations SHOULD consider supporting the <> encoding. + +==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc new file mode 100644 index 00000000..c5b04bd4 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc @@ -0,0 +1,7 @@ +[[req_deploy-replace-undeploy_deploy_body]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/body +part:: The body of the POST request SHALL be in JSON format. +==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc new file mode 100644 index 00000000..0282edc2 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc @@ -0,0 +1,7 @@ +[[req_job-management_create_content-type]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/content-type +part:: The `Content-Type` https://tools.ietf.org/html/rfc2616#section-14.17[header] SHALL be used to declare the media type of the request. +==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc new file mode 100644 index 00000000..dc8dca0e --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc @@ -0,0 +1,7 @@ +[[req_job-management_create_post-op]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/post-op +part:: The server SHALL support the HTTP POST operation at the path `/jobs`. +==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc new file mode 100644 index 00000000..8206f860 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc @@ -0,0 +1,8 @@ +[[req_job-management_create_response-body]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/response-body +part:: The response SHALL include a body that contains a status information of the created job conforms to the https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/statusInfo.yaml[statusInfo.yaml] schema. +part:: The response SHALL contains a `pending` status code and the `jobId` property that contains the job identifier. +==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc new file mode 100644 index 00000000..0f250b65 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc @@ -0,0 +1,7 @@ +[[req_job-management_create_response-jobid]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/response-jobid +part:: If the operation completes, the server SHALL generate a job identifier (i.e. `{jobId}`) for the created job. +==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc new file mode 100644 index 00000000..026c1a02 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc @@ -0,0 +1,8 @@ +[[req_job-management_create_response_success]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/response-success +part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code `201`. +part:: A response with HTTP status code `201` SHALL include a `Location` header with the URI of the deployed processes (path: `/jobs/{jobId}`). +==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc new file mode 100644 index 00000000..4a433a58 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc @@ -0,0 +1,11 @@ +[[req_job-management_create_unsupported-media-type]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/unsupported-media-type + +part:: If the server does not support the Content-Type header associated with the request body, the code of the response SHALL be `415 Unsupported Media Type`. +part:: The content of that response SHALL be based upon the OpenAPI +3.0 schema https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/exception.yaml[exception.yaml]. +part:: The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-4/1.0/unsupported-media-type”. +==== diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc new file mode 100644 index 00000000..10e72e92 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc @@ -0,0 +1,9 @@ +[[req_deploy-replace-undeploy_package_get-op]] +[requirement] +==== +[%metadata] +label:: /req/deploy-replace-undeploy/package/get-op +part:: For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path `/processes/{processId}/package`. +part:: The parameter `processId` is each `id` property in the process collection response (JSONPath: `$.processes[*].id`). + +==== diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc new file mode 100644 index 00000000..be69c245 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc @@ -0,0 +1,7 @@ +[[req_deploy-replace-undeploy_package_response-body]] +[requirement] +==== +[%metadata] +label:: /req/deploy-replace-undeploy/package/response-body +part:: A response with HTTP status code `200` SHALL include a body that contains the request body used to create or update the job. +==== diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc new file mode 100644 index 00000000..feaa48a2 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc @@ -0,0 +1,7 @@ +[[req_deploy-replace-undeploy_package_response-success]] +[requirement] +==== +[%metadata] +label:: /req/deploy-replace-undeploy/package/response-success +part:: A successful access to the resource SHALL be reported as a response with a HTTP status code `200`. +==== diff --git a/extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc b/extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc new file mode 100644 index 00000000..14d351e4 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc @@ -0,0 +1,8 @@ +[[req_job-management_start_response]] +[requirement] +==== +[%metadata] +label:: /req/job-management/start/response +part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. +part:: A response SHALL be a document that conforms to statusInfo.yaml. +==== diff --git a/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc b/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc new file mode 100644 index 00000000..e00e9e0a --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc @@ -0,0 +1,8 @@ +[[req_job-management_start_start-op]] +[requirement] +==== +[%metadata] +label:: /req/job-management/start/start-op +part:: For every created jobs (path: `/jobs/{jobId}/results`), the server SHALL support the HTTP POST operation. +part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc new file mode 100644 index 00000000..6ae70501 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc @@ -0,0 +1,7 @@ +[[req_job-management_update_body]] +[requirement] +==== +[%metadata] +label:: /req/job-management/update/body* +part:: The body of a PUT request SHALL be in JSON format. +==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc new file mode 100644 index 00000000..3ceb094c --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc @@ -0,0 +1,7 @@ +[[req_job-management_update_content-type]] +[requirement] +==== +[%metadata] +label:: /req/job-management/update/content-type +part:: As per <> (https://tools.ietf.org/html/rfc2616#section-14.17) the 'Content-Type' header SHALL be used to indicate the media type of a request body containing the description of the replacement processes. +==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_put-op.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_put-op.adoc new file mode 100644 index 00000000..38f84197 --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_put-op.adoc @@ -0,0 +1,8 @@ +[[req_job-management_update_put-op]] +[requirement] +==== +[%metadata] +label:: /req/job-management/update/put-op +part:: For every created jobs (path '/jobs/{jobId}'), the server SHALL support the HTTP PUT operation. +part:: The parameter 'jobId' is each 'jobID' property in the jobs list response (JSONPath: `$.jobs[*].jobID`). +==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc new file mode 100644 index 00000000..8bf0901c --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc @@ -0,0 +1,8 @@ +[[req_job-management_update_response]] +[requirement] +==== +[%metadata] +label:: /req/job-management/update/response +part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code `200` or `204`. +part:: If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code `202`. +==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc new file mode 100644 index 00000000..286bbc0d --- /dev/null +++ b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc @@ -0,0 +1,7 @@ +[[req_ogcappkg_body]] +[requirement] +==== +[%metadata] +label:: /req/ogcapppkg/body +part:: The media type `application/ogcapppkg+json` SHALL be used to indicate that request body contains a processes description encoded as an <>. +==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc new file mode 100644 index 00000000..d483da05 --- /dev/null +++ b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc @@ -0,0 +1,7 @@ +[[req_ogcapppkg_process-description]] +[requirement] +==== +[%metadata] +label:: /req/ogcapppkg/process-description +part:: The value of the processDescription property SHALL be based upon the OpenAPI schema https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/process.yaml[process.yaml]. +==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc new file mode 100644 index 00000000..04c0da48 --- /dev/null +++ b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc @@ -0,0 +1,7 @@ +[[req_ogcapppkg_profile-docker]] +[requirement] +==== +[%metadata] +label:: /req/ogcapppkg/profile-docker +part:: If the execution unit is a Docker image, the value of the `deploymentProfile` property shall be `http://www.opengis.net/profiles/eoc/dockerizedApplication`. +==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc new file mode 100644 index 00000000..4ca75722 --- /dev/null +++ b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc @@ -0,0 +1,7 @@ +[[req_ogcapi-processes_schema]] +[requirement] +==== +[%metadata] +label:: /req/ogcapi-processes/schema +part:: An `OGC API - Processes` document SHALL be based upon the JSON schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflow.yaml]. +==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc new file mode 100644 index 00000000..01b6d117 --- /dev/null +++ b/extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc @@ -0,0 +1,8 @@ +[[req_ogcapi-processes_create_body]] +[requirement] +==== +[%metadata] +label:: /req/ogcapi-processes/create/body +part:: The body of the POST request SHALL be based upon the OpenAPI 3.0 schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflows.yaml] +part:: The media type `application/json` SHALL be used to indicate that request body contains a processes description encoded as an <>. +==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc new file mode 100644 index 00000000..5a0eeb21 --- /dev/null +++ b/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc @@ -0,0 +1,7 @@ +[[req_ogcapi-processes_definition_response-body]] +[requirement] +==== +[%metadata] +label:: /req/ogcapi-processes/definition/response-body +part:: A response with HTTP status code `200` SHALL include a body that contains the <> to use to deploy the process. +==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc new file mode 100644 index 00000000..77285285 --- /dev/null +++ b/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc @@ -0,0 +1,7 @@ +[[req_ogcapi-processes_update__body]] +[requirement] +==== +[%metadata] +label:: /req/ogcapi-processes/update/body +part:: The media type `application/ogcapi-processes+json` SHALL be used to indicate that request body contains a job encoded as an <>. +==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/REQ_body.adoc new file mode 100644 index 00000000..286bbc0d --- /dev/null +++ b/extensions/job_management/standard/requirements/openeo/REQ_body.adoc @@ -0,0 +1,7 @@ +[[req_ogcappkg_body]] +[requirement] +==== +[%metadata] +label:: /req/ogcapppkg/body +part:: The media type `application/ogcapppkg+json` SHALL be used to indicate that request body contains a processes description encoded as an <>. +==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc b/extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc new file mode 100644 index 00000000..d483da05 --- /dev/null +++ b/extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc @@ -0,0 +1,7 @@ +[[req_ogcapppkg_process-description]] +[requirement] +==== +[%metadata] +label:: /req/ogcapppkg/process-description +part:: The value of the processDescription property SHALL be based upon the OpenAPI schema https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/process.yaml[process.yaml]. +==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc b/extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc new file mode 100644 index 00000000..04c0da48 --- /dev/null +++ b/extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc @@ -0,0 +1,7 @@ +[[req_ogcapppkg_profile-docker]] +[requirement] +==== +[%metadata] +label:: /req/ogcapppkg/profile-docker +part:: If the execution unit is a Docker image, the value of the `deploymentProfile` property shall be `http://www.opengis.net/profiles/eoc/dockerizedApplication`. +==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_schema.adoc b/extensions/job_management/standard/requirements/openeo/REQ_schema.adoc new file mode 100644 index 00000000..c458ca50 --- /dev/null +++ b/extensions/job_management/standard/requirements/openeo/REQ_schema.adoc @@ -0,0 +1,7 @@ +[[req_openeo_schema]] +[requirement] +==== +[%metadata] +label:: /req/openeo/schema +part:: An `OpenEO Process Graph` document SHALL be based upon the JSON schema https://raw.githubusercontent.com/Open-EO/openeo-processes/master/meta/subtype-schemas.json#/definitions/process-graph. +==== diff --git a/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc new file mode 100644 index 00000000..21358437 --- /dev/null +++ b/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc @@ -0,0 +1,7 @@ +[[req_openeo_create_body]] +[requirement] +==== +[%metadata] +label:: /req/openeo/create/body +part:: The media type `application/openeo+json` SHALL be used to indicate that request body contains a processes description encoded as an <>. +==== diff --git a/extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc new file mode 100644 index 00000000..7dfdcdd9 --- /dev/null +++ b/extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc @@ -0,0 +1,7 @@ +[[req_openeo_definition_response-body]] +[requirement] +==== +[%metadata] +label:: /req/openeo/definition/response-body +part:: A response with HTTP status code `200` SHALL include a body that contains the <> to use to deploy the process. +==== diff --git a/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc new file mode 100644 index 00000000..c8fbad9d --- /dev/null +++ b/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc @@ -0,0 +1,7 @@ +[[req_openeo_update__body]] +[requirement] +==== +[%metadata] +label:: /req/openeo/update/body +part:: The media type `application/openeo+json` SHALL be used to indicate that request body contains a job encoded as an <>. +==== diff --git a/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc new file mode 100644 index 00000000..3d515131 --- /dev/null +++ b/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc @@ -0,0 +1,8 @@ +[[req_job-provenance_inputs_get-op]] +[requirement] +==== +[%metadata] +label:: /req/provenance/inputs/get-op +part:: For every created jobs (path: `/jobs/{jobId}/inputs`), the server SHALL support the HTTP GET operation. +part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +==== diff --git a/extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc b/extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc new file mode 100644 index 00000000..4b0307e7 --- /dev/null +++ b/extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc @@ -0,0 +1,8 @@ +[[req_provenance_inputs_response]] +[requirement] +==== +[%metadata] +label:: /req/provenance/inputs/response +part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. +part:: The response SHALL contains a JSON document that conforms to the schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-job-management/inputs.yaml[inputs.yaml]. +==== diff --git a/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc new file mode 100644 index 00000000..4f580354 --- /dev/null +++ b/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc @@ -0,0 +1,8 @@ +[[req_job-provenance_outputs_get-op]] +[requirement] +==== +[%metadata] +label:: /req/provenance/outputs/get-op +part:: For every created jobs (path: `/jobs/{jobId}/outputs`), the server SHALL support the HTTP GET operation. +part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +==== diff --git a/extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc b/extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc new file mode 100644 index 00000000..a6ac8568 --- /dev/null +++ b/extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc @@ -0,0 +1,8 @@ +[[req_provenance_outputs_response]] +[requirement] +==== +[%metadata] +label:: /req/provenance/outputs/response +part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. +part:: The response SHALL contains a JSON document that conforms to the schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-job-management/outputs.yaml[outputs.yaml]. +==== diff --git a/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc new file mode 100644 index 00000000..6e5d2770 --- /dev/null +++ b/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc @@ -0,0 +1,8 @@ +[[req_job-provenance_run_get-op]] +[requirement] +==== +[%metadata] +label:: /req/provenance/run/get-op +part:: For every created jobs (path: `/jobs/{jobId}/run`), the server SHALL support the HTTP GET operation. +part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +==== diff --git a/extensions/job_management/standard/requirements/requirements_class_job-management.adoc b/extensions/job_management/standard/requirements/requirements_class_job-management.adoc new file mode 100644 index 00000000..f27ba10e --- /dev/null +++ b/extensions/job_management/standard/requirements/requirements_class_job-management.adoc @@ -0,0 +1,10 @@ +[[rc_job-mangement]] +[requirements_class] +==== +[%metadata] +label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-management +obligation:: requirement +subject:: Web API +inherit:: <> +inherit:: <> +==== diff --git a/extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc b/extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc new file mode 100644 index 00000000..630cb76a --- /dev/null +++ b/extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc @@ -0,0 +1,10 @@ +[[rc_ogcapi-processes]] +[requirements_class] +==== +[%metadata] +label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/ogcapi-processes +obligation:: requirement +subject:: Web API +inherit:: <> +inherit:: <> +==== diff --git a/extensions/job_management/standard/requirements/requirements_class_openeo.adoc b/extensions/job_management/standard/requirements/requirements_class_openeo.adoc new file mode 100644 index 00000000..4677ed90 --- /dev/null +++ b/extensions/job_management/standard/requirements/requirements_class_openeo.adoc @@ -0,0 +1,10 @@ +[[rc_openeo]] +[requirements_class] +==== +[%metadata] +label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeo +obligation:: requirement +subject:: Web API +inherit:: <> +inherit:: <> +==== diff --git a/extensions/job_management/standard/requirements/requirements_class_provenance.adoc b/extensions/job_management/standard/requirements/requirements_class_provenance.adoc new file mode 100644 index 00000000..491d6644 --- /dev/null +++ b/extensions/job_management/standard/requirements/requirements_class_provenance.adoc @@ -0,0 +1,9 @@ +[[rc_cwl]] +[requirements_class] +==== +[%metadata] +label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/provenance +obligation:: requirement +subject:: Web API +inherit:: <> +==== diff --git a/extensions/job_management/standard/requirements/requirements_class_quotation.adoc b/extensions/job_management/standard/requirements/requirements_class_quotation.adoc new file mode 100644 index 00000000..bb06ba07 --- /dev/null +++ b/extensions/job_management/standard/requirements/requirements_class_quotation.adoc @@ -0,0 +1,11 @@ +[[rc_quotation]] +[requirements_class] +==== +[%metadata] +label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/quotation +obligation:: requirement +subject:: Web API +inherit:: <> +inherit:: <> +inherit:: <> +==== diff --git a/extensions/job_management/standard/sections/annex_ats.adoc b/extensions/job_management/standard/sections/annex_ats.adoc new file mode 100644 index 00000000..1a1e8744 --- /dev/null +++ b/extensions/job_management/standard/sections/annex_ats.adoc @@ -0,0 +1,15 @@ +[[ats]] +[appendix,obligation="normative"] +== Abstract Test Suite + +=== Introduction + +OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested. + +The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes "basic" and "bearer", API keys, and OAuth2 flow "authorizationCode". + + +=== Conformance Class Deploy, Replace, Undeploy + +include::../abstract_tests/ATS_class_jm.adoc[] + diff --git a/extensions/job_management/standard/sections/annex_bibliography.adoc b/extensions/job_management/standard/sections/annex_bibliography.adoc new file mode 100644 index 00000000..351430db --- /dev/null +++ b/extensions/job_management/standard/sections/annex_bibliography.adoc @@ -0,0 +1,29 @@ +[bibliography] +[[Bibliography]] +== Bibliography + +//// +The TC has approved Springer LNCS as the official document citation type. + +Springer LNCS is widely used in technical and computer science journals and other publications + +* For citations in the text please use square brackets and consecutive numbers: [1], [2], [3] + +– Actual References: + +[n] Journal: Author Surname, A.: Title. Publication Title. Volume number, Issue number, Pages Used (Year Published) + +[n] Web: Author Surname, A.: Title, http://Website-Url + +* [[[OGC2015,OGCTB12]]], _OGC: OGC Testbed 12 Annex B: Architecture_ (2015). + +//// + +// * [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2016): Common Workflow Language, v1.0. Specification, Common Workflow Language working group. https://w3id.org/cwl/v1.0/ https://doi.org/10.6084/m9.figshare.3115156.v2 + +* [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. https://w3id.org/cwl/ + +* [[[OpenEO_Process_Graphs,2]]], OpenEO: OpenEO Developers API Reference / Process Graphs. https://openeo.org/documentation/1.0/developers/api/reference.html#section/Processes/Process-Graphs + +* [[[OpenAPI-Spec,OpenAPI Specification 3.0.2]]] OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: +https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md. diff --git a/extensions/job_management/standard/sections/annex_history.adoc b/extensions/job_management/standard/sections/annex_history.adoc new file mode 100644 index 00000000..9771e1ec --- /dev/null +++ b/extensions/job_management/standard/sections/annex_history.adoc @@ -0,0 +1,8 @@ +[appendix] +== Revision History + +[cols="12,18,12,12,46",options="header,unnumbered"] +|=== +|Date |Release |Editor | Primary clauses modified |Description +|2024-08-22 |None |Gérald Fenoy |all |Boostraping the document +|=== diff --git a/extensions/job_management/standard/sections/clause_0_front_material.adoc b/extensions/job_management/standard/sections/clause_0_front_material.adoc new file mode 100644 index 00000000..3d0ff1bc --- /dev/null +++ b/extensions/job_management/standard/sections/clause_0_front_material.adoc @@ -0,0 +1,26 @@ + +[abstract] +== Abstract + +OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The <> is used to define the API building blocks. + +The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard. + +The OGC API - Processes - Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [<>] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard. + +The OGC API - Processes - Part 3: Workflows draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [<>] with the ability to ... + +The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [<>] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable. + +CAUTION: This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion. + +== Submitters + +All questions regarding this submission should be directed to the editors or the submitters: + +[cols="2",options="header,unnumbered"] +|=== +| Name | Affiliation +| Gérald Fenoy _(editor)_ | GeoLabs +|=== + diff --git a/extensions/job_management/standard/sections/clause_10_provenance.adoc b/extensions/job_management/standard/sections/clause_10_provenance.adoc new file mode 100644 index 00000000..ca2e76c5 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_10_provenance.adoc @@ -0,0 +1,43 @@ +== Requirements Class "Provenance" + +[[provenance-overview]] +=== Overview + +This requirements class defines how to allow client application accessing the provenance of a job run. + +include::../requirements/requirements_class_provenance.adoc[] + +=== Additional endpoints + +==== Inputs + +The server MUST provide an endpoint to retrieve the inputs of a job run. + +===== Operation + +include::../requirements/provenance/inputs/REQ_get-op.adoc[] + +===== Response + +include::../requirements/provenance/inputs/REQ_response.adoc[] + +==== Outputs + +The server MUST provide an endpoint to retrieve the outputs of a job run. + +===== Operation + +include::../requirements/provenance/outputs/REQ_get-op.adoc[] + +===== Response + +include::../requirements/provenance/outputs/REQ_response.adoc[] + +==== Run + +The server MUST provide an endpoint to retrieve the run of a job. + +===== Operation + +include::../requirements/provenance/run/REQ_get-op.adoc[] + diff --git a/extensions/job_management/standard/sections/clause_11_oas.adoc b/extensions/job_management/standard/sections/clause_11_oas.adoc new file mode 100644 index 00000000..45e1367d --- /dev/null +++ b/extensions/job_management/standard/sections/clause_11_oas.adoc @@ -0,0 +1,5 @@ + +[[oas]] +== OpenAPI 3.0 + +See <>, Clause 9. diff --git a/extensions/job_management/standard/sections/clause_12_media_types.adoc b/extensions/job_management/standard/sections/clause_12_media_types.adoc new file mode 100644 index 00000000..82e621ec --- /dev/null +++ b/extensions/job_management/standard/sections/clause_12_media_types.adoc @@ -0,0 +1,13 @@ +[[mediatypes]] +== Media Types + +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 + +Additional CWL media types that would typically be used in a server that supports CWL are: + +* application/cwl \ No newline at end of file diff --git a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc new file mode 100644 index 00000000..1207e44b --- /dev/null +++ b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc @@ -0,0 +1,119 @@ +== Security Considerations + +See <>, Clause 10.4. + +Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will - in almost all cases - restrict the access to these operations. + +Users making modifications to process resources need to: + +. Be authenticated, +. Have "modification privileges" on the processes offered through the API, +. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints. + +The API definition, as defined in Clause 7.3 from <>, must reflect this in the resource paths and their available methods. + +Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance: + +The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes - Part 2 (DRU) supports for each operation (or for all operations in the API implementation). + +A member "security" in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a "security" member for the individual operation. + +[#auth-example-1,reftext=`Example OpenAPI definition with security requirements`] +.Example OpenAPI definition with security requirements +==== +The following OpenAPI definition declares that the API accepts either api keys in an "X-API-Key" header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user. + +[source,JSON] +---- +{ + "openapi" : "3.0.3", + "info" : { + "title" : "My API", + "description" : "This API ...", + "version" : "1.0.0" + }, + "servers" : [ { + "url" : "https://example.com/api/v1" + } ], + "security" : [ { + "JWT" : [ ], + "api_key": [ ] + } ], + "paths" : { }, + "components" : { + "securitySchemes": { + "JWT" : { + "type" : "http", + "scheme" : "bearer", + "bearerFormat" : "JWT" + }, + "api_key" : { + "type": "apiKey", + "name": "X-API-Key", + "in": "header" + } + } + } +} +---- +==== + +If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error. + +In case the request does not include information to authenticate the user, the server will respond with a 401 response ("Unauthorized"). The response will include a "WWW-Authenticate" header with hints as to how authentication credentials are provided. + +[#auth-example-2,reftext=`Unauthorized request`] +.Unauthorized request + +---- +Client Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | ----------------------------------------------------------->| + | | + | HTTP/1.1 401 Unauthorized | + | Date: Mon, 23 May 2022 11:18:45 GMT | + | WWW-Authenticate: Bearer realm="my-realm" | + | WWW-Authenticate: ApiKey header="X-API-Key" | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 86 | + | | + | { | + | "status": 401, | + | "title": "Unauthorized", | + | "detail": "HTTP 401 Unauthorized" | + | } | + | <-----------------------------------------------------------| +---- + +NOTE: HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023) + +If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response ("Forbidden"). + +[#auth-example-3,reftext=`Forbidden request`] +.Forbidden request + +``` +Client Server + | | + | DELETE /processes/SampleProcess HTTP/1.1 | + | Host: example.com | + | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | + |------------------------------------------------------------------>| + | | + | HTTP/1.1 403 Forbidden | + | Date: Mon, 23 May 2022 11:18:55 GMT | + | Content-Type: application/problem+json | + | Vary: Accept | + | Content-Length: 80 | + | | + | { | + | "status" : 403, | + | "title" : "Forbidden", | + | "detail" : "HTTP 403 Forbidden" | + | } | + |<------------------------------------------------------------------| +``` + +However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response ("Not Found") to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation. \ No newline at end of file diff --git a/extensions/job_management/standard/sections/clause_1_scope.adoc b/extensions/job_management/standard/sections/clause_1_scope.adoc new file mode 100644 index 00000000..4678be08 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_1_scope.adoc @@ -0,0 +1,13 @@ +== Scope + +The OGC API - Processes - Part 4 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [<>] and defines the behavior of a server that +supports the ability to create jobs without implying the process execution starts right away. + +Specifically, the Processes Part 4 Standard specifies: + +* How to manage job. + +* How to handle provenenance information associated with a job. + + + diff --git a/extensions/job_management/standard/sections/clause_2_conformance.adoc b/extensions/job_management/standard/sections/clause_2_conformance.adoc new file mode 100644 index 00000000..ae9cc154 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_2_conformance.adoc @@ -0,0 +1,29 @@ + +== Conformance + +The OGC API - Processes - Part 4 Standard defines the following requirements classes. + +The main requirements class is: + +* <>. + +This class specifies requirements that any Web API implementing Processes Part 4 must conform with. + +The `Job Management` class does mandate a specific encoding and +format for the job definition. However, the Part 4 extension +defines the following conformance class: + +* <> + +The `OpenEO grap` class defines that jobs can be created from an OpenEO graph. + +The provenance information associated with a job is not mandated to be supported by the server. +A dedicated requirements class <> is defined for this feature. + +The standardization target for all Conformance class defined in this Standard is “Web API”. + +Conformance with this Standard shall be checked using all the relevant tests +specified in <> of this document. The framework, concepts, and +methodology for testing, and the criteria to be achieved to claim conformance +are specified in the OGC Compliance Testing Policies and Procedures and the +OGC Compliance Testing web site. diff --git a/extensions/job_management/standard/sections/clause_3_references.adoc b/extensions/job_management/standard/sections/clause_3_references.adoc new file mode 100644 index 00000000..d03081c4 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_3_references.adoc @@ -0,0 +1,13 @@ + +[bibliography] +== References + +* [[[OAProc-1,OGC 18-062]]] Pross, B.: OGC 18-062, *OGC API - Processes - Part 1: Core* + +* [[[OAProc-2,OGC 20-044]]] Pross, B.: OGC 18-062, *OGC API - Processes - Part 2: Deploy, Replace, Undeploy* + +* [[[OAProc-3,OGC 18-062]]] Pross, B.: OGC 18-062, *OGC API - Processes - Part 1: Core* + +* [[[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 diff --git a/extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc b/extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc new file mode 100644 index 00000000..7807e494 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc @@ -0,0 +1,25 @@ + +== Terms, definitions and abbreviated terms + +=== Terms and definitions + +==== Execution unit + +A component containing a process that an implementation of the Processes API Part 1 can run. + +==== Deploy + +Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard. + +==== Replace + +Replace refers to upgrading a deployed process from a Processes API implementation. + +==== Undeploy + +Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process. + +=== Abbreviated Terms + +CWL:: Common Workflow Language +DRU:: Deploy, Replace, Undeploy diff --git a/extensions/job_management/standard/sections/clause_5_conventions.adoc b/extensions/job_management/standard/sections/clause_5_conventions.adoc new file mode 100644 index 00000000..af2b0125 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_5_conventions.adoc @@ -0,0 +1,4 @@ + +== Conventions and background + +See <>, Clause 5. diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc new file mode 100644 index 00000000..b1de6f88 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -0,0 +1,248 @@ +== Requirements Class "Job Management" + +[[job-management]] +=== Overview + +include::../requirements/requirements_class_job-management.adoc[] + +A server that implements the Job Management Requirements Class provides the ability to +create, update and start jobs. + +The HTTP POST method is used to create new jobs. + +The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint. + +Finally, the HTTP POST method is used to start a job. + +Creating or updating a job requires that a formal description of the new or +updated jobs be provided by the client. This Standard does +mandate that a specific jobs schema be used. +However, this extension defines the following conformance +classe: + + * <>, that enables support for OpenEO-encoded jobs definition. + + +[[job-management-http_status_codes]] +==== HTTP status codes + +Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code. + +The *Status Codes* listed in <> are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in <> are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations. + +[[status_codes]] +.Typical HTTP status codes +[cols="15,85",options="header"] +|=== +|Status code |Description +|`200` |A successful request. +|`201` |The server has successfully completed the operation and a new resource has been created. +|`202` |The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. +|`204` |A successful request with no additional content to send in the response. +|`400` |The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value. +|`401` |The request requires user authentication. The response includes a `WWW-Authenticate` header field containing a challenge applicable to the requested resource. +|`403` |The server understood the request, but is refusing to execute the request. While status code `401` indicates missing or bad authentication, status code `403` indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource. +|`404` |The requested resource does not exist on the server. For example, a path parameter had an incorrect value. +|`405` |The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests. +|`406` |Content negotiation failed. For example, the `Accept` header submitted in the request did not support any of the media types supported by the server for the requested resource. +|`412` |The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server. +|`413` |The server is refusing to process the request because the request content is larger than the server is willing or able to process. +|`415` |The server is refusing to service the request because the content is in a format not supported by this method on the target resource. +|`422` |The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing. +|`500` |An internal error occurred in the server. +|=== + +NOTE: Status code `422` is not yet an official HTTP status code, but is expected to be added by the https://www.ietf.org/archive/id/draft-ietf-httpbis-semantics-14.html#name-422-unprocessable-content[draft IETF RFC "HTTP Semantics"]. + +More specific guidance is provided for each resource, where applicable. + +include::../recommendations/job-management/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. + +[[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)]. + + + +[[create]] +=== Creating a new job + +==== Sequence diagram + +The following diagram illustrates the sequence diagram for deploying +a new process to the API: + + +``` +Client Server + | | + | POST /jobs HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 201 Created | + | Location: /jobs/{jobId} | + |<------------------------------------------------------------| +``` + + +==== Operation + +include::../requirements/job-management/create/REQ_post-op.adoc[] + +==== Request body + +===== Overview + +include::../requirements/job-management/create/REQ_body.adoc[] + +include::../recommendations/job-management/create/PER_body.adoc[] + +include::../requirements/job-management/create/REQ_content-type.adoc[] + +See https://www.rfc-editor.org/rfc/rfc7231#section-3.1.1.5[section 3.1.1.5 of RFC 7231] for details. + +===== OGC API - Processes - Workflow Execute Request body + +include::../recommendations/job-management/create/REC_body-ogcapi-processes.adoc[] + +===== OpenEO Process Graph body + +include::../recommendations/job-management/create/REC_body-openeo.adoc[] + + +==== Response + +include::../requirements/job-management/create/REQ_response-jobid.adoc[] + +include::../requirements/job-management/create/REQ_response-success.adoc[] + +include::../requirements/job-management/create/REQ_response-body.adoc[] + +==== Exceptions + +See <> for general guidance. + +If the request body's media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from <>. + +[[update]] +=== Updating an existing job + +==== Sequence diagram + +The following diagram illustrates the sequence diagram for updating a +previously created job. The identifier of the job does not change. + +NOTE: The new job definition replaces the old job definition. Version control is not discussed in this Standard. + +``` +Client Server + | | + | PUT /jobs/{jobId} HTTP/1.1 | + | Content-Type: application/json | + | | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| +``` + +==== Operation + +include::../requirements/job-management/update/REQ_put-op.adoc[] + +==== Request body + +==== Overview + +include::../requirements/job-management/update/REQ_body.adoc[] + +include::../recommendations/job-management/update/PER_body.adoc[] + +include::../requirements/job-management/update/REQ_content-type.adoc[] + +===== OGC API - Processes - Workflow Execute Request body + +include::../recommendations/job-management/update/REC_body-ogcapi-processes.adoc[] + +===== OpenEO Process Graph body + +include::../recommendations/job-management/update/REC_body-openeo.adoc[] + +==== Response + +include::../requirements/job-management/update/REQ_response.adoc[] + +The status code depends on the server. If the server has replaced the job, the response is either `200` (if the response includes additional content) or `204` (if the response has no additional content). + +If the server will process the replace request later, a `202` status code will be returned. In this case, the processing can succeed or fail, without further notification to the client. + +==== Exceptions + +See <> for general guidance. + +If the request body's media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from <>. + +If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. + +[[undeploy]] +=== Staring a job + +==== Sequence diagram + +The following diagram illustrates the sequence diagram for starting +the execution of a previously created jobs. + + +``` +Client Server + | | + | POST /jobs/{jobId} HTTP/1.1 | + |------------------------------------------------------------>| + | | + | HTTP/1.1 204 OK | + |<------------------------------------------------------------| +``` + +==== Operation + +include::../requirements/job-management/start/REQ_start-op.adoc[] + +==== Response + +include::../requirements/job-management/start/REQ_response.adoc[] + +==== Exceptions + +See <> for general guidance. + +If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. + + + +[[job-management-definition]] +=== Job definition + +For every job, it is possible to retrieve its original definition. It corresponds to the request's body used to create or update the jobs. + +==== Operation + +include::../requirements/job-management/definition/REQ_get-op.adoc[] + +==== Response + +===== Overview + +include::../requirements/job-management/definition/REQ_response-success.adoc[] + +include::../requirements/job-management/definition/REQ_response-body.adoc[] + +==== Exceptions + +See <> for general guidance. + +If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. diff --git a/extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc b/extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc new file mode 100644 index 00000000..947e659e --- /dev/null +++ b/extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc @@ -0,0 +1,33 @@ + +== Requirements Class "OGC API - Process - Workflow Execute Request" + +[[ogcapi-processes-overview]] +=== Overview + +include::../requirements/requirements_class_ogcapi-processes.adoc[] + +This requirements class defines that the OGC API - Process - Workflow Execute Request is supported as an encoding for job definitions. + +=== OGC API - Processes + +==== Overview + +include::../requirements/ogcapi-processes/REQ_schema.adoc[] + +=== Create + +==== OGC API - Processes body + +include::../requirements/ogcapi-processes/create/REQ_body.adoc[] + +=== Update + +==== OGC API - Processes body + +include::../requirements/ogcapi-processes/update/REQ_body.adoc[] + +=== Job definition + +==== OGC API - Processes content + +include::../requirements/ogcapi-processes/definition/REQ_response-body.adoc[] \ No newline at end of file diff --git a/extensions/job_management/standard/sections/clause_8_openeo.adoc b/extensions/job_management/standard/sections/clause_8_openeo.adoc new file mode 100644 index 00000000..b9689362 --- /dev/null +++ b/extensions/job_management/standard/sections/clause_8_openeo.adoc @@ -0,0 +1,40 @@ + +== Requirements Class "OpenEO Process Graph" + +[[openeo-overview]] +=== Overview + +include::../requirements/requirements_class_openeo.adoc[] + +This requirements class defines that the server supports the OpenEO Process Graph as an encoding for job definitions. + +=== OpenEO Process Graph + +==== Overview + +include::../requirements/openeo/REQ_schema.adoc[] + +[[schema_ogcappkg]] +.link:http://schemas.opengis.net/ogcapi/processes/part4/1.0/openapi/schemas/openeo-process-graph.yaml[Schema for OpenEO Process Graph] +[source,yaml] +---- +include::../../../../openapi/schemas/processes-job-management/openeo-process-graph.yaml[] +---- + +=== Create + +==== OpenEO body + +include::../requirements/openeo/create/REQ_body.adoc[] + +=== Update + +==== OpenEO body + +include::../requirements/openeo/update/REQ_body.adoc[] + +=== Job definition + +==== OpenEO content + +include::../requirements/openeo/definition/REQ_response-body.adoc[] \ No newline at end of file diff --git a/extensions/job_management/standard/sections/clause_9_quotation.adoc b/extensions/job_management/standard/sections/clause_9_quotation.adoc new file mode 100644 index 00000000..7ca26b3e --- /dev/null +++ b/extensions/job_management/standard/sections/clause_9_quotation.adoc @@ -0,0 +1,8 @@ + +== Requirements Class "Quotation" + +[[quotation-overview]] +=== Overview + +include::../requirements/requirements_class_quotation.adoc[] + diff --git a/extensions/job_management/standard/standard.css b/extensions/job_management/standard/standard.css new file mode 100644 index 00000000..8271ec58 --- /dev/null +++ b/extensions/job_management/standard/standard.css @@ -0,0 +1,2134 @@ +/*! normalize.css v2.1.2 | MIT License | git.io/normalize */ +/* ========================================================================== HTML5 display definitions ========================================================================== */ +/** Correct `block` display not defined in IE 8/9. */ +article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { + display: block; +} + +/** Correct `inline-block` display not defined in IE 8/9. */ +audio, canvas, video { + display: inline-block; +} + +/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */ +audio:not([controls]) { + display: none; + height: 0; +} + +/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */ +[hidden], template { + display: none; +} + +script { + display: none !important; +} + +/* ========================================================================== Base ========================================================================== */ +/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */ +html { + font-family: sans-serif; /* 1 */ + -ms-text-size-adjust: 100%; /* 2 */ + -webkit-text-size-adjust: 100%; /* 2 */ +} + +/** Remove default margin. */ +body { + margin: 0; +} + +/* ========================================================================== Links ========================================================================== */ +/** Remove the gray background color from active links in IE 10. */ +a { + background: transparent; +} + +/** Address `outline` inconsistency between Chrome and other browsers. */ +a:focus { + outline: thin dotted; +} + +/** Improve readability when focused and also mouse hovered in all browsers. */ +a:active, a:hover { + outline: 0; +} + +/* ========================================================================== Typography ========================================================================== */ +/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */ +h1 { + font-size: 2em; + margin: 0.67em 0; +} + +/** Address styling not present in IE 8/9, Safari 5, and Chrome. */ +abbr[title] { + border-bottom: 1px dotted; +} + +/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */ +b, strong { + font-weight: bold; +} + +/** Address styling not present in Safari 5 and Chrome. */ +dfn { + font-style: italic; +} + +/** Address differences between Firefox and other browsers. */ +hr { + -moz-box-sizing: content-box; + box-sizing: content-box; + height: 0; +} + +/** Address styling not present in IE 8/9. */ +mark { + background: #ff0; + color: #000; +} + +/** Correct font family set oddly in Safari 5 and Chrome. */ +code, kbd, pre, samp { + font-family: monospace, serif; + font-size: 1em; +} + +/** Improve readability of pre-formatted text in all browsers. */ +pre { + white-space: pre-wrap; +} + +/** Set consistent quote types. */ +q { + quotes: "\201C" "\201D" "\2018" "\2019"; +} + +/** Address inconsistent and variable font size in all browsers. */ +small { + font-size: 80%; +} + +/** Address inconsistent and variable font size in all browsers. */ +big { + font-size: 160%; +} + +/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */ +sub, sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline; +} + +sup { + top: -0.5em; +} + +sub { + bottom: -0.25em; +} + +/* ========================================================================== Embedded content ========================================================================== */ +/** Remove border when inside `a` element in IE 8/9. */ +img { + border: 0; +} + +/** Correct overflow displayed oddly in IE 9. */ +svg:not(:root) { + overflow: hidden; +} + +/* ========================================================================== Figures ========================================================================== */ +/** Address margin not present in IE 8/9 and Safari 5. */ +figure { + margin: 0; +} + +/* ========================================================================== Forms ========================================================================== */ +/** Define consistent border, margin, and padding. */ +fieldset { + border: 1px solid #c0c0c0; + margin: 0 2px; + padding: 0.35em 0.625em 0.75em; +} + +/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */ +legend { + border: 0; /* 1 */ + padding: 0; /* 2 */ +} + +/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */ +button, input, select, textarea { + font-family: inherit; /* 1 */ + font-size: 100%; /* 2 */ + margin: 0; /* 3 */ +} + +/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */ +button, input { + line-height: normal; +} + +/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */ +button, select { + text-transform: none; +} + +/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */ +button, html input[type="button"], input[type="reset"], input[type="submit"] { + -webkit-appearance: button; /* 2 */ + cursor: pointer; /* 3 */ +} + +/** Re-set default cursor for disabled elements. */ +button[disabled], html input[disabled] { + cursor: default; +} + +/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */ +input[type="checkbox"], input[type="radio"] { + box-sizing: border-box; /* 1 */ + padding: 0; /* 2 */ +} + +/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */ +input[type="search"] { + -webkit-appearance: textfield; /* 1 */ + -moz-box-sizing: content-box; + -webkit-box-sizing: content-box; /* 2 */ + box-sizing: content-box; +} + +/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */ +input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { + -webkit-appearance: none; +} + +/** Remove inner padding and border in Firefox 4+. */ +button::-moz-focus-inner, input::-moz-focus-inner { + border: 0; + padding: 0; +} + +/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */ +textarea { + overflow: auto; /* 1 */ + vertical-align: top; /* 2 */ +} + +/* ========================================================================== Tables ========================================================================== */ +/** Remove most spacing between table cells. */ +table { + border-collapse: collapse; + border-spacing: 0; +} + +meta.foundation-mq-small { + font-family: "only screen and (min-width: 768px)"; + width: 768px; +} + +meta.foundation-mq-medium { + font-family: "only screen and (min-width:1280px)"; + width: 1280px; +} + +meta.foundation-mq-large { + font-family: "only screen and (min-width:1440px)"; + width: 1440px; +} + +*, *:before, *:after { + -moz-box-sizing: border-box; + -webkit-box-sizing: border-box; + box-sizing: border-box; +} + +html, body { + font-size: 100%; +} + +body { + background: white; + color: rgba(0, 0, 0, 0.8); + padding: 0; + margin: 0; + font-family: "Noto Serif", "DejaVu Serif", serif; + font-weight: normal; + font-style: normal; + line-height: 1; + position: relative; + cursor: auto; +} + +a:hover { + cursor: pointer; +} + +img, object, embed { + max-width: 100%; + height: auto; +} + +object, embed { + height: 100%; +} + +img { + -ms-interpolation-mode: bicubic; +} + +#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { + max-width: none !important; +} + +.left { + float: left !important; +} + +.right { + float: right !important; +} + +.text-left { + text-align: left !important; +} + +.text-right { + text-align: right !important; +} + +.text-center { + text-align: center !important; +} + +.text-justify { + text-align: justify !important; +} + +.hide { + display: none; +} + +.antialiased, body { + -webkit-font-smoothing: antialiased; +} + +img { + display: inline-block; + vertical-align: middle; +} + +textarea { + height: auto; + min-height: 50px; +} + +select { + width: 100%; +} + +p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { + font-size: 1.21875em; + line-height: 1.6; +} + +.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { + line-height: 1.45; + color: #000000; + font-weight: normal; + margin-top: 0; + margin-bottom: 0.25em; +} + +/* Typography resets */ +div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { + margin: 0; + padding: 0; + direction: ltr; +} + +/* Default Link Styles */ +a { + color: #2156a5; + text-decoration: underline; + line-height: inherit; +} + +a:hover, a:focus { + color: #1d4b8f; +} + +a img { + border: none; +} + +/* Default paragraph styles */ +p { + font-family: inherit; + font-weight: normal; + font-size: 1em; + line-height: 1.6; + margin-bottom: 1.25em; + text-rendering: optimizeLegibility; +} + +p aside { + font-size: 0.875em; + line-height: 1.35; + font-style: italic; +} + +/* Default header styles */ +h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { + font-family: "Noto Serif", "DejaVu Serif", serif; + font-weight: 300; + font-style: normal; + color: #000000; + text-rendering: optimizeLegibility; + margin-top: 1em; + margin-bottom: 0.5em; + line-height: 1.0125em; +} + +h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { + font-size: 60%; + color: #000000; + line-height: 0; +} + +h1 { + font-size: 160%; +} + +h2 { + font-size: 160%; +} + +h3, #toctitle, .sidebarblock > .content > .title { + font-size: 140%; +} + +h4 { + font-size: 1em; +} + +h5 { + font-size: 1em; +} + +h6 { + font-size: 1em; +} + +hr { + border: solid #ddddd8; + border-width: 1px 0 0; + clear: both; + margin: 1.25em 0 1.1875em; + height: 0; +} + +/* Helpful Typography Defaults */ +em, i { + font-style: italic; + line-height: inherit; +} + +strong, b { + font-weight: bold; + line-height: inherit; +} + +small { + font-size: 60%; + line-height: inherit; +} + +code { + font-family: "Droid Sans Mono", "DejaVu Sans Mono", "Monospace", monospace; + font-weight: normal; + color: rgba(0, 0, 0, 0.9); +} + +/* Lists */ +ul, ol, dl { + font-size: 1em; + line-height: 1.6; + margin-bottom: 1.25em; + list-style-position: outside; + font-family: inherit; +} + +ul, ol { + margin-left: 1.5em; +} + +ul.no-bullet, ol.no-bullet { + margin-left: 1.5em; +} + +/* Unordered Lists */ +ul li ul, ul li ol { + margin-left: 1.25em; + margin-bottom: 0; + font-size: 1em; /* Override nested font-size change */ +} + +ul.square li ul, ul.circle li ul, ul.disc li ul { + list-style: inherit; +} + +ul.square { + list-style-type: square; +} + +ul.circle { + list-style-type: circle; +} + +ul.disc { + list-style-type: disc; +} + +ul.no-bullet { + list-style: none; +} + +/* Ordered Lists */ +ol li ul, ol li ol { + margin-left: 1.25em; + margin-bottom: 0; +} + +/* Definition Lists */ +dl dt { + margin-bottom: 0.3125em; + font-weight: bold; +} + +dl dd { + margin-bottom: 1.25em; +} + +/* Abbreviations */ +abbr, acronym { + text-transform: uppercase; + font-size: 90%; + color: rgba(0, 0, 0, 0.8); + border-bottom: 1px dotted #dddddd; + cursor: help; +} + +abbr { + text-transform: none; +} + +/* Blockquotes */ +blockquote { + margin: 0 0 1.25em; + padding: 0.5625em 1.25em 0 1.1875em; + border-left: 1px solid #dddddd; +} + +blockquote cite { + display: block; + font-size: 0.9375em; + color: rgba(0, 0, 0, 0.6); +} + +blockquote cite:before { + content: "\2014 \0020"; +} + +blockquote cite a, blockquote cite a:visited { + color: rgba(0, 0, 0, 0.6); +} + +blockquote, blockquote p { + line-height: 1.6; + color: rgba(0, 0, 0, 0.85); +} + +/* Microformats */ +.vcard { + display: inline-block; + margin: 0 0 1.25em 0; + border: 1px solid #dddddd; + padding: 0.625em 0.75em; +} + +.vcard li { + margin: 0; + display: block; +} + +.vcard .fn { + font-weight: bold; + font-size: 0.9375em; +} + +.vevent .summary { + font-weight: bold; +} + +.vevent abbr { + cursor: auto; + text-decoration: none; + font-weight: bold; + border: none; + padding: 0 0.0625em; +} + +@media only screen and (min-width: 768px) { + h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { + font-family: "Noto Serif", "DejaVu Serif", serif; + line-height: 1.2; + font-weight: 300; + font-style: normal; + color: #000000; + text-rendering: optimizeLegibility; + margin-top: 1em; + margin-bottom: 0.5em; + line-height: 1.0125em; + } + + h1 { + font-size: 160%; + font-weight: bold; + } + + h2 { + font-size: 160%; + font-weight: bold; + } + + h3, #toctitle, .sidebarblock > .content > .title { + font-size: 140%; + font-weight: bold; + } + + h4 { + font-size: 1em; + } +} + +/* Tables */ +table { + background: white; + margin-bottom: 1.25em; + border: solid 1px #dedede; +} + +table thead, table tfoot { + background: #f7f8f7; + font-weight: bold; +} + +table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { + padding: 0.5em 0.625em 0.625em; + font-size: inherit; + color: rgba(0, 0, 0, 0.8); + text-align: left; +} + +table tr th, table tr td { + padding: 0.5625em 0.625em; + font-size: inherit; + color: rgba(0, 0, 0, 0.8); +} + +table tr.even, table tr.alt, table tr:nth-of-type(even) { + background: #f8f8f7; +} + +table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { + display: table-cell; + line-height: 1.6; +} + +h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { + line-height: 1.2; + word-spacing: -0.05em; +} + +h1 strong, h2 strong, h3 strong, #toctitle strong, .sidebarblock > .content > .title strong, h4 strong, h5 strong, h6 strong { + font-weight: 400; +} + +.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { + content: " "; + display: table; +} + +.clearfix:after, .float-group:after { + clear: both; +} + +*:not(pre) > code { + font-size: 0.9375em; + font-style: normal !important; + letter-spacing: 0; + padding: 0.1em 0.5ex; + word-spacing: -0.15em; + background-color: #f7f7f8; + -webkit-border-radius: 4px; + border-radius: 4px; + line-height: 1.45; + text-rendering: optimizeSpeed; +} + +pre, pre > code { + line-height: 1.45; + color: rgba(0, 0, 0, 0.9); + font-family: "Droid Sans Mono", "DejaVu Sans Mono", "Monospace", monospace; + font-weight: normal; + text-rendering: optimizeSpeed; +} + +.keyseq { + color: rgba(51, 51, 51, 0.8); +} + +kbd { + display: inline-block; + color: rgba(0, 0, 0, 0.8); + font-size: 0.75em; + line-height: 1.4; + background-color: #f7f7f7; + border: 1px solid #ccc; + -webkit-border-radius: 3px; + border-radius: 3px; + -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; + box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; + margin: -0.15em 0.15em 0 0.15em; + padding: 0.2em 0.6em 0.2em 0.5em; + vertical-align: middle; + white-space: nowrap; +} + +.keyseq kbd:first-child { + margin-left: 0; +} + +.keyseq kbd:last-child { + margin-right: 0; +} + +.menuseq, .menu { + color: rgba(0, 0, 0, 0.8); +} + +b.button:before, b.button:after { + position: relative; + top: -1px; + font-weight: normal; +} + +b.button:before { + content: "["; + padding: 0 3px 0 2px; +} + +b.button:after { + content: "]"; + padding: 0 2px 0 3px; +} + +p a > code:hover { + color: rgba(0, 0, 0, 0.9); +} + +#header, #content, #footnotes, #footer { + width: 100%; + margin-left: auto; + margin-right: auto; + margin-top: 0; + margin-bottom: 0; + max-width: 62.5em; + *zoom: 1; + position: relative; + padding-left: 0.9375em; + padding-right: 0.9375em; +} + +#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { + content: " "; + display: table; +} + +#header:after, #content:after, #footnotes:after, #footer:after { + clear: both; +} + +#content { + margin-top: 1.25em; +} + +#content:before { + content: none; +} + +#header > h1:first-child { + color: rgba(0, 0, 0, 0.85); + margin-top: 2.25rem; + margin-bottom: 0; +} + +#header > h1:first-child + #toc { + margin-top: 8px; + border-top: 1px solid #ddddd8; +} + +#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { + border-bottom: 1px solid #ddddd8; + padding-bottom: 8px; +} + +#header .details { + border-bottom: 1px solid #ddddd8; + line-height: 1.45; + padding-top: 0.25em; + padding-bottom: 0.25em; + padding-left: 0.25em; + color: rgba(0, 0, 0, 0.6); + display: -ms-flexbox; + display: -webkit-flex; + display: flex; + -ms-flex-flow: row wrap; + -webkit-flex-flow: row wrap; + flex-flow: row wrap; +} + +#header .details span:first-child { + margin-left: -0.125em; +} + +#header .details span.email a { + color: rgba(0, 0, 0, 0.85); +} + +#header .details br { + display: none; +} + +#header .details br + span:before { + content: "\00a0\2013\00a0"; +} + +#header .details br + span.author:before { + content: "\00a0\22c5\00a0"; + color: rgba(0, 0, 0, 0.85); +} + +#header .details br + span#revremark:before { + content: "\00a0|\00a0"; +} + +#header #revnumber { + text-transform: capitalize; +} + +#header #revnumber:after { + content: "\00a0"; +} + +#content > h1:first-child:not([class]) { + color: rgba(0, 0, 0, 0.85); + border-bottom: 1px solid #ddddd8; + padding-bottom: 8px; + margin-top: 0; + padding-top: 1rem; + margin-bottom: 1.25rem; +} + +#toc { + border-bottom: 1px solid #efefed; + padding-bottom: 0.5em; +} + +#toc > ul { + margin-left: 0.125em; +} + +#toc ul.sectlevel0 > li > a { + font-style: italic; +} + +#toc ul.sectlevel0 ul.sectlevel1 { + margin: 0.5em 0; +} + +#toc ul { + font-family: "Open Sans", "DejaVu Sans", sans-serif; + list-style-type: none; +} + +#toc a { + text-decoration: none; +} + +#toc a:active { + text-decoration: underline; +} + +#toctitle { + color: #7a2518; + font-size: 1.2em; +} + +@media only screen and (min-width: 768px) { + #toctitle { + font-size: 1.375em; + } + + body.toc2 { + padding-left: 15em; + padding-right: 0; + } + + #toc.toc2 { + margin-top: 0 !important; + background-color: #f8f8f7; + position: fixed; + width: 15em; + left: 0; + top: 0; + border-right: 1px solid #efefed; + border-top-width: 0 !important; + border-bottom-width: 0 !important; + z-index: 1000; + padding: 1.25em 1em; + height: 100%; + overflow: auto; + } + + #toc.toc2 #toctitle { + margin-top: 0; + font-size: 1.2em; + } + + #toc.toc2 > ul { + font-size: 0.9em; + margin-bottom: 0; + } + + #toc.toc2 ul ul { + margin-left: 0; + padding-left: 1em; + } + + #toc.toc2 ul.sectlevel0 ul.sectlevel1 { + padding-left: 0; + margin-top: 0.5em; + margin-bottom: 0.5em; + } + + body.toc2.toc-right { + padding-left: 0; + padding-right: 15em; + } + + body.toc2.toc-right #toc.toc2 { + border-right-width: 0; + border-left: 1px solid #efefed; + left: auto; + right: 0; + } +} + +@media only screen and (min-width: 1280px) { + body.toc2 { + padding-left: 20em; + padding-right: 0; + } + + #toc.toc2 { + width: 20em; + } + + #toc.toc2 #toctitle { + font-size: 1.375em; + } + + #toc.toc2 > ul { + font-size: 0.95em; + } + + #toc.toc2 ul ul { + padding-left: 1.25em; + } + + body.toc2.toc-right { + padding-left: 0; + padding-right: 20em; + } +} + +#content #toc { + border-style: solid; + border-width: 1px; + border-color: #e0e0dc; + margin-bottom: 1.25em; + padding: 1.25em; + background: #f8f8f7; + -webkit-border-radius: 4px; + border-radius: 4px; +} + +#content #toc > :first-child { + margin-top: 0; +} + +#content #toc > :last-child { + margin-bottom: 0; +} + +#footer { + max-width: 100%; + background-color: rgba(0, 0, 0, 0.8); + padding: 1.25em; +} + +#footer-text { + color: rgba(255, 255, 255, 0.8); + line-height: 1.44; +} + +.sect1 { + padding-bottom: 0.625em; +} + +@media only screen and (min-width: 768px) { + .sect1 { + padding-bottom: 1.25em; + } +} + +.sect1 + .sect1 { + border-top: 1px solid #efefed; +} + +#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { + position: absolute; + z-index: 1001; + width: 1.5ex; + margin-left: -1.5ex; + display: block; + text-decoration: none !important; + visibility: hidden; + text-align: center; + font-weight: normal; +} + +#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { + content: "\00A7"; + font-size: 0.85em; + display: block; + padding-top: 0.1em; +} + +#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { + visibility: visible; +} + +#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { + color: #ba3925; + text-decoration: none; +} + +#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { + color: #a53221; +} + +.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { + margin-bottom: 1.25em; +} + +.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { + text-rendering: optimizeLegibility; + text-align: left; + font-family: "Noto Serif", "DejaVu Serif", serif; + font-size: 1rem; + font-style: italic; +} + +table.tableblock > caption.title { + white-space: nowrap; + overflow: visible; + max-width: 0; +} + +.paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { + color: rgba(0, 0, 0, 0.85); +} + +table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { + font-size: inherit; +} + +.admonitionblock > table { + border-collapse: separate; + border: 0; + background: none; + width: 100%; +} + +.admonitionblock > table td.icon { + text-align: center; + width: 80px; +} + +.admonitionblock > table td.icon img { + max-width: none; +} + +.admonitionblock > table td.icon .title { + font-weight: bold; + font-family: "Open Sans", "DejaVu Sans", sans-serif; + text-transform: uppercase; +} + +.admonitionblock > table td.content { + padding-left: 1.125em; + padding-right: 1.25em; + border-left: 1px solid #ddddd8; + color: rgba(0, 0, 0, 0.6); +} + +.admonitionblock > table td.content > :last-child > :last-child { + margin-bottom: 0; +} + +.exampleblock > .content { + border-style: solid; + border-width: 1px; + border-color: #e6e6e6; + margin-bottom: 1.25em; + padding: 1.25em; + background: white; + -webkit-border-radius: 4px; + border-radius: 4px; +} + +.exampleblock > .content > :first-child { + margin-top: 0; +} + +.exampleblock > .content > :last-child { + margin-bottom: 0; +} + +.sidebarblock { + border-style: solid; + border-width: 1px; + border-color: #e0e0dc; + margin-bottom: 1.25em; + padding: 1.25em; + background: #f8f8f7; + -webkit-border-radius: 4px; + border-radius: 4px; +} + +.sidebarblock > :first-child { + margin-top: 0; +} + +.sidebarblock > :last-child { + margin-bottom: 0; +} + +.sidebarblock > .content > .title { + color: #7a2518; + margin-top: 0; + text-align: center; +} + +.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { + margin-bottom: 0; +} + +.literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint { + background: #f7f7f8; +} + +.sidebarblock .literalblock pre, .sidebarblock .listingblock pre:not(.highlight), .sidebarblock .listingblock pre[class="highlight"], .sidebarblock .listingblock pre[class^="highlight "], .sidebarblock .listingblock pre.CodeRay, .sidebarblock .listingblock pre.prettyprint { + background: #f2f1f1; +} + +.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { + -webkit-border-radius: 4px; + border-radius: 4px; + word-wrap: break-word; + padding: 1em; + font-size: 0.8125em; +} + +.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { + overflow-x: auto; + white-space: pre; + word-wrap: normal; +} + +@media only screen and (min-width: 768px) { + .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { + font-size: 0.90625em; + } +} + +@media only screen and (min-width: 1280px) { + .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { + font-size: 1em; + } +} + +.literalblock.output pre { + color: #f7f7f8; + background-color: rgba(0, 0, 0, 0.9); +} + +.listingblock pre.highlightjs { + padding: 0; +} + +.listingblock pre.highlightjs > code { + padding: 1em; + -webkit-border-radius: 4px; + border-radius: 4px; +} + +.listingblock pre.prettyprint { + border-width: 0; +} + +.listingblock > .content { + position: relative; +} + +.listingblock code[data-lang]:before { + display: none; + content: attr(data-lang); + position: absolute; + font-size: 0.75em; + top: 0.425rem; + right: 0.5rem; + line-height: 1; + text-transform: uppercase; + color: #999; +} + +.listingblock:hover code[data-lang]:before { + display: block; +} + +.listingblock.terminal pre .command:before { + content: attr(data-prompt); + padding-right: 0.5em; + color: #999; +} + +.listingblock.terminal pre .command:not([data-prompt]):before { + content: "$"; +} + +table.pyhltable { + border-collapse: separate; + border: 0; + margin-bottom: 0; + background: none; +} + +table.pyhltable td { + vertical-align: top; + padding-top: 0; + padding-bottom: 0; +} + +table.pyhltable td.code { + padding-left: .75em; + padding-right: 0; +} + +pre.pygments .lineno, table.pyhltable td:not(.code) { + color: #999; + padding-left: 0; + padding-right: .5em; + border-right: 1px solid #ddddd8; +} + +pre.pygments .lineno { + display: inline-block; + margin-right: .25em; +} + +table.pyhltable .linenodiv { + background: none !important; + padding-right: 0 !important; +} + +.quoteblock { + margin: 0 1em 1.25em 1.5em; + display: table; +} + +.quoteblock > .title { + margin-left: -1.5em; + margin-bottom: 0.75em; +} + +.quoteblock blockquote, .quoteblock blockquote p { + color: rgba(0, 0, 0, 0.85); + font-size: 1.15rem; + line-height: 1.75; + word-spacing: 0.1em; + letter-spacing: 0; + font-style: italic; + text-align: justify; +} + +.quoteblock blockquote { + margin: 0; + padding: 0; + border: 0; +} + +.quoteblock blockquote:before { + content: "\201c"; + float: left; + font-size: 2.75em; + font-weight: bold; + line-height: 0.6em; + margin-left: -0.6em; + color: #7a2518; + text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); +} + +.quoteblock blockquote > .paragraph:last-child p { + margin-bottom: 0; +} + +.quoteblock .attribution { + margin-top: 0.5em; + margin-right: 0.5ex; + text-align: right; +} + +.quoteblock .quoteblock { + margin-left: 0; + margin-right: 0; + padding: 0.5em 0; + border-left: 3px solid rgba(0, 0, 0, 0.6); +} + +.quoteblock .quoteblock blockquote { + padding: 0 0 0 0.75em; +} + +.quoteblock .quoteblock blockquote:before { + display: none; +} + +.verseblock { + margin: 0 1em 1.25em 1em; +} + +.verseblock pre { + font-family: "Open Sans", "DejaVu Sans", sans; + font-size: 1.15rem; + color: rgba(0, 0, 0, 0.85); + font-weight: 300; + text-rendering: optimizeLegibility; +} + +.verseblock pre strong { + font-weight: 400; +} + +.verseblock .attribution { + margin-top: 1.25rem; + margin-left: 0.5ex; +} + +.quoteblock .attribution, .verseblock .attribution { + font-size: 0.9375em; + line-height: 1.45; + font-style: italic; +} + +.quoteblock .attribution br, .verseblock .attribution br { + display: none; +} + +.quoteblock .attribution cite, .verseblock .attribution cite { + display: block; + letter-spacing: -0.05em; + color: rgba(0, 0, 0, 0.6); +} + +.quoteblock.abstract { + margin: 0 0 1.25em 0; + display: block; +} + +.quoteblock.abstract blockquote, .quoteblock.abstract blockquote p { + text-align: left; + word-spacing: 0; +} + +.quoteblock.abstract blockquote:before, .quoteblock.abstract blockquote p:first-of-type:before { + display: none; +} + +table.tableblock { + max-width: 100%; + border-collapse: separate; +} + +table.tableblock td > .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { + margin-bottom: 0; +} + +table.spread { + width: 100%; +} + +table.tableblock, th.tableblock, td.tableblock { + border: 0 solid #dedede; +} + +table.grid-all th.tableblock, table.grid-all td.tableblock { + border-width: 0 1px 1px 0; +} + +table.grid-all tfoot > tr > th.tableblock, table.grid-all tfoot > tr > td.tableblock { + border-width: 1px 1px 0 0; +} + +table.grid-cols th.tableblock, table.grid-cols td.tableblock { + border-width: 0 1px 0 0; +} + +table.grid-all * > tr > .tableblock:last-child, table.grid-cols * > tr > .tableblock:last-child { + border-right-width: 0; +} + +table.grid-rows th.tableblock, table.grid-rows td.tableblock { + border-width: 0 0 1px 0; +} + +table.grid-all tbody > tr:last-child > th.tableblock, table.grid-all tbody > tr:last-child > td.tableblock, table.grid-all thead:last-child > tr > th.tableblock, table.grid-rows tbody > tr:last-child > th.tableblock, table.grid-rows tbody > tr:last-child > td.tableblock, table.grid-rows thead:last-child > tr > th.tableblock { + border-bottom-width: 0; +} + +table.grid-rows tfoot > tr > th.tableblock, table.grid-rows tfoot > tr > td.tableblock { + border-width: 1px 0 0 0; +} + +table.frame-all { + border-width: 1px; +} + +table.frame-sides { + border-width: 0 1px; +} + +table.frame-topbot { + border-width: 1px 0; +} + +th.halign-left, td.halign-left { + text-align: left; +} + +th.halign-right, td.halign-right { + text-align: right; +} + +th.halign-center, td.halign-center { + text-align: center; +} + +th.valign-top, td.valign-top { + vertical-align: top; +} + +th.valign-bottom, td.valign-bottom { + vertical-align: bottom; +} + +th.valign-middle, td.valign-middle { + vertical-align: middle; +} + +table thead th, table tfoot th { + font-weight: bold; +} + +tbody tr th { + display: table-cell; + line-height: 1.6; + background: #f7f8f7; +} + +tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { + color: rgba(0, 0, 0, 0.8); + font-weight: bold; +} + +p.tableblock > code:only-child { + background: none; + padding: 0; +} + +p.tableblock { + font-size: 1em; +} + +td > div.verse { + white-space: pre; +} + +ol { + margin-left: 1.75em; +} + +ul li ol { + margin-left: 1.5em; +} + +dl dd { + margin-left: 1.125em; +} + +dl dd:last-child, dl dd:last-child > :last-child { + margin-bottom: 0; +} + +ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { + margin-bottom: 0.625em; +} + +ul.unstyled, ol.unnumbered, ul.checklist, ul.none { + list-style-type: none; +} + +ul.unstyled, ol.unnumbered, ul.checklist { + margin-left: 0.625em; +} + +ul.checklist li > p:first-child > .fa-check-square-o:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { + margin-right: 0.25em; +} + +ul.checklist li > p:first-child > input[type="checkbox"]:first-child { + position: relative; + top: 1px; +} + +ul.inline { + margin: 0 auto 0.625em auto; + margin-left: -1.375em; + margin-right: 0; + padding: 0; + list-style: none; + overflow: hidden; +} + +ul.inline > li { + list-style: none; + float: left; + margin-left: 1.375em; + display: block; +} + +ul.inline > li > * { + display: block; +} + +.unstyled dl dt { + font-weight: normal; + font-style: normal; +} + +ol.arabic { + list-style-type: decimal; +} + +ol.decimal { + list-style-type: decimal-leading-zero; +} + +ol.loweralpha { + list-style-type: lower-alpha; +} + +ol.upperalpha { + list-style-type: upper-alpha; +} + +ol.lowerroman { + list-style-type: lower-roman; +} + +ol.upperroman { + list-style-type: upper-roman; +} + +ol.lowergreek { + list-style-type: lower-greek; +} + +.hdlist > table, .colist > table { + border: 0; + background: none; +} + +.hdlist > table > tbody > tr, .colist > table > tbody > tr { + background: none; +} + +td.hdlist1 { + padding-right: .75em; + font-weight: bold; +} + +td.hdlist1, td.hdlist2 { + vertical-align: top; +} + +.literalblock + .colist, .listingblock + .colist { + margin-top: -0.5em; +} + +.colist > table tr > td:first-of-type { + padding: 0 0.75em; + line-height: 1; +} + +.colist > table tr > td:last-of-type { + padding: 0.25em 0; +} + +.thumb, .th { + line-height: 0; + display: inline-block; + border: solid 4px white; + -webkit-box-shadow: 0 0 0 1px #dddddd; + box-shadow: 0 0 0 1px #dddddd; +} + +.imageblock.left, .imageblock[style*="float: left"] { + margin: 0.25em 0.625em 1.25em 0; +} + +.imageblock.right, .imageblock[style*="float: right"] { + margin: 0.25em 0 1.25em 0.625em; +} + +.imageblock > .title { + margin-bottom: 0; +} + +.imageblock.thumb, .imageblock.th { + border-width: 6px; +} + +.imageblock.thumb > .title, .imageblock.th > .title { + padding: 0 0.125em; +} + +.image.left, .image.right { + margin-top: 0.25em; + margin-bottom: 0.25em; + display: inline-block; + line-height: 0; +} + +.image.left { + margin-right: 0.625em; +} + +.image.right { + margin-left: 0.625em; +} + +a.image { + text-decoration: none; +} + +span.footnote, span.footnoteref { + vertical-align: super; + font-size: 0.875em; +} + +span.footnote a, span.footnoteref a { + text-decoration: none; +} + +span.footnote a:active, span.footnoteref a:active { + text-decoration: underline; +} + +#footnotes { + padding-top: 0.75em; + padding-bottom: 0.75em; + margin-bottom: 0.625em; +} + +#footnotes hr { + width: 20%; + min-width: 6.25em; + margin: -.25em 0 .75em 0; + border-width: 1px 0 0 0; +} + +#footnotes .footnote { + padding: 0 0.375em; + line-height: 1.3; + font-size: 0.875em; + margin-left: 1.2em; + text-indent: -1.2em; + margin-bottom: .2em; +} + +#footnotes .footnote a:first-of-type { + font-weight: bold; + text-decoration: none; +} + +#footnotes .footnote:last-of-type { + margin-bottom: 0; +} + +#content #footnotes { + margin-top: -0.625em; + margin-bottom: 0; + padding: 0.75em 0; +} + +.gist .file-data > table { + border: 0; + background: #fff; + width: 100%; + margin-bottom: 0; +} + +.gist .file-data > table td.line-data { + width: 99%; +} + +div.unbreakable { + page-break-inside: avoid; +} + +.big { + font-size: x-large; +} + +.small { + font-size: smaller; +} + +.underline { + text-decoration: underline; +} + +.overline { + text-decoration: overline; +} + +.line-through { + text-decoration: line-through; +} + +.aqua { + color: #00bfbf; +} + +.aqua-background { + background-color: #00fafa; +} + +.black { + color: black; +} + +.black-background { + background-color: black; +} + +.blue { + color: #0000bf; +} + +.blue-background { + background-color: #0000fa; +} + +.fuchsia { + color: #bf00bf; +} + +.fuchsia-background { + background-color: #fa00fa; +} + +.gray { + color: #606060; +} + +.gray-background { + background-color: #7d7d7d; +} + +.green { + color: #006000; +} + +.green-background { + background-color: #007d00; +} + +.lime { + color: #00bf00; +} + +.lime-background { + background-color: #00fa00; +} + +.maroon { + color: #600000; +} + +.maroon-background { + background-color: #7d0000; +} + +.navy { + color: #000060; +} + +.navy-background { + background-color: #00007d; +} + +.olive { + color: #606000; +} + +.olive-background { + background-color: #7d7d00; +} + +.purple { + color: #600060; +} + +.purple-background { + background-color: #7d007d; +} + +.red { + color: #bf0000; +} + +.red-background { + background-color: #fa0000; +} + +.silver { + color: #909090; +} + +.silver-background { + background-color: #bcbcbc; +} + +.teal { + color: #006060; +} + +.teal-background { + background-color: #007d7d; +} + +.white { + color: #bfbfbf; +} + +.white-background { + background-color: #fafafa; +} + +.yellow { + color: #bfbf00; +} + +.yellow-background { + background-color: #fafa00; +} + +span.icon > .fa { + cursor: default; +} + +.admonitionblock td.icon [class^="fa icon-"] { + font-size: 2.5em; + text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); + cursor: default; +} + +.admonitionblock td.icon .icon-note:before { + content: "\f05a"; + color: #19407c; +} + +.admonitionblock td.icon .icon-tip:before { + content: "\f0eb"; + text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); + color: #111; +} + +.admonitionblock td.icon .icon-warning:before { + content: "\f071"; + color: #bf6900; +} + +.admonitionblock td.icon .icon-caution:before { + content: "\f06d"; + color: #bf3400; +} + +.admonitionblock td.icon .icon-important:before { + content: "\f06a"; + color: #bf0000; +} + +.conum[data-value] { + display: inline-block; + color: #fff !important; + background-color: rgba(0, 0, 0, 0.8); + -webkit-border-radius: 100px; + border-radius: 100px; + text-align: center; + font-size: 0.75em; + width: 1.67em; + height: 1.67em; + line-height: 1.67em; + font-family: "Open Sans", "DejaVu Sans", sans-serif; + font-style: normal; + font-weight: bold; +} + +.conum[data-value] * { + color: #fff !important; +} + +.conum[data-value] + b { + display: none; +} + +.conum[data-value]:after { + content: attr(data-value); +} + +pre .conum[data-value] { + position: relative; + top: -0.125em; +} + +b.conum * { + color: inherit !important; +} + +.conum:not([data-value]):empty { + display: none; +} + +h1, h2 { + letter-spacing: -0.01em; +} + +dt, th.tableblock, td.content { + text-rendering: optimizeLegibility; +} + +p, td.content { + letter-spacing: -0.01em; +} + +p strong, td.content strong { + letter-spacing: -0.005em; +} + +p, blockquote, dt, td.content { + font-size: 1.0625rem; +} + +p { + margin-bottom: 1.25rem; +} + +.sidebarblock p, .sidebarblock dt, .sidebarblock td.content, p.tableblock { + font-size: 1em; +} + +.exampleblock > .content { + background-color: #fffef7; + border-color: #e0e0dc; + -webkit-box-shadow: 0 1px 4px #e0e0dc; + box-shadow: 0 1px 4px #e0e0dc; +} + +.print-only { + display: none !important; +} + +@media print { + @page { + margin: 1.25cm 0.75cm; + } + + * { + -webkit-box-shadow: none !important; + box-shadow: none !important; + text-shadow: none !important; + } + + a { + color: inherit !important; + text-decoration: underline !important; + } + + a.bare, a[href^="#"], a[href^="mailto:"] { + text-decoration: none !important; + } + + a[href^="http:"]:not(.bare):after, a[href^="https:"]:not(.bare):after, a[href^="mailto:"]:not(.bare):after { + content: "(" attr(href) ")"; + display: inline-block; + font-size: 0.875em; + padding-left: 0.25em; + } + + abbr[title]:after { + content: " (" attr(title) ")"; + } + + pre, blockquote, tr, img { + page-break-inside: avoid; + } + + thead { + display: table-header-group; + } + + img { + max-width: 100% !important; + } + + p, blockquote, dt, td.content { + font-size: 1em; + orphans: 3; + widows: 3; + } + + h2, h3, #toctitle, .sidebarblock > .content > .title, #toctitle, .sidebarblock > .content > .title { + page-break-after: avoid; + } + + #toc, .sidebarblock, .exampleblock > .content { + background: none !important; + } + + #toc { + border-bottom: 1px solid #ddddd8 !important; + padding-bottom: 0 !important; + } + + .sect1 { + padding-bottom: 0 !important; + } + + .sect1 + .sect1 { + border: 0 !important; + } + + #header > h1:first-child { + margin-top: 1.25rem; + } + + body.book #header { + text-align: center; + } + + body.book #header > h1:first-child { + border: 0 !important; + margin: 2.5em 0 1em 0; + } + + body.book #header .details { + border: 0 !important; + display: block; + padding: 0 !important; + } + + body.book #header .details span:first-child { + margin-left: 0 !important; + } + + body.book #header .details br { + display: block; + } + + body.book #header .details br + span:before { + content: none !important; + } + + body.book #toc { + border: 0 !important; + text-align: left !important; + padding: 0 !important; + margin: 0 !important; + } + + body.book #toc, body.book #preamble, body.book h1.sect0, body.book .sect1 > h2 { + page-break-before: always; + } + + .listingblock code[data-lang]:before { + display: block; + } + + #footer { + background: none !important; + padding: 0 0.9375em; + } + + #footer-text { + color: rgba(0, 0, 0, 0.6) !important; + font-size: 0.9em; + } + + .hide-on-print { + display: none !important; + } + + .print-only { + display: block !important; + } + + .hide-for-print { + display: none !important; + } + + .show-for-print { + display: inherit !important; + } +} diff --git a/extensions/job_management/xml/README.md b/extensions/job_management/xml/README.md new file mode 100644 index 00000000..f1ab5dec --- /dev/null +++ b/extensions/job_management/xml/README.md @@ -0,0 +1 @@ +XML stuff goes here! diff --git a/openapi/schemas/processes-job-management/inputs.yaml b/openapi/schemas/processes-job-management/inputs.yaml new file mode 100644 index 00000000..77bf8df0 --- /dev/null +++ b/openapi/schemas/processes-job-management/inputs.yaml @@ -0,0 +1,3 @@ +type: object +additionalProperties: + $ref: "input.yaml" \ No newline at end of file diff --git a/openapi/schemas/processes-job-management/openeo-process-graph.yaml b/openapi/schemas/processes-job-management/openeo-process-graph.yaml new file mode 100644 index 00000000..ff4cbf18 --- /dev/null +++ b/openapi/schemas/processes-job-management/openeo-process-graph.yaml @@ -0,0 +1,10 @@ +type: object +additionalProperties: + type: object + required: + - process_id + - arguments + properties: + process_id: + type: string + arguments: {} diff --git a/openapi/schemas/processes-job-management/outputs.yaml b/openapi/schemas/processes-job-management/outputs.yaml new file mode 100644 index 00000000..04f0bfe4 --- /dev/null +++ b/openapi/schemas/processes-job-management/outputs.yaml @@ -0,0 +1,3 @@ +type: object +additionalProperties: + $ref: "output.yaml" \ No newline at end of file diff --git a/openapi/schemas/processes-job-management/statusCode.yaml b/openapi/schemas/processes-job-management/statusCode.yaml new file mode 100644 index 00000000..ccdde642 --- /dev/null +++ b/openapi/schemas/processes-job-management/statusCode.yaml @@ -0,0 +1,9 @@ +type: string +nullable: false +enum: + - pending + - accepted + - running + - successful + - failed + - dismissed From ca03fbd72da4d2423905e833154a0cc55d0bbf66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 16:34:40 +0200 Subject: [PATCH 02/29] Fix typos --- .../standard/20-044.presentation.xml | 2154 ----------------- extensions/job_management/standard/20-044.xml | 1087 --------- .../job-management/definition/REQ_get-op.adoc | 4 +- .../definition/REQ_response-body.adoc | 4 +- .../definition/REQ_response-success.adoc | 4 +- .../clause_13_security_considerations.adoc | 8 +- .../sections/clause_2_conformance.adoc | 12 +- 7 files changed, 17 insertions(+), 3256 deletions(-) delete mode 100644 extensions/job_management/standard/20-044.presentation.xml delete mode 100644 extensions/job_management/standard/20-044.xml diff --git a/extensions/job_management/standard/20-044.presentation.xml b/extensions/job_management/standard/20-044.presentation.xml deleted file mode 100644 index 6eb51013..00000000 --- a/extensions/job_management/standard/20-044.presentation.xml +++ /dev/null @@ -1,2154 +0,0 @@ - - - -OGC API - Processes - Part 4: Job Management -http://www.opengis.net/doc/IS/ogcapi-processes-4/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd -Geolabs - -Terradue Srl. - -Computer Research Institute of Montréal (CRIM). - -Gérald Fenoy - -Open Geospatial Consortium -OGC1.0en

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

- -

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

- -

The OGC API - Processes - Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [OGC 18-062r2] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard.

- -

The OGC API - Processes - Part 3: Workflows draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [OGC 18-062r2] with the ability to …​

- -

The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [OGC 18-062r2] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

- -CAUTION

This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion.

-draftDraft2019 -Open Geospatial Consortium -OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementationScopeSymbols and abbreviated termsAbbreviated termsSymbolsContentsIntroductionPrefaceAbstractAcknowledgementsTerms and definitionsTerms, definitions, symbols and abbreviated termsTerms, definitions and symbolsTerms, definitions and abbreviated termsNormative referencesBibliographyPrefaceSectionClauseAnnexAppendixcontinued

No terms and definitions are listed in this document.

-

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

-

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

-

For the purposes of this document, the following additional terms and definitions apply.

-The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.There are no normative references in this document.

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

-

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

-

For the purposes of this document, the terms and definitions given in % additionally apply.

-

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

-

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

-

For the purposes of this document, the terms and definitions given in % and the following additionally apply.

-[NO INFORMATION AVAILABLE](%)%1 and %2%1, and %2%1 or %2%1, or %2%1 and %2%1 or %2%1 from %2%1 to %2%1, %2%1 %2spellout-ordinaldigits-ordinalNOTENoteNote % to entryListDefinition ListFigureDiagramFormulaFormulaTableRequirementRecommendationPermissionBox(NO ID)Recommendation testRequirement testPermission testRecommendations classRequirements classPermissions classAbstract testConformance classKeyExampleExamplewherewhereWhole of textdraftinformativenormativemodifiedadaptedDEPRECATEDSOURCEandAll Parts{{ var1 | ordinal_word: '', '' }} editioneditionversionList of FiguresList of TablesList of RecommendationsJanuaryFebruaryMarchAprilMayJuneJulyAugustSeptemberOctoberNovemberDecemberObligationDangerWarningCautionImportantSafety PrecautionsEditorial NoteSectionClausePartParagraphChapterPageTableAnnexFigureExampleNoteFormulamfncommonsgdualplpreppartadjadvnounverbdeprecatessupersedesnarrowerbroaderequivalentcomparecontrastseesee alsoClauseClausesAnnexAnnexesAppendixAppendixesNoteNotesNote % to entryNotes % to entryListListsFigureFiguresFormulaFormulasTableTablesRequirementRequirementsRecommendationRecommendationsPermissionPermissionsExampleExamplesPartPartsSectionSectionsParagraphParagraphsChapterChaptersPagePagesALTERNATIVESubmittersContributorsRevision historyListingTable of FiguresNo security considerations have been made for this document.Submission DateApproval DatePublication DateAuthorEditorContributorDraftWork Item DraftCandidate SWG DraftCandidate OAB Review DraftCandidate Public RFC DraftCandidate TC Vote DraftApprovedPublishedDeprecatedRescindedRetiredenLatnTable
ats_druhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
_99e940ea-ac12-4895-8c4c-7ab0fba8b43d/conf/dru/deploy/post-op
ats_dru_deploy_post-op/conf/jm/create/post-op
TOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 - -OGC API - Processes - Part 4: Job Management -http://www.opengis.net/doc/IS/ogcapi-processes-4/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd -Geolabs - -Terradue Srl. - -Computer Research Institute of Montréal (CRIM). - -Gérald Fenoy - -Open Geospatial Consortium -OGC1.0enLatnOGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. - -The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard. - -The OGC API - Processes - Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard. - -The OGC API - Processes - Part 3: Workflows draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to …​ - -The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable. - -This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion. -draft2019 -Open Geospatial Consortium -OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementationats_druhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management_99e940ea-ac12-4895-8c4c-7ab0fba8b43d/conf/dru/deploy/post-opats_dru_deploy_post-op/conf/jm/create/post-opTOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 - - - -Copyright notice -Copyright © 2019 Open Geospatial Consortium To obtain additional rights of use, visit - - - -Note -Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. - -Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation. - - - - - - -License Agreement -Use of this document is subject to the license agreement at - - - - - - -Notice for Drafts -This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard. - -Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation. - - - - - - -Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site: - - -AbstractOGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. - -The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard. - -The OGC API — Processes — Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard. - -The OGC API — Processes — Part 3: Workflows draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to …​ - -The OGC API — Processes — Part 4: Job Management draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable. - -This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion. - -Security Considerations -See OGC API — Processes — Part 1: Core, Clause 10.4. - -Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations. - -Users making modifications to process resources need to: - -Be authenticated, - -Have “modification privileges” on the processes offered through the API, - -Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints. - - - -The API definition, as defined in Clause 7.3 from , must reflect this in the resource paths and their available methods. - -Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance: - -The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation). - -A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation. - - -Example OpenAPI definition with security requirements -The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user. - -{ - "openapi" : "3.0.3", - "info" : { - "title" : "My API", - "description" : "This API ...", - "version" : "1.0.0" - }, - "servers" : [ { - "url" : "https://example.com/api/v1" - } ], - "security" : [ { - "JWT" : [ ], - "api_key": [ ] - } ], - "paths" : { }, - "components" : { - "securitySchemes": { - "JWT" : { - "type" : "http", - "scheme" : "bearer", - "bearerFormat" : "JWT" - }, - "api_key" : { - "type": "apiKey", - "name": "X-API-Key", - "in": "header" - } - } - } -} - - - -If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error. - -In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided. - -Unauthorized requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | ----------------------------------------------------------->| - | | - | HTTP/1.1 401 Unauthorized | - | Date: Mon, 23 May 2022 11:18:45 GMT | - | WWW-Authenticate: Bearer realm="my-realm" | - | WWW-Authenticate: ApiKey header="X-API-Key" | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 86 | - | | - | { | - | "status": 401, | - | "title": "Unauthorized", | - | "detail": "HTTP 401 Unauthorized" | - | } | - | <-----------------------------------------------------------| - - -HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023) - - -If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”). - -Forbidden requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | Host: example.com | - | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | - |------------------------------------------------------------------>| - | | - | HTTP/1.1 403 Forbidden | - | Date: Mon, 23 May 2022 11:18:55 GMT | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 80 | - | | - | { | - | "status" : 403, | - | "title" : "Forbidden", | - | "detail" : "HTTP 403 Forbidden" | - | } | - |<------------------------------------------------------------------| - - -However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation. - -Submitters -All questions regarding this submission should be directed to the editors or the submitters: - -Name -Affiliation - -Gérald Fenoy (editor) -GeoLabs - - - - - -Scope -The OGC API — Processes — Part 4 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [] and defines the behavior of a server that supports the ability to create jobs without implying the process execution starts right away. - -Specifically, the Processes Part 4 Standard specifies: - -How to manage job. - -How to handle provenenance information associated with a job. - - - - - -Conformance -The OGC API — Processes — Part 4 Standard defines the following requirements classes. - -The main requirements class is: - -Job Management. - - - -This class specifies requirements that any Web API implementing Processes Part 4 must conform with. - -The Job Management class does mandate a specific encoding and format for the job definition. However, the Part 4 extension defines the following conformance class: - -OpenEO graph - - - -The OpenEO grap class defines that jobs can be created from an OpenEO graph. - -The provenance information associated with a job is not mandated to be supported by the server. A dedicated requirements class Provenance is defined for this feature. - -The standardization target for all Conformance class defined in this Standard is “Web API”. - -Conformance with this Standard shall be checked using all the relevant tests specified in of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site. - - - - - -Terms, definitions and abbreviated termsThis document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2. -This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec. -For the purposes of this document, the following additional terms and definitions apply. - - -Terms and definitions - -Execution unit - - -A component containing a process that an implementation of the Processes API Part 1 can run. - - - -Deploy - - -Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard. - - - -Replace - - -Replace refers to upgrading a deployed process from a Processes API implementation. - - - -Undeploy - - -Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process. - - - - -Abbreviated terms -CWLCommon Workflow Language - -DRUDeploy, Replace, Undeploy - - - - -Conventions and background -See , Clause 5. - - - -Requirements Class “Job Management” - -Overview - Web APIOGC API — Processes — Part 1: Core, Conformance Class ‘core’RFC 2616 (HTTP/1.1)label - - -A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs. - -The HTTP POST method is used to create new jobs. - -The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint. - -Finally, the HTTP POST method is used to start a job. - -Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standard does mandate that a specific jobs schema be used. However, this extension defines the following conformance classe: - -OpenEO Process Graph, that enables support for OpenEO-encoded jobs definition. - - - - -HTTP status codes -Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code. - -The Status Codes listed in are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations. - - -Typical HTTP status codes -Status code -Description - -200 -A successful request. -201 -The server has successfully completed the operation and a new resource has been created. -202 -The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. -204 -A successful request with no additional content to send in the response. -400 -The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value. -401 -The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource. -403 -The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource. -404 -The requested resource does not exist on the server. For example, a path parameter had an incorrect value. -405 -The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests. -406 -Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource. -412 -The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server. -413 -The server is refusing to process the request because the request content is larger than the server is willing or able to process. -415 -The server is refusing to service the request because the content is in a format not supported by this method on the target resource. -422 -The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing. -500 -An internal error occurred in the server. - -Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”. - - - - -More specific guidance is provided for each resource, where applicable. - - label/per/core/additional-status-codesServers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in . - - - -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. - - - -Cross-origin requests -See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS). - - - - -Creating a new job - -Sequence diagram -The following diagram illustrates the sequence diagram for deploying a new process to the API: - -Client Server - | | - | POST /jobs HTTP/1.1 | - | Content-Type: application/json | - | | - |------------------------------------------------------------>| - | | - | HTTP/1.1 201 Created | - | Location: /jobs/{jobId} | - |<------------------------------------------------------------| - - - - -Operation - label/req/job-management/create/post-opThe server SHALL support the HTTP POST operation at the path /jobs. - - - - - -Request body - -Overview - label/req/job-management/create/bodyThe body of the POST request SHALL be in JSON format. - - - - label/per/job-management/create/bodyA server MAY support any encoding in the body of a HTTP POST operation. - - - - label/req/job-management/create/content-typeThe Content-Type header SHALL be used to declare the media type of the request. - - - -See section 3.1.1.5 of RFC 7231 for details. - - - -OGC API — Processes — Workflow Execute Request body - label/rec/job-management/create/body-ogcapi-processesIf the job can be encoded as an OGC API — Processes — Workflow Execute Request, implementation SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding. - - - - - -OpenEO Process Graph body - label/rec/job-management/create/body-openeoIf the job can be encoded as an OpenEO graph, implementation SHOULD consider supporting the OpenEO graph encoding. - - - - - - -Response - label/req/job-management/create/response-jobidIf the operation completes, the server SHALL generate a job identifier (i.e. {jobId}) for the created job. - - - - label/req/job-management/create/response-successA successful execution of the operation SHALL be reported as a response with a HTTP status code 201. -A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /jobs/{jobId}). - - - - label/req/job-management/create/response-bodyThe response SHALL include a body that contains a status information of the created job conforms to the statusInfo.yaml schema. -The response SHALL contains a pending status code and the jobId property that contains the job identifier. - - - - - -Exceptions -See for general guidance. - -If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from . - - - - -Updating an existing job - -Sequence diagram -The following diagram illustrates the sequence diagram for updating a -previously created job. The identifier of the job does not change.The new job definition replaces the old job definition. Version control is not discussed in this Standard. - - - - -Client Server - | | - | PUT /jobs/{jobId} HTTP/1.1 | - | Content-Type: application/json | - | | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -Operation - label/req/job-management/update/put-opFor every created jobs (path ‘/jobs/{jobId}’), the server SHALL support the HTTP PUT operation. -The parameter ‘jobId’ is each ‘jobID’ property in the jobs list response (JSONPath: $.jobs[*].jobID). - - - - - -Request body - - - -Overview - label/req/job-management/update/body*The body of a PUT request SHALL be in JSON format. - - - - label/per/job-management/update/bodyA server MAY support any encoding in the body of a HTTP PUT operation. - - - - label/req/job-management/update/content-typeAs per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes. - - - - -OGC API — Processes — Workflow Execute Request body - label/rec/job-management/update/body-ogcapi-processesIf a job can be created from an rc_ogcapi-processes,OGC API — Processes — Workflow Execute Request>>, implementations SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding. - - - - - -OpenEO Process Graph body - label/rec/job-management/update/body-openeoIf a job can be created from an OpenEO graph, implementations SHOULD consider supporting the OpenEO graph encoding. - - - - - - -Response - label/req/job-management/update/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204. -If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202. - - - -The status code depends on the server. If the server has replaced the job, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content). - -If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client. - - - -Exceptions -See for general guidance. - -If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from . - -If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from . - - - - -Staring a job - -Sequence diagram -The following diagram illustrates the sequence diagram for starting the execution of a previously created jobs. - -Client Server - | | - | POST /jobs/{jobId} HTTP/1.1 | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -Operation - label/req/job-management/start/start-opFor every created jobs (path: /jobs/{jobId}/results), the server SHALL support the HTTP POST operation. -The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). - - - - - -Response - label/req/job-management/start/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’. -A response SHALL be a document that conforms to statusInfo.yaml. - - - - - -Exceptions -See HTTP status codes for general guidance. - -If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from . - - - - -Job definition -For every job, it is possible to retrieve its original definition. It corresponds to the request’s body used to create or update the jobs. - - -Operation - label/req/deploy-replace-undeploy/package/get-opFor every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package. -The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id). - - - - - -Response - -Overview - label/req/deploy-replace-undeploy/package/response-successA successful access to the resource SHALL be reported as a response with a HTTP status code 200. - - - - label/req/deploy-replace-undeploy/package/response-bodyA response with HTTP status code 200 SHALL include a body that contains the request body used to create or update the job. - - - - - - -Exceptions -See HTTP status codes for general guidance. - -If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from . - - - - - -Requirements Class “OGC API — Process — Workflow Execute Request” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel - - -This requirements class defines that the OGC API — Process — Workflow Execute Request is supported as an encoding for job definitions. - - - -OGC API — Processes - -Overview - label/req/ogcapi-processes/schemaAn OGC API - Processes document SHALL be based upon the JSON schema execute-workflow.yaml. - - - - - - -Create - -OGC API — Processes body - label/req/ogcapi-processes/create/bodyThe body of the POST request SHALL be based upon the OpenAPI 3.0 schema execute-workflows.yaml -The media type application/json SHALL be used to indicate that request body contains a processes description encoded as an OGC API — Processes. - - - - - - -Update - -OGC API — Processes body - label/req/ogcapi-processes/update/bodyThe media type application/ogcapi-processes+json SHALL be used to indicate that request body contains a job encoded as an OGC API — Processes. - - - - - - -Job definition - -OGC API — Processes content - label/req/ogcapi-processes/definition/response-bodyA response with HTTP status code 200 SHALL include a body that contains the OGC API — Processes to use to deploy the process. - - - - - - - -Requirements Class “OpenEO Process Graph” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel - - -This requirements class defines that the server supports the OpenEO Process Graph as an encoding for job definitions. - - - -OpenEO Process Graph - -Overview - label/req/openeo/schemaAn OpenEO Process Graph document SHALL be based upon the JSON schema . - - - - -Schema for OpenEO Process Graph -type: object -additionalProperties: - type: object - required: - - process_id - - arguments - properties: - process_id: - type: string - arguments: {} - - - - - -Create - -OpenEO body - label/req/openeo/create/bodyThe media type application/openeo+json SHALL be used to indicate that request body contains a processes description encoded as an OpenEO Process Graph. - - - - - - -Update - -OpenEO body - label/req/openeo/update/bodyThe media type application/openeo+json SHALL be used to indicate that request body contains a job encoded as an OpenEO Process Graph. - - - - - - -Job definition - -OpenEO content - label/req/openeo/definition/response-bodyA response with HTTP status code 200 SHALL include a body that contains the OpenEO Process Graph to use to deploy the process. - - - - - - - -Requirements Class “Quotation” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeolabel - - - - - -Requirements Class “Provenance” - -Overview -This requirements class defines how to allow client application accessing the provenance of a job run. - - Web APIOGC API — Processes — Part 1: Corelabel - - - - -Additional endpoints - -Inputs -The server MUST provide an endpoint to retrieve the inputs of a job run. - - -Operation - label/req/provenance/inputs/get-opFor every created jobs (path: /jobs/{jobId}/inputs), the server SHALL support the HTTP GET operation. -The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). - - - - - -Response - label/req/provenance/inputs/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’. -The response SHALL contains a JSON document that conforms to the schema inputs.yaml. - - - - - - -Outputs -The server MUST provide an endpoint to retrieve the outputs of a job run. - - -Operation - label/req/provenance/outputs/get-opFor every created jobs (path: /jobs/{jobId}/outputs), the server SHALL support the HTTP GET operation. -The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). - - - - - -Response - label/req/provenance/outputs/responseA successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’. -The response SHALL contains a JSON document that conforms to the schema outputs.yaml. - - - - - - -Run -The server MUST provide an endpoint to retrieve the run of a job. - - -Operation - label/req/provenance/run/get-opFor every created jobs (path: /jobs/{jobId}/run), the server SHALL support the HTTP GET operation. -The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID). - - - - - - - - -OpenAPI 3.0 -See , Clause 9. - - - -Media Types -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 - - - -Additional CWL media types that would typically be used in a server that supports CWL are: - -application/cwl - - - - - - - - - - - - -Abstract Test Suite - -Introduction -OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested. - -The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”. - - - -Conformance Class Deploy, Replace, Undeploy - -Job Managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementTarget TypeWeb API /conf/dru/deploy/post-op - - - - -Create operation - /conf/jm/create/post-optarget/req/job-management/create/post-opValidate that the server support HTTP POST operation at the path /jobs/ -Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/job-list” link on the landing page as well as for the {root}/jobs path. - -Issue an HTTP POST request for each path. - -Validate that the response header does not contain 405 Method not allowed - - - - - - - -Revision History -Date -Release -Editor -Primary clauses modified -Description - -2024-08-22 -None -Gérald Fenoy -all -Boostraping the document - - - -Normative referencesThe following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. - - 2024-08-29 - -OGC API - - -Processes - - -Part 1: Core - - -OGC API — Processes — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 - https://docs.ogc.org/is/18-062r2/18-062r2.html - OGC 18-062r2OGC 18-062r2 - - 2021-12-20 - - - - - - Benjamin Pross - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - -Open Geospatial Consortium - - - - 2 - en - Latn - The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. - -By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. - -The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. - -The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. - - -Pross, B.: OGC 18-062, OGC API — Processes — Part 2: Deploy, Replace, UndeployOGC 20-044OGC 20-04420-044 - - 2024-08-29 - -OGC API - - -Processes - - -Part 1: Core - - -OGC API — Processes — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 - https://docs.ogc.org/is/18-062r2/18-062r2.html - OGC 18-062r2OGC 18-062r2 - - 2021-12-20 - - - - - - Benjamin Pross - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - -Open Geospatial Consortium - - - - 2 - en - Latn - The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. - -By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. - -The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. - -The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. - - - - 2024-08-29 - -OGC API - - -Features - - -Part 1: Core - - -OGC API — Features — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0 - https://docs.ogc.org/is/17-069r3/17-069r3.html - OGC 17-069r3OGC 17-069r3 - - 2019-10-07 - - - - - - Clemens Portele - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - - Charles Heazel - - - - - - - -Open Geospatial Consortium - - - - 3 - en - Latn - OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. - -The OGC API family of standards is organized by resource type. This standard specifies the fundamental API building blocks for interacting with features. The spatial data community uses the term ‘feature’ for things in the real world that are of interest. - - - -Bibliography - OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: -. - OpenAPI Specification 3.0.2OpenAPI Specification 3.0.2 - 3.0.2 - - Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. - [2] - - OpenEO: OpenEO Developers API Reference / Process Graphs. - [3] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - : - - - - -sourcecode table td { padding: 5px; } -sourcecode table pre { margin: 0; } -sourcecode, sourcecode .w { - color: #444444; -} -sourcecode .cp { - color: #CC00A3; -} -sourcecode .cs { - color: #CC00A3; -} -sourcecode .c, sourcecode .ch, sourcecode .cd, sourcecode .cm, sourcecode .cpf, sourcecode .c1 { - color: #1E90FF; -} -sourcecode .kc { - color: #C34E00; -} -sourcecode .kd { - color: #0000FF; -} -sourcecode .kr { - color: #007575; -} -sourcecode .k, sourcecode .kn, sourcecode .kp, sourcecode .kt, sourcecode .kv { - color: #0000FF; -} -sourcecode .s, sourcecode .sb, sourcecode .sc, sourcecode .ld, sourcecode .sd, sourcecode .s2, sourcecode .se, sourcecode .sh, sourcecode .si, sourcecode .sx, sourcecode .sr, sourcecode .s1, sourcecode .ss { - color: #009C00; -} -sourcecode .sa { - color: #0000FF; -} -sourcecode .nb, sourcecode .bp { - color: #C34E00; -} -sourcecode .nt { - color: #0000FF; -} - - - - -Copyright notice -

Copyright © 2019 Open Geospatial Consortium
To obtain additional rights of use, visit

- - - -Note -

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

- -

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

- - - - - - -License Agreement -

Use of this document is subject to the license agreement at

- - - - - - -Notice for Drafts -

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

- -

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

- - - - - - -

Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site:

- - -Contents -I.<tab/>Abstract

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

- -

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

- -

The OGC API — Processes — Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [OGC 18-062r2] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard.

- -

The OGC API — Processes — Part 3: Workflows draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [OGC 18-062r2] with the ability to …​

- -

The OGC API — Processes — Part 4: Job Management draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [OGC 18-062r2] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

- -CAUTION

This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion.

- -II.<tab/>Keywords -

The following are keywords to be used by search engines and document catalogues.

-

process, collection, instance, spatial, data, openapi, transactions, insert, update, delete, add, remove, deploy, undeploy, REST, PUT, POST, DELETE

 - -III.<tab/>Security Considerations -

See OGC API — Processes — Part 1: Core, Clause 10.4.

- -

Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations.

- -

Users making modifications to process resources need to:

- -

  1. Be authenticated,

    -
    2. -

  2. Have “modification privileges” on the processes offered through the API,

    -
    3. -

  3. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints.

    -
    4. -
- -

The API definition, as defined in Clause 7.3 from OGC 18-062r2, must reflect this in the resource paths and their available methods.

- -

Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance:

- -

The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation).

- -

A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation.

- - -Example — Example OpenAPI definition with security requirements -

The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user.

- -{ - "openapi" : "3.0.3", - "info" : { - "title" : "My API", - "description" : "This API ...", - "version" : "1.0.0" - }, - "servers" : [ { - "url" : "https://example.com/api/v1" - } ], - "security" : [ { - "JWT" : [ ], - "api_key": [ ] - } ], - "paths" : { }, - "components" : { - "securitySchemes": { - "JWT" : { - "type" : "http", - "scheme" : "bearer", - "bearerFormat" : "JWT" - }, - "api_key" : { - "type": "apiKey", - "name": "X-API-Key", - "in": "header" - } - } - } -} - - - -

If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.

- -

In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided.

- -Listing 1 — Unauthorized requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | ----------------------------------------------------------->| - | | - | HTTP/1.1 401 Unauthorized | - | Date: Mon, 23 May 2022 11:18:45 GMT | - | WWW-Authenticate: Bearer realm="my-realm" | - | WWW-Authenticate: ApiKey header="X-API-Key" | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 86 | - | | - | { | - | "status": 401, | - | "title": "Unauthorized", | - | "detail": "HTTP 401 Unauthorized" | - | } | - | <-----------------------------------------------------------| - - -NOTE

HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023)

- - -

If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”).

- -Listing 2 — Forbidden requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | Host: example.com | - | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | - |------------------------------------------------------------------>| - | | - | HTTP/1.1 403 Forbidden | - | Date: Mon, 23 May 2022 11:18:55 GMT | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 80 | - | | - | { | - | "status" : 403, | - | "title" : "Forbidden", | - | "detail" : "HTTP 403 Forbidden" | - | } | - |<------------------------------------------------------------------| - - -

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

- -IV.<tab/>Submitting Organizations -

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

-
  • Geolabs
    • -
  • Terradue Srl.
    • -
  • Computer Research Institute of Montréal (CRIM).
- - -V.<tab/>Submitters -

All questions regarding this submission should be directed to the editors or the submitters:

- - - - - - - -
NameAffiliation
Gérald Fenoy (editor)GeoLabs
- - - -1.<tab/>Scope -

The OGC API — Processes — Part 4 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [OGC 18-062r2] and defines the behavior of a server that supports the ability to create jobs without implying the process execution starts right away.

- -

Specifically, the Processes Part 4 Standard specifies:

- -

  • How to manage job.

    -
    • -

  • How to handle provenenance information associated with a job.

    -
    • -
- - - -2.<tab/>Conformance -

The OGC API — Processes — Part 4 Standard defines the following requirements classes.

- -

The main requirements class is:

- -

  • Job Management.

    -
    • -
- -

This class specifies requirements that any Web API implementing Processes Part 4 must conform with.

- -

The Job Management class does mandate a specific encoding and format for the job definition. However, the Part 4 extension defines the following conformance class:

- -

  • OpenEO graph

    -
    • -
- -

The OpenEO grap class defines that jobs can be created from an OpenEO graph.

- -

The provenance information associated with a job is not mandated to be supported by the server. A dedicated requirements class Provenance is defined for this feature.

- -

The standardization target for all Conformance class defined in this Standard is “Web API”.

- -

Conformance with this Standard shall be checked using all the relevant tests specified in Annex A of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.

- - - - - -4.<tab/>Terms, definitions and abbreviated terms

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

-

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

-

For the purposes of this document, the following additional terms and definitions apply.

- - -4.1.<tab/>Terms and definitions -4.1.1.Execution unit -

A component containing a process that an implementation of the Processes API Part 1 can run.

 - - -4.1.2.Deploy -

Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard.

 - - -4.1.3.Replace -

Replace refers to upgrading a deployed process from a Processes API implementation.

 - - -4.1.4.Undeploy -

Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process.

 - - - - -4.2.<tab/>Abbreviated terms -
CWL

Common Workflow Language

-
-
DRU

Deploy, Replace, Undeploy

-
- - - -5.<tab/>Conventions and background -

See OGC 18-062r2, Clause 5.

- - - -6.<tab/>Requirements Class “Job Management” - -6.1.<tab/>Overview - -

Requirements class 1

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core, Conformance Class ‘core’
RFC 2616 (HTTP/1.1)
Label
- -

A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs.

- -

The HTTP POST method is used to create new jobs.

- -

The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint.

- -

Finally, the HTTP POST method is used to start a job.

- -

Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standard does mandate that a specific jobs schema be used. However, this extension defines the following conformance classe:

- -

  • OpenEO Process Graph, that enables support for OpenEO-encoded jobs definition.

    -
    • -
- - -6.1.1.<tab/>HTTP status codes -

Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code.

- -

The Status Codes listed in Table 1 are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in Table 1 are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations.

- - -Table 1 — Typical HTTP status codes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -NOTE

Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”.

-
Status codeDescription
200A successful request.
201The server has successfully completed the operation and a new resource has been created.
202The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
204A successful request with no additional content to send in the response.
400The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.
401The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource.
404The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
405The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.
406Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource.
412The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server.
413The server is refusing to process the request because the request content is larger than the server is willing or able to process.
415The server is refusing to service the request because the content is in a format not supported by this method on the target resource.
422The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing.
500An internal error occurred in the server.
- - - -

More specific guidance is provided for each resource, where applicable.

- - -

Permission 1

Label/per/core/additional-status-codes
A

Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in Table 1.

-
- -

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.

- - - -6.1.2.<tab/>Cross-origin requests -

See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).

- - - - -6.2.<tab/>Creating a new job - -6.2.1.<tab/>Sequence diagram -

The following diagram illustrates the sequence diagram for deploying a new process to the API:

- -Listing 3Client Server - | | - | POST /jobs HTTP/1.1 | - | Content-Type: application/json | - | | - |------------------------------------------------------------>| - | | - | HTTP/1.1 201 Created | - | Location: /jobs/{jobId} | - |<------------------------------------------------------------| - - - - -6.2.2.<tab/>Operation - -

Requirement 1

Label/req/job-management/create/post-op
A

The server SHALL support the HTTP POST operation at the path /jobs.

-
- - - -6.2.3.<tab/>Request body - -6.2.3.1.<tab/>Overview - -

Requirement 2

Label/req/job-management/create/body
A

The body of the POST request SHALL be in JSON format.

-
- - -

Permission 2

Label/per/job-management/create/body
A

A server MAY support any encoding in the body of a HTTP POST operation.

-
- - -

Requirement 3

Label/req/job-management/create/content-type
A

The Content-Type header SHALL be used to declare the media type of the request.

-
- -

See section 3.1.1.5 of RFC 7231 for details.

- - - -6.2.3.2.<tab/>OGC API — Processes — Workflow Execute Request body - -

Recommendation 1

Label/rec/job-management/create/body-ogcapi-processes
A

If the job can be encoded as an OGC API — Processes — Workflow Execute Request, implementation SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

-
- - - -6.2.3.3.<tab/>OpenEO Process Graph body - -

Recommendation 2

Label/rec/job-management/create/body-openeo
A

If the job can be encoded as an OpenEO graph, implementation SHOULD consider supporting the OpenEO graph encoding.

-
- - - - -6.2.4.<tab/>Response - -

Requirement 4

Label/req/job-management/create/response-jobid
A

If the operation completes, the server SHALL generate a job identifier (i.e. {jobId}) for the created job.

-
- - -

Requirement 5

Label/req/job-management/create/response-success
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code 201.

-
B

A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /jobs/{jobId}).

-
- - -

Requirement 6

Label/req/job-management/create/response-body
A

The response SHALL include a body that contains a status information of the created job conforms to the statusInfo.yaml schema.

-
B

The response SHALL contains a pending status code and the jobId property that contains the job identifier.

-
- - - -6.2.5.<tab/>Exceptions -

See Clause 6.1.1 for general guidance.

- -

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from OGC 20-044.

- - - - -6.3.<tab/>Updating an existing job - -6.3.1.<tab/>Sequence diagram -

The following diagram illustrates the sequence diagram for updating a -previously created job. The identifier of the job does not change.NOTE

The new job definition replaces the old job definition. Version control is not discussed in this Standard.

-

- - - -Listing 4Client Server - | | - | PUT /jobs/{jobId} HTTP/1.1 | - | Content-Type: application/json | - | | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -6.3.2.<tab/>Operation - -

Requirement 7

Label/req/job-management/update/put-op
A

For every created jobs (path ‘/jobs/{jobId}’), the server SHALL support the HTTP PUT operation.

-
B

The parameter ‘jobId’ is each ‘jobID’ property in the jobs list response (JSONPath: $.jobs[*].jobID).

-
- - - -6.3.3.<tab/>Request body - - - -6.3.4.<tab/>Overview - -

Requirement 8

Label/req/job-management/update/body*
A

The body of a PUT request SHALL be in JSON format.

-
- - -

Permission 3

Label/per/job-management/update/body
A

A server MAY support any encoding in the body of a HTTP PUT operation.

-
- - -

Requirement 9

Label/req/job-management/update/content-type
A

As per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes.

-
- - -6.3.4.1.<tab/>OGC API — Processes — Workflow Execute Request body - -

Recommendation 3

Label/rec/job-management/update/body-ogcapi-processes
A

If a job can be created from an rc_ogcapi-processes,OGC API — Processes — Workflow Execute Request>>, implementations SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

-
- - - -6.3.4.2.<tab/>OpenEO Process Graph body - -

Recommendation 4

Label/rec/job-management/update/body-openeo
A

If a job can be created from an OpenEO graph, implementations SHOULD consider supporting the OpenEO graph encoding.

-
- - - - -6.3.5.<tab/>Response - -

Requirement 10

Label/req/job-management/update/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204.

-
B

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

-
- -

The status code depends on the server. If the server has replaced the job, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content).

- -

If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client.

- - - -6.3.6.<tab/>Exceptions -

See Clause 6.1.1 for general guidance.

- -

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from OGC 20-044.

- -

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from OGC 18-062r2.

- - - - -6.4.<tab/>Staring a job - -6.4.1.<tab/>Sequence diagram -

The following diagram illustrates the sequence diagram for starting the execution of a previously created jobs.

- -Listing 5Client Server - | | - | POST /jobs/{jobId} HTTP/1.1 | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -6.4.2.<tab/>Operation - -

Requirement 11

Label/req/job-management/start/start-op
A

For every created jobs (path: /jobs/{jobId}/results), the server SHALL support the HTTP POST operation.

-
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

-
- - - -6.4.3.<tab/>Response - -

Requirement 12

Label/req/job-management/start/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

-
B

A response SHALL be a document that conforms to statusInfo.yaml.

-
- - - -6.4.4.<tab/>Exceptions -

See HTTP status codes for general guidance.

- -

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from OGC 18-062r2.

- - - - -6.5.<tab/>Job definition -

For every job, it is possible to retrieve its original definition. It corresponds to the request’s body used to create or update the jobs.

- - -6.5.1.<tab/>Operation - -

Requirement 13

Label/req/deploy-replace-undeploy/package/get-op
A

For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package.

-
B

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

-
- - - -6.5.2.<tab/>Response - -6.5.2.1.<tab/>Overview - -

Requirement 14

Label/req/deploy-replace-undeploy/package/response-success
A

A successful access to the resource SHALL be reported as a response with a HTTP status code 200.

-
- - -

Requirement 15

Label/req/deploy-replace-undeploy/package/response-body
A

A response with HTTP status code 200 SHALL include a body that contains the request body used to create or update the job.

-
- - - - -6.5.3.<tab/>Exceptions -

See HTTP status codes for general guidance.

- -

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from OGC 18-062r2.

- - - - - -7.<tab/>Requirements Class “OGC API — Process — Workflow Execute Request” - -7.1.<tab/>Overview - -

Requirements class 2

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-management
Label
- -

This requirements class defines that the OGC API — Process — Workflow Execute Request is supported as an encoding for job definitions.

- - - -7.2.<tab/>OGC API — Processes - -7.2.1.<tab/>Overview - -

Requirement 16

Label/req/ogcapi-processes/schema
A

An OGC API - Processes document SHALL be based upon the JSON schema execute-workflow.yaml.

-
- - - - -7.3.<tab/>Create - -7.3.1.<tab/>OGC API — Processes body - -

Requirement 17

Label/req/ogcapi-processes/create/body
A

The body of the POST request SHALL be based upon the OpenAPI 3.0 schema execute-workflows.yaml

-
B

The media type application/json SHALL be used to indicate that request body contains a processes description encoded as an OGC API — Processes.

-
- - - - -7.4.<tab/>Update - -7.4.1.<tab/>OGC API — Processes body - -

Requirement 18

Label/req/ogcapi-processes/update/body
A

The media type application/ogcapi-processes+json SHALL be used to indicate that request body contains a job encoded as an OGC API — Processes.

-
- - - - -7.5.<tab/>Job definition - -7.5.1.<tab/>OGC API — Processes content - -

Requirement 19

Label/req/ogcapi-processes/definition/response-body
A

A response with HTTP status code 200 SHALL include a body that contains the OGC API — Processes to use to deploy the process.

-
- - - - - -8.<tab/>Requirements Class “OpenEO Process Graph” - -8.1.<tab/>Overview - -

Requirements class 3

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-management
Label
- -

This requirements class defines that the server supports the OpenEO Process Graph as an encoding for job definitions.

- - - -8.2.<tab/>OpenEO Process Graph - -8.2.1.<tab/>Overview - -

Requirement 20

Label/req/openeo/schema
A

An OpenEO Process Graph document SHALL be based upon the JSON schema .

-
- -Listing 6 — - Schema for OpenEO Process Graph - - -type: object -additionalProperties: - type: object - required: - - process_id - - arguments - properties: - process_id: - type: string - arguments: {} - - - - - -8.3.<tab/>Create - -8.3.1.<tab/>OpenEO body - -

Requirement 21

Label/req/openeo/create/body
A

The media type application/openeo+json SHALL be used to indicate that request body contains a processes description encoded as an OpenEO Process Graph.

-
- - - - -8.4.<tab/>Update - -8.4.1.<tab/>OpenEO body - -

Requirement 22

Label/req/openeo/update/body
A

The media type application/openeo+json SHALL be used to indicate that request body contains a job encoded as an OpenEO Process Graph.

-
- - - - -8.5.<tab/>Job definition - -8.5.1.<tab/>OpenEO content - -

Requirement 23

Label/req/openeo/definition/response-body
A

A response with HTTP status code 200 SHALL include a body that contains the OpenEO Process Graph to use to deploy the process.

-
- - - - - -9.<tab/>Requirements Class “Quotation” - -9.1.<tab/>Overview - -

Requirements class 4

Obligationrequirement
Target typeWeb API
PrerequisitesOGC API — Processes — Part 1: Core
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-management
http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeo
Label
- - - - -10.<tab/>Requirements Class “Provenance” - -10.1.<tab/>Overview -

This requirements class defines how to allow client application accessing the provenance of a job run.

- - -

Requirements class 5

Obligationrequirement
Target typeWeb API
PrerequisiteOGC API — Processes — Part 1: Core
Label
- - - -10.2.<tab/>Additional endpoints - -10.2.1.<tab/>Inputs -

The server MUST provide an endpoint to retrieve the inputs of a job run.

- - -10.2.1.1.<tab/>Operation - -

Requirement 24

Label/req/provenance/inputs/get-op
A

For every created jobs (path: /jobs/{jobId}/inputs), the server SHALL support the HTTP GET operation.

-
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

-
- - - -10.2.1.2.<tab/>Response - -

Requirement 25

Label/req/provenance/inputs/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

-
B

The response SHALL contains a JSON document that conforms to the schema inputs.yaml.

-
- - - - -10.2.2.<tab/>Outputs -

The server MUST provide an endpoint to retrieve the outputs of a job run.

- - -10.2.2.1.<tab/>Operation - -

Requirement 26

Label/req/provenance/outputs/get-op
A

For every created jobs (path: /jobs/{jobId}/outputs), the server SHALL support the HTTP GET operation.

-
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

-
- - - -10.2.2.2.<tab/>Response - -

Requirement 27

Label/req/provenance/outputs/response
A

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

-
B

The response SHALL contains a JSON document that conforms to the schema outputs.yaml.

-
- - - - -10.2.3.<tab/>Run -

The server MUST provide an endpoint to retrieve the run of a job.

- - -10.2.3.1.<tab/>Operation - -

Requirement 28

Label/req/provenance/run/get-op
A

For every created jobs (path: /jobs/{jobId}/run), the server SHALL support the HTTP GET operation.

-
B

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

-
- - - - - - -11.<tab/>OpenAPI 3.0 -

See OGC 18-062r2, Clause 9.

- - - -12.<tab/>Media Types -

See OGC 18-062r2, Clause 13.

- -

Additional JSON media types that would typically be used in a server that supports JSON are:

- -

  • application/ogcapppkg+json

    -
    • -

  • application/cwl+json

    -
    • -
- -

Additional CWL media types that would typically be used in a server that supports CWL are:

- -

  • application/cwl

    -
    • -
- - - - - - - - - - -3.<tab/>Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

-Benjamin Pross, Panagiotis (Peter) A. Vretanos: OGC 18-062r2, OGC API — Processes — Part 1: Core. Open Geospatial Consortium (2021). http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0.http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0https://docs.ogc.org/is/18-062r2/18-062r2.htmlOGC 18-062r2OGC 18-062r2 -Pross, B.: OGC 18-062, OGC API — Processes — Part 2: Deploy, Replace, UndeployOGC 20-044OGC 20-04420-044 -Benjamin Pross, Panagiotis (Peter) A. Vretanos: OGC 18-062r2, OGC API — Processes — Part 1: Core. Open Geospatial Consortium (2021). http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0.http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0https://docs.ogc.org/is/18-062r2/18-062r2.htmlOGC 18-062r2OGC 18-062r2 -Clemens Portele, Panagiotis (Peter) A. Vretanos, Charles Heazel: OGC 17-069r3, OGC API — Features — Part 1: Core. Open Geospatial Consortium (2019). http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0.http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0https://docs.ogc.org/is/17-069r3/17-069r3.htmlOGC 17-069r3OGC 17-069r3 - -<strong>Annex A</strong><br/>(normative)<br/><strong>Abstract Test Suite</strong> - -A.1.<tab/>Introduction -

OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested.

- -

The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”.

- - - -A.2.<tab/>Conformance Class Deploy, Replace, Undeploy - - - -

Conformance class A.1: Job Management

Identifierhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
Subjecthttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
Target TypeWeb API
Conformance testConformance test A.1-1: /conf/dru/deploy/post-op
- - -A.2.1.<tab/>Create operation - - - -

Abstract test A.1

Identifier/conf/jm/create/post-op
Requirement/req/job-management/create/post-op
Test purpose

Validate that the server support HTTP POST operation at the path /jobs/

-
Test method

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/job-list” link on the landing page as well as for the {root}/jobs path.

    -
    2. -

  2. Issue an HTTP POST request for each path.

    -
    3. -

  3. Validate that the response header does not contain 405 Method not allowed

    -
    4. -
-
- - - -<strong>Annex B</strong><br/>(informative)<br/><strong>Revision History</strong> - - - - - - - - - - - - -
DateReleaseEditorPrimary clauses modifiedDescription
2024-08-22NoneGérald FenoyallBoostraping the document
- -Bibliography - OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: -.[1] - OpenAPI Specification 3.0.2OpenAPI Specification 3.0.2 - 3.0.2 -[1] - Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. [2] - -[2] - OpenEO: OpenEO Developers API Reference / Process Graphs. [3] - -[3] - - - - - diff --git a/extensions/job_management/standard/20-044.xml b/extensions/job_management/standard/20-044.xml deleted file mode 100644 index 9745f8bb..00000000 --- a/extensions/job_management/standard/20-044.xml +++ /dev/null @@ -1,1087 +0,0 @@ - - - -OGC API - Processes - Part 4: Job Management -http://www.opengis.net/doc/IS/ogcapi-processes-4/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd -Geolabs - -Terradue Srl. - -Computer Research Institute of Montréal (CRIM). - -Gérald Fenoy - -Open Geospatial Consortium -OGC1.0en

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

- -

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

- -

The OGC API - Processes - Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard.

- -

The OGC API - Processes - Part 3: Workflows draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to …​

- -

The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

- -

This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion.

-draft2019 -Open Geospatial Consortium -OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementation
ats_druhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-management
_99e940ea-ac12-4895-8c4c-7ab0fba8b43d/conf/dru/deploy/post-op
ats_dru_deploy_post-op/conf/jm/create/post-op
TOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 - - - -Copyright notice -

Copyright © 2019 Open Geospatial Consortium
To obtain additional rights of use, visit

- - - -Note -

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

- -

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

- - - - - - -License Agreement -

Use of this document is subject to the license agreement at

- - - - - - -Notice for Drafts -

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

- -

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

- - - - - - -

Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site:

- - -Abstract

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

- -

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

- -

The OGC API — Processes — Part 2: Deploy, Replace, Undeploy draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard.

- -

The OGC API — Processes — Part 3: Workflows draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to …​

- -

The OGC API — Processes — Part 4: Job Management draft specification extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable.

- -

This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion.

- -Security Considerations -

See OGC API — Processes — Part 1: Core, Clause 10.4.

- -

Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations.

- -

Users making modifications to process resources need to:

- -

  1. Be authenticated,

    -
    2. -

  2. Have “modification privileges” on the processes offered through the API,

    -
    3. -

  3. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints.

    -
    4. -
- -

The API definition, as defined in Clause 7.3 from , must reflect this in the resource paths and their available methods.

- -

Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance:

- -

The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation).

- -

A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation.

- - -Example OpenAPI definition with security requirements -

The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user.

- -{ - "openapi" : "3.0.3", - "info" : { - "title" : "My API", - "description" : "This API ...", - "version" : "1.0.0" - }, - "servers" : [ { - "url" : "https://example.com/api/v1" - } ], - "security" : [ { - "JWT" : [ ], - "api_key": [ ] - } ], - "paths" : { }, - "components" : { - "securitySchemes": { - "JWT" : { - "type" : "http", - "scheme" : "bearer", - "bearerFormat" : "JWT" - }, - "api_key" : { - "type": "apiKey", - "name": "X-API-Key", - "in": "header" - } - } - } -} - - - -

If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.

- -

In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided.

- -Unauthorized requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | ----------------------------------------------------------->| - | | - | HTTP/1.1 401 Unauthorized | - | Date: Mon, 23 May 2022 11:18:45 GMT | - | WWW-Authenticate: Bearer realm="my-realm" | - | WWW-Authenticate: ApiKey header="X-API-Key" | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 86 | - | | - | { | - | "status": 401, | - | "title": "Unauthorized", | - | "detail": "HTTP 401 Unauthorized" | - | } | - | <-----------------------------------------------------------| - - -

HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023)

- - -

If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”).

- -Forbidden requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | Host: example.com | - | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | - |------------------------------------------------------------------>| - | | - | HTTP/1.1 403 Forbidden | - | Date: Mon, 23 May 2022 11:18:55 GMT | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 80 | - | | - | { | - | "status" : 403, | - | "title" : "Forbidden", | - | "detail" : "HTTP 403 Forbidden" | - | } | - |<------------------------------------------------------------------| - - -

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

- -Submitters -

All questions regarding this submission should be directed to the editors or the submitters:

- - - - - - - -
NameAffiliation
Gérald Fenoy (editor)GeoLabs
- - - -Scope -

The OGC API — Processes — Part 4 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [] and defines the behavior of a server that supports the ability to create jobs without implying the process execution starts right away.

- -

Specifically, the Processes Part 4 Standard specifies:

- -

  • How to manage job.

    -
    • -

  • How to handle provenenance information associated with a job.

    -
    • -
- - - -Conformance -

The OGC API — Processes — Part 4 Standard defines the following requirements classes.

- -

The main requirements class is:

- -

  • Job Management.

    -
    • -
- -

This class specifies requirements that any Web API implementing Processes Part 4 must conform with.

- -

The Job Management class does mandate a specific encoding and format for the job definition. However, the Part 4 extension defines the following conformance class:

- -

  • OpenEO graph

    -
    • -
- -

The OpenEO grap class defines that jobs can be created from an OpenEO graph.

- -

The provenance information associated with a job is not mandated to be supported by the server. A dedicated requirements class Provenance is defined for this feature.

- -

The standardization target for all Conformance class defined in this Standard is “Web API”.

- -

Conformance with this Standard shall be checked using all the relevant tests specified in of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.

- - - - - -Terms, definitions and abbreviated terms

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

-

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

-

For the purposes of this document, the following additional terms and definitions apply.

- - -Terms and definitions - -Execution unit - - -

A component containing a process that an implementation of the Processes API Part 1 can run.

 - - - -Deploy - - -

Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard.

 - - - -Replace - - -

Replace refers to upgrading a deployed process from a Processes API implementation.

 - - - -Undeploy - - -

Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process.

 - - - - -Abbreviated terms -
CWL

Common Workflow Language

-
-
DRU

Deploy, Replace, Undeploy

-
- - - -Conventions and background -

See , Clause 5.

- - - -Requirements Class “Job Management” - -Overview - Web APIOGC API — Processes — Part 1: Core, Conformance Class ‘core’RFC 2616 (HTTP/1.1)label - - -

A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs.

- -

The HTTP POST method is used to create new jobs.

- -

The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint.

- -

Finally, the HTTP POST method is used to start a job.

- -

Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standard does mandate that a specific jobs schema be used. However, this extension defines the following conformance classe:

- -

  • OpenEO Process Graph, that enables support for OpenEO-encoded jobs definition.

    -
    • -
- - -HTTP status codes -

Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code.

- -

The Status Codes listed in are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations.

- - -Typical HTTP status codes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”.

-
Status codeDescription
200A successful request.
201The server has successfully completed the operation and a new resource has been created.
202The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
204A successful request with no additional content to send in the response.
400The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.
401The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource.
404The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
405The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.
406Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource.
412The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server.
413The server is refusing to process the request because the request content is larger than the server is willing or able to process.
415The server is refusing to service the request because the content is in a format not supported by this method on the target resource.
422The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing.
500An internal error occurred in the server.
- - - -

More specific guidance is provided for each resource, where applicable.

- - label/per/core/additional-status-codes

Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in .

- - - -

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.

- - - -Cross-origin requests -

See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).

- - - - -Creating a new job - -Sequence diagram -

The following diagram illustrates the sequence diagram for deploying a new process to the API:

- -Client Server - | | - | POST /jobs HTTP/1.1 | - | Content-Type: application/json | - | | - |------------------------------------------------------------>| - | | - | HTTP/1.1 201 Created | - | Location: /jobs/{jobId} | - |<------------------------------------------------------------| - - - - -Operation - label/req/job-management/create/post-op

The server SHALL support the HTTP POST operation at the path /jobs.

- - - - - -Request body - -Overview - label/req/job-management/create/body

The body of the POST request SHALL be in JSON format.

- - - - label/per/job-management/create/body

A server MAY support any encoding in the body of a HTTP POST operation.

- - - - label/req/job-management/create/content-type

The Content-Type header SHALL be used to declare the media type of the request.

- - - -

See section 3.1.1.5 of RFC 7231 for details.

- - - -OGC API — Processes — Workflow Execute Request body - label/rec/job-management/create/body-ogcapi-processes

If the job can be encoded as an OGC API — Processes — Workflow Execute Request, implementation SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

- - - - - -OpenEO Process Graph body - label/rec/job-management/create/body-openeo

If the job can be encoded as an OpenEO graph, implementation SHOULD consider supporting the OpenEO graph encoding.

- - - - - - -Response - label/req/job-management/create/response-jobid

If the operation completes, the server SHALL generate a job identifier (i.e. {jobId}) for the created job.

- - - - label/req/job-management/create/response-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 201.

-

A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /jobs/{jobId}).

- - - - label/req/job-management/create/response-body

The response SHALL include a body that contains a status information of the created job conforms to the statusInfo.yaml schema.

-

The response SHALL contains a pending status code and the jobId property that contains the job identifier.

- - - - - -Exceptions -

See for general guidance.

- -

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from .

- - - - -Updating an existing job - -Sequence diagram -

The following diagram illustrates the sequence diagram for updating a -previously created job. The identifier of the job does not change.

The new job definition replaces the old job definition. Version control is not discussed in this Standard.

-

- - - -Client Server - | | - | PUT /jobs/{jobId} HTTP/1.1 | - | Content-Type: application/json | - | | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -Operation - label/req/job-management/update/put-op

For every created jobs (path ‘/jobs/{jobId}’), the server SHALL support the HTTP PUT operation.

-

The parameter ‘jobId’ is each ‘jobID’ property in the jobs list response (JSONPath: $.jobs[*].jobID).

- - - - - -Request body - - - -Overview - label/req/job-management/update/body*

The body of a PUT request SHALL be in JSON format.

- - - - label/per/job-management/update/body

A server MAY support any encoding in the body of a HTTP PUT operation.

- - - - label/req/job-management/update/content-type

As per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes.

- - - - -OGC API — Processes — Workflow Execute Request body - label/rec/job-management/update/body-ogcapi-processes

If a job can be created from an rc_ogcapi-processes,OGC API — Processes — Workflow Execute Request>>, implementations SHOULD consider supporting the OGC API — Processes — Workflow Execute Request encoding.

- - - - - -OpenEO Process Graph body - label/rec/job-management/update/body-openeo

If a job can be created from an OpenEO graph, implementations SHOULD consider supporting the OpenEO graph encoding.

- - - - - - -Response - label/req/job-management/update/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204.

-

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

- - - -

The status code depends on the server. If the server has replaced the job, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content).

- -

If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client.

- - - -Exceptions -

See for general guidance.

- -

If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from .

- -

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from .

- - - - -Staring a job - -Sequence diagram -

The following diagram illustrates the sequence diagram for starting the execution of a previously created jobs.

- -Client Server - | | - | POST /jobs/{jobId} HTTP/1.1 | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -Operation - label/req/job-management/start/start-op

For every created jobs (path: /jobs/{jobId}/results), the server SHALL support the HTTP POST operation.

-

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

- - - - - -Response - label/req/job-management/start/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

-

A response SHALL be a document that conforms to statusInfo.yaml.

- - - - - -Exceptions -

See HTTP status codes for general guidance.

- -

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from .

- - - - -Job definition -

For every job, it is possible to retrieve its original definition. It corresponds to the request’s body used to create or update the jobs.

- - -Operation - label/req/deploy-replace-undeploy/package/get-op

For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package.

-

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

- - - - - -Response - -Overview - label/req/deploy-replace-undeploy/package/response-success

A successful access to the resource SHALL be reported as a response with a HTTP status code 200.

- - - - label/req/deploy-replace-undeploy/package/response-body

A response with HTTP status code 200 SHALL include a body that contains the request body used to create or update the job.

- - - - - - -Exceptions -

See HTTP status codes for general guidance.

- -

If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from .

- - - - - -Requirements Class “OGC API — Process — Workflow Execute Request” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel - - -

This requirements class defines that the OGC API — Process — Workflow Execute Request is supported as an encoding for job definitions.

- - - -OGC API — Processes - -Overview - label/req/ogcapi-processes/schema

An OGC API - Processes document SHALL be based upon the JSON schema execute-workflow.yaml.

- - - - - - -Create - -OGC API — Processes body - label/req/ogcapi-processes/create/body

The body of the POST request SHALL be based upon the OpenAPI 3.0 schema execute-workflows.yaml

-

The media type application/json SHALL be used to indicate that request body contains a processes description encoded as an OGC API — Processes.

- - - - - - -Update - -OGC API — Processes body - label/req/ogcapi-processes/update/body

The media type application/ogcapi-processes+json SHALL be used to indicate that request body contains a job encoded as an OGC API — Processes.

- - - - - - -Job definition - -OGC API — Processes content - label/req/ogcapi-processes/definition/response-body

A response with HTTP status code 200 SHALL include a body that contains the OGC API — Processes to use to deploy the process.

- - - - - - - -Requirements Class “OpenEO Process Graph” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementlabel - - -

This requirements class defines that the server supports the OpenEO Process Graph as an encoding for job definitions.

- - - -OpenEO Process Graph - -Overview - label/req/openeo/schema

An OpenEO Process Graph document SHALL be based upon the JSON schema .

- - - - -Schema for OpenEO Process Graph -type: object -additionalProperties: - type: object - required: - - process_id - - arguments - properties: - process_id: - type: string - arguments: {} - - - - - -Create - -OpenEO body - label/req/openeo/create/body

The media type application/openeo+json SHALL be used to indicate that request body contains a processes description encoded as an OpenEO Process Graph.

- - - - - - -Update - -OpenEO body - label/req/openeo/update/body

The media type application/openeo+json SHALL be used to indicate that request body contains a job encoded as an OpenEO Process Graph.

- - - - - - -Job definition - -OpenEO content - label/req/openeo/definition/response-body

A response with HTTP status code 200 SHALL include a body that contains the OpenEO Process Graph to use to deploy the process.

- - - - - - - -Requirements Class “Quotation” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeolabel - - - - - -Requirements Class “Provenance” - -Overview -

This requirements class defines how to allow client application accessing the provenance of a job run.

- - Web APIOGC API — Processes — Part 1: Corelabel - - - - -Additional endpoints - -Inputs -

The server MUST provide an endpoint to retrieve the inputs of a job run.

- - -Operation - label/req/provenance/inputs/get-op

For every created jobs (path: /jobs/{jobId}/inputs), the server SHALL support the HTTP GET operation.

-

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

- - - - - -Response - label/req/provenance/inputs/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

-

The response SHALL contains a JSON document that conforms to the schema inputs.yaml.

- - - - - - -Outputs -

The server MUST provide an endpoint to retrieve the outputs of a job run.

- - -Operation - label/req/provenance/outputs/get-op

For every created jobs (path: /jobs/{jobId}/outputs), the server SHALL support the HTTP GET operation.

-

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

- - - - - -Response - label/req/provenance/outputs/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘200’.

-

The response SHALL contains a JSON document that conforms to the schema outputs.yaml.

- - - - - - -Run -

The server MUST provide an endpoint to retrieve the run of a job.

- - -Operation - label/req/provenance/run/get-op

For every created jobs (path: /jobs/{jobId}/run), the server SHALL support the HTTP GET operation.

-

The parameter jobId is each jobID property in the job list response (JSONPath: $.jobs[*].jobID).

- - - - - - - - -OpenAPI 3.0 -

See , Clause 9.

- - - -Media Types -

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

    -
    • -
- -

Additional CWL media types that would typically be used in a server that supports CWL are:

- -

  • application/cwl

    -
    • -
- - - - - - - - - - -Abstract Test Suite - -Introduction -

OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested.

- -

The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”.

- - - -Conformance Class Deploy, Replace, Undeploy - -Job Managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementhttp://www.opengis.net/spec/ogcapi-processes-4/1.0/conf/job-managementTarget TypeWeb API /conf/dru/deploy/post-op - - - - -Create operation - /conf/jm/create/post-optarget/req/job-management/create/post-op

Validate that the server support HTTP POST operation at the path /jobs/

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/job-list” link on the landing page as well as for the {root}/jobs path.

    -
    2. -

  2. Issue an HTTP POST request for each path.

    -
    3. -

  3. Validate that the response header does not contain 405 Method not allowed

    -
    4. -
- - - - - -Revision History - - - - - - - - - - - - -
DateReleaseEditorPrimary clauses modifiedDescription
2024-08-22NoneGérald FenoyallBoostraping the document
- -Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

- - 2024-08-29 - -OGC API - - -Processes - - -Part 1: Core - - -OGC API — Processes — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 - https://docs.ogc.org/is/18-062r2/18-062r2.html - 18-062r2 - - 2021-12-20 - - - - - - Benjamin Pross - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - -Open Geospatial Consortium - - - - 2 - en - - The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. - -By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. - -The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. - -The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. - - -Pross, B.: OGC 18-062, OGC API — Processes — Part 2: Deploy, Replace, UndeployOGC 20-04420-044 - - 2024-08-29 - -OGC API - - -Processes - - -Part 1: Core - - -OGC API — Processes — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 - https://docs.ogc.org/is/18-062r2/18-062r2.html - 18-062r2 - - 2021-12-20 - - - - - - Benjamin Pross - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - -Open Geospatial Consortium - - - - 2 - en - - The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. - -By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. - -The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. - -The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. - - - - 2024-08-29 - -OGC API - - -Features - - -Part 1: Core - - -OGC API — Features — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0 - https://docs.ogc.org/is/17-069r3/17-069r3.html - 17-069r3 - - 2019-10-07 - - - - - - Clemens Portele - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - - Charles Heazel - - - - - - - -Open Geospatial Consortium - - - - 3 - en - - OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. - -The OGC API family of standards is organized by resource type. This standard specifies the fundamental API building blocks for interacting with features. The spatial data community uses the term ‘feature’ for things in the real world that are of interest. - - - -Bibliography - OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: -. - OpenAPI Specification 3.0.2 - 3.0.2 - - Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. - [2] - - OpenEO: OpenEO Developers API Reference / Process Graphs. - [3] - - - - - - diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc index 10e72e92..d89a7165 100644 --- a/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc @@ -1,8 +1,8 @@ -[[req_deploy-replace-undeploy_package_get-op]] +[[req_job-management_definition_get-op]] [requirement] ==== [%metadata] -label:: /req/deploy-replace-undeploy/package/get-op +label:: /req/job-management/definition/get-op part:: For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path `/processes/{processId}/package`. part:: The parameter `processId` is each `id` property in the process collection response (JSONPath: `$.processes[*].id`). diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc index be69c245..5f9faf06 100644 --- a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc @@ -1,7 +1,7 @@ -[[req_deploy-replace-undeploy_package_response-body]] +[[req_job-management_definition_response-body]] [requirement] ==== [%metadata] -label:: /req/deploy-replace-undeploy/package/response-body +label:: /req/job-management/definition/response-body part:: A response with HTTP status code `200` SHALL include a body that contains the request body used to create or update the job. ==== diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc index feaa48a2..b638a2d7 100644 --- a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc @@ -1,7 +1,7 @@ -[[req_deploy-replace-undeploy_package_response-success]] +[[req_job-management_definition_response-success]] [requirement] ==== [%metadata] -label:: /req/deploy-replace-undeploy/package/response-success +label:: /req/job-management/definition/response-success part:: A successful access to the resource SHALL be reported as a response with a HTTP status code `200`. ==== diff --git a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc index 1207e44b..97a22d33 100644 --- a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc +++ b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc @@ -2,13 +2,13 @@ See <>, Clause 10.4. -Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will - in almost all cases - restrict the access to these operations. +Since creating and updating jobs will change the jobs available to a client, servers will - in almost all cases - restrict the access to these operations. Users making modifications to process resources need to: . Be authenticated, . Have "modification privileges" on the processes offered through the API, -. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints. +. Have access to one or more of the POST and/or PUT methods on the processes /jobs/{jobId} endpoints. The API definition, as defined in Clause 7.3 from <>, must reflect this in the resource paths and their available methods. @@ -68,7 +68,7 @@ In case the request does not include information to authenticate the user, the s ---- Client Server | | - | DELETE /processes/SampleProcess HTTP/1.1 | + | DELETE /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 | | ----------------------------------------------------------->| | | | HTTP/1.1 401 Unauthorized | @@ -97,7 +97,7 @@ If valid authentication credentials have been provided, but the API refuses to e ``` Client Server | | - | DELETE /processes/SampleProcess HTTP/1.1 | + | DELETE /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 | | Host: example.com | | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | |------------------------------------------------------------------>| diff --git a/extensions/job_management/standard/sections/clause_2_conformance.adoc b/extensions/job_management/standard/sections/clause_2_conformance.adoc index ae9cc154..bec04fe6 100644 --- a/extensions/job_management/standard/sections/clause_2_conformance.adoc +++ b/extensions/job_management/standard/sections/clause_2_conformance.adoc @@ -9,13 +9,15 @@ The main requirements class is: This class specifies requirements that any Web API implementing Processes Part 4 must conform with. -The `Job Management` class does mandate a specific encoding and -format for the job definition. However, the Part 4 extension -defines the following conformance class: +The `Job Management` class does not mandate a specific encoding for the job definition. +However, the Part 4 extension defines the following conformance class: -* <> +* <> +* <> -The `OpenEO grap` class defines that jobs can be created from an OpenEO graph. +The `OGC API - Processes - Workflow Execute Request` class defines that jobs can be created from an OGC API - Processes - Workflow Execute Request. + +The `OpenEO Process Graph` class defines that jobs can be created from an OpenEO Process Graph. The provenance information associated with a job is not mandated to be supported by the server. A dedicated requirements class <> is defined for this feature. From 6b7acb335cf6a50582ea94efc44d51ec9e2fcbed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 16:37:20 +0200 Subject: [PATCH 03/29] Fix typos --- .../standard/sections/clause_13_security_considerations.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc index 97a22d33..4164527b 100644 --- a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc +++ b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc @@ -68,7 +68,7 @@ In case the request does not include information to authenticate the user, the s ---- Client Server | | - | DELETE /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 | + | POST /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 | | ----------------------------------------------------------->| | | | HTTP/1.1 401 Unauthorized | @@ -97,7 +97,7 @@ If valid authentication credentials have been provided, but the API refuses to e ``` Client Server | | - | DELETE /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 | + | POST /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1 | | Host: example.com | | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | |------------------------------------------------------------------>| From 4aaf77736e35a0c95b830d7a04fa3a5636b9ac2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 16:38:32 +0200 Subject: [PATCH 04/29] Fix typos --- .../standard/sections/clause_13_security_considerations.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc index 4164527b..3377d4a7 100644 --- a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc +++ b/extensions/job_management/standard/sections/clause_13_security_considerations.adoc @@ -14,7 +14,7 @@ The API definition, as defined in Clause 7.3 from <>, must reflect thi Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance: -The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes - Part 2 (DRU) supports for each operation (or for all operations in the API implementation). +The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes - Part 4 (JM) supports for each operation (or for all operations in the API implementation). A member "security" in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a "security" member for the individual operation. From 8a6d4691b76a76aaba910414043599b0ca995a89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 17:10:55 +0200 Subject: [PATCH 05/29] Fix typo --- .../standard/{20-044.adoc => 24-051.adoc} | 12 +++++------- .../job-management/update/REC_body-cwl.adoc | 9 --------- .../update/REC_body-ogcapi-processes.adoc | 2 +- .../job-management/update/REC_body-openeo.adoc | 2 +- 4 files changed, 7 insertions(+), 18 deletions(-) rename extensions/job_management/standard/{20-044.adoc => 24-051.adoc} (84%) delete mode 100644 extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc diff --git a/extensions/job_management/standard/20-044.adoc b/extensions/job_management/standard/24-051.adoc similarity index 84% rename from extensions/job_management/standard/20-044.adoc rename to extensions/job_management/standard/24-051.adoc index 631029b3..b738ca24 100644 --- a/extensions/job_management/standard/20-044.adoc +++ b/extensions/job_management/standard/24-051.adoc @@ -1,7 +1,7 @@ = OGC API - Processes - Part 4: Job Management :doctype: standard :docsubtype: implementation -:docnumber: 20-044 +:docnumber: 24-051 :status: draft :copyright-year: 2019 :edition: 1.0 @@ -37,15 +37,13 @@ include::sections/clause_7_ogcapi-processes.adoc[] include::sections/clause_8_openeo.adoc[] -include::sections/clause_9_quotation.adoc[] +include::sections/clause_9_provenance.adoc[] -include::sections/clause_10_provenance.adoc[] +include::sections/clause_10_oas.adoc[] -include::sections/clause_11_oas.adoc[] +include::sections/clause_11_media_types.adoc[] -include::sections/clause_12_media_types.adoc[] - -include::sections/clause_13_security_considerations.adoc[] +include::sections/clause_12_security_considerations.adoc[] include::sections/annex_ats.adoc[] diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc deleted file mode 100644 index 8972765a..00000000 --- a/extensions/job_management/standard/recommendations/job-management/update/REC_body-cwl.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[rec_deploy-replace-undeploy_replace_body-cwl]] -[recommendation] -==== -[%metadata] -label:: /rec/deploy-replace-undeploy/replace/body-cwl - -part:: If a process can be encoded for the intended use in <>, implementations SHOULD consider supporting the <> encoding for describing the replacement process. - -==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc index 31f42316..bd66fb6c 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc @@ -4,6 +4,6 @@ [%metadata] label:: /rec/job-management/update/body-ogcapi-processes -part:: If a job can be created from an rc_ogcapi-processes,OGC API - Processes - Workflow Execute Request>>, implementations SHOULD consider supporting the <> encoding. +part:: If a job can be created from an <>, implementations SHOULD consider supporting the <> encoding. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc index 317dbabc..460ad751 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc @@ -4,6 +4,6 @@ [%metadata] label:: /rec/job-management/update/body-openeo -part:: If a job can be created from an <>, implementations SHOULD consider supporting the <> encoding. +part:: If a job can be created from an <>, implementations SHOULD consider supporting the <> encoding. ==== From 3281c3d417843f4e242d4735658c3d405c5d3abd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 17:14:19 +0200 Subject: [PATCH 06/29] Fix files names --- .../sections/{clause_11_oas.adoc => clause_10_oas.adoc} | 0 ...use_12_media_types.adoc => clause_11_media_types.adoc} | 0 ...ations.adoc => clause_12_security_considerations.adoc} | 0 ...clause_10_provenance.adoc => clause_9_provenance.adoc} | 0 .../standard/sections/clause_9_quotation.adoc | 8 -------- 5 files changed, 8 deletions(-) rename extensions/job_management/standard/sections/{clause_11_oas.adoc => clause_10_oas.adoc} (100%) rename extensions/job_management/standard/sections/{clause_12_media_types.adoc => clause_11_media_types.adoc} (100%) rename extensions/job_management/standard/sections/{clause_13_security_considerations.adoc => clause_12_security_considerations.adoc} (100%) rename extensions/job_management/standard/sections/{clause_10_provenance.adoc => clause_9_provenance.adoc} (100%) delete mode 100644 extensions/job_management/standard/sections/clause_9_quotation.adoc diff --git a/extensions/job_management/standard/sections/clause_11_oas.adoc b/extensions/job_management/standard/sections/clause_10_oas.adoc similarity index 100% rename from extensions/job_management/standard/sections/clause_11_oas.adoc rename to extensions/job_management/standard/sections/clause_10_oas.adoc diff --git a/extensions/job_management/standard/sections/clause_12_media_types.adoc b/extensions/job_management/standard/sections/clause_11_media_types.adoc similarity index 100% rename from extensions/job_management/standard/sections/clause_12_media_types.adoc rename to extensions/job_management/standard/sections/clause_11_media_types.adoc diff --git a/extensions/job_management/standard/sections/clause_13_security_considerations.adoc b/extensions/job_management/standard/sections/clause_12_security_considerations.adoc similarity index 100% rename from extensions/job_management/standard/sections/clause_13_security_considerations.adoc rename to extensions/job_management/standard/sections/clause_12_security_considerations.adoc diff --git a/extensions/job_management/standard/sections/clause_10_provenance.adoc b/extensions/job_management/standard/sections/clause_9_provenance.adoc similarity index 100% rename from extensions/job_management/standard/sections/clause_10_provenance.adoc rename to extensions/job_management/standard/sections/clause_9_provenance.adoc diff --git a/extensions/job_management/standard/sections/clause_9_quotation.adoc b/extensions/job_management/standard/sections/clause_9_quotation.adoc deleted file mode 100644 index 7ca26b3e..00000000 --- a/extensions/job_management/standard/sections/clause_9_quotation.adoc +++ /dev/null @@ -1,8 +0,0 @@ - -== Requirements Class "Quotation" - -[[quotation-overview]] -=== Overview - -include::../requirements/requirements_class_quotation.adoc[] - From 7b7ed5d5e18974a647398bc1d209879401929d0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 17:17:24 +0200 Subject: [PATCH 07/29] Delete extensions/job_management/standard/20-044.xml.abort --- .../job_management/standard/20-044.xml.abort | 1509 ----------------- 1 file changed, 1509 deletions(-) delete mode 100644 extensions/job_management/standard/20-044.xml.abort diff --git a/extensions/job_management/standard/20-044.xml.abort b/extensions/job_management/standard/20-044.xml.abort deleted file mode 100644 index 0744cadd..00000000 --- a/extensions/job_management/standard/20-044.xml.abort +++ /dev/null @@ -1,1509 +0,0 @@ - - - -OGC API - Processes - Part 4: Job Management -http://www.opengis.net/doc/IS/ogcapi-processes-2/1.020-04420-044yyyy-mm-ddyyyy-mm-ddyyyy-mm-dd -Geolabs - -CubeWerx Inc - -Terradue Srl. - -Wuhan University (WHU). - -Computer Research Institute of Montréal (CRIM). - -Gérald Fenoy - -Open Geospatial Consortium -OGC1.0en

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

- -

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

- -

OGC API - Processes - Part 2: Deploy, Replace, Undeploy extends the core capabilities specified in OGC API - Processes - Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard.

- -

This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion.

-draft2019 -Open Geospatial Consortium -OGCprocesscollectioninstancespatialdataopenapitransactionsinsertupdatedeleteaddremovedeployundeployRESTPUTPOSTDELETEstandardimplementation
ats_dru_mutable-process/req/dru/mutable-process
ats_dru_test-process/req/dru/test-process
ats_druhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/deploy-replace-undeploy
_f7ee31b4-f02b-4ada-a34f-569b063612d1/conf/dru/static-indicator
_2c99dc51-ecdc-4480-b23e-d5f831205920/conf/dru/deploy/post-op
_5b5ebd3a-cd9f-408a-9905-09b91d420c6d/conf/dru/deploy/content-type
_8e36ae58-5789-4dd1-80b9-956967dc8c22/conf/dru/deploy/unsupported-content-type
_7843c6bd-67d7-4dc9-83da-c11f9cfe41a1/conf/dru/replace/put-op
_231f2a7f-6dd1-4bfe-b304-5c64040f15d8/conf/dru/replace/content-type
_79103ae8-bdc4-4213-98b6-32a8b280f7c3/conf/dru/undeploy/delete-op
_64a67495-1e74-46e8-990a-ad273a56a7e2/conf/dru/undeploy/response
_2ca56830-1a16-4fae-9722-8eca5cd08d27/conf/dru/undeploy/response-immutable
ats_dru_static-indicator/conf/dru/static-indicator
ats_dru_deploy_post-op/conf/dru/deploy/post-op
ats_dru_deploy_content-type/conf/dru/deploy/content-type
ats_dru_deploy_unsupported-content-type/conf/dru/deploy/unsupported-content-type
ats_dru_replace_put-op/conf/dru/replace/put-op
ats_dru_replace_content-type/conf/dru/replace/content-type
ats_dru_undeploy_delete-op/conf/dru/undeploy/delete-op
ats_dru_undeploy_response/conf/dru/undeploy/response
ats_dru_undeploy_response-immutable/conf/dru/undeploy/response-immutable
ats_ogcapppkghttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/ogcapppkg
_b663cbca-b5f5-44f3-a97c-246087f2c4e3/conf/ogcapppkg/deploy/body
_682969d9-d3b8-46ed-a88e-2fe35852baa3/conf/ogcapppkg/deploy/response
_d3f14213-fdd8-489e-a3ca-935b8f764f40/conf/ogcapppkg/deploy/response-success
_ead29a44-1dc5-4fd3-99a9-c92103b5d9e3/conf/ogcapppkg/deploy/response-duplicate
_981d7d56-4bdc-4ed2-8d10-e3a1988a2423/conf/ogcapppkg/replace/body
_6f6e06b2-ccf3-4b2a-bba0-0e4f72efcd51/conf/ogcapppkg/replace/response
ats_ogcapppkg_deploy_body/conf/ogcapppkg/deploy/body
ats_ogcapppkg_deploy_response/conf/ogcapppkg/deploy/response
ats_ogcapppkg_deploy_response-success/conf/ogcapppkg/deploy/response-success
ats_ogcapppkg_deploy_response-duplicate/conf/ogcapppkg/deploy/response-duplicate
ats_ogcapppkg_replace_body/conf/ogcapppkg/replace/body
ats_ogcapppkg_replace_response/conf/ogcapppkg/replace/response
ats_dockerhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/docker
_8abd0775-f4a6-4530-8633-3a1ec8a28c99/conf/docker/deploy/body
_92183e95-5148-414b-abe9-44bb78da02b5/conf/docker/replace/body
ats_docker_deploy_body/conf/docker/deploy/body
ats_docker_replace_body/conf/docker/replace/body
ats_cwlhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/cwl
_e5c50d2f-dec9-4c90-a1de-5d61ad8e454b/conf/cwl/deploy/body
_0274eb63-ac42-4f63-8e23-c6b9e1affcbb/conf/cwl/replace/body
ats_cwl_deploy_body/conf/cwl/deploy/body
ats_cwl_replace_body/conf/cwl/replace/body
TOC Heading Levels2HTML TOC Heading Levels2DOC TOC Heading Levels2PDF TOC Heading Levels2 - - - -Copyright notice -

Copyright © 2019 Open Geospatial Consortium
To obtain additional rights of use, visit

- - - -Note -

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

- -

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

- - - - - - -License Agreement -

Use of this document is subject to the license agreement at

- - - - - - -Notice for Drafts -

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

- -

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

- - - - - - -

Suggested additions, changes and comments on this document are welcome and encouraged. Such suggestions may be submitted using the online change request form on OGC web site:

- - -Abstract

OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

- -

The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard.

- -

OGC API — Processes — Part 2: Deploy, Replace, Undeploy extends the core capabilities specified in OGC API — Processes — Part 1: Core [] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API — Processes Standard.

- -

This is a DRAFT version of the 2nd part of the OGC API — Processes standards. This draft is not complete and there are open issues that are still under discussion.

- -Security Considerations -

See OGC API — Processes — Part 1: Core, Clause 10.4.

- -

Since deploy, replace and undeploy (DRU) operations will change the processes available to a client, servers will — in almost all cases — restrict the access to these operations.

- -

Users making modifications to process resources need to:

- -

  1. Be authenticated,

    -
    2. -

  2. Have “modification privileges” on the processes offered through the API,

    -
    3. -

  3. Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints.

    -
    4. -
- -

The API definition, as defined in Clause 7.3 from , must reflect this in the resource paths and their available methods.

- -

Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance:

- -

The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 2 (DRU) supports for each operation (or for all operations in the API implementation).

- -

A member “security” in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a “security” member for the individual operation.

- - -Example OpenAPI definition with security requirements -

The following OpenAPI definition declares that the API accepts either api keys in an “X-API-Key” header or Json Web Token (JWT) bearer tokens to authenticate the requestor. X-API-KEY is a custom HTTP header that can be used to secure APIs. The API implementation will decide, if an authenticated request is rejected or executed based on the privileges of the authenticated user.

- -{ - "openapi" : "3.0.3", - "info" : { - "title" : "My API", - "description" : "This API ...", - "version" : "1.0.0" - }, - "servers" : [ { - "url" : "https://example.com/api/v1" - } ], - "security" : [ { - "JWT" : [ ], - "api_key": [ ] - } ], - "paths" : { }, - "components" : { - "securitySchemes": { - "JWT" : { - "type" : "http", - "scheme" : "bearer", - "bearerFormat" : "JWT" - }, - "api_key" : { - "type": "apiKey", - "name": "X-API-Key", - "in": "header" - } - } - } -} - - - -

If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.

- -

In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided.

- -Unauthorized requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | ----------------------------------------------------------->| - | | - | HTTP/1.1 401 Unauthorized | - | Date: Mon, 23 May 2022 11:18:45 GMT | - | WWW-Authenticate: Bearer realm="my-realm" | - | WWW-Authenticate: ApiKey header="X-API-Key" | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 86 | - | | - | { | - | "status": 401, | - | "title": "Unauthorized", | - | "detail": "HTTP 401 Unauthorized" | - | } | - | <-----------------------------------------------------------| - - -

HTTP WWW-Authenticate header is a response-type header. It serves as a support for various authentication mechanisms which are important to control access to pages and other resources as well. All of these mechanisms are based on the use of the 401 status code. The HTTP WWW-Authenticate response header defines the authentication method that ought to be wont to gain access to a resource. As discussed earlier, the WWW-Authenticate header is sent along with a 401 Unauthorized response. (GeeksforGeeks.org, 2023)

- - -

If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”).

- -Forbidden requestClient Server - | | - | DELETE /processes/SampleProcess HTTP/1.1 | - | Host: example.com | - | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ | - |------------------------------------------------------------------>| - | | - | HTTP/1.1 403 Forbidden | - | Date: Mon, 23 May 2022 11:18:55 GMT | - | Content-Type: application/problem+json | - | Vary: Accept | - | Content-Length: 80 | - | | - | { | - | "status" : 403, | - | "title" : "Forbidden", | - | "detail" : "HTTP 403 Forbidden" | - | } | - |<------------------------------------------------------------------| - - -

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

- -Submitters -

All questions regarding this submission should be directed to the editors or the submitters:

- - - - - - - - - - - -
NameAffiliation
Panagiotis (Peter) A. Vretanos (editor)CubeWerx Inc.
Gérald Fenoy (editor)GeoLabs
Pedro GonçalvesTerradue Srl.
- - - -Scope -

The OGC API — Processes — Part 2 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [] and defines the behavior of a server that supports the ability to dynamically add, replace and/or undeploy processes via an OGC API — Processes implementation instance.

- -

Specifically, the Processes Part 2 Standard specifies:

- -

  • How to deploy a new process.

    -
    • -

  • How to replace an existing process.

    -
    • -

  • How to undeploy an existing process.

    -
    • -
- -

The following table crosswalks each of the resource endpoints discussed in this Standard with the HTTP methods POST, PUT and DELETE. Each intersecting cell in the table either contains the name of the operation for that combination of resource endpoint and HTTP method, or it contains the phrase “n/a” which is used to indicate that this Standard does not specify any behavior for that combination of resource endpoints and the HTTP method.

- - -Supported HTTP methods by resource - - - - - - - - - - - - - - - -
Resource endpointHTTP method
POSTPUTDELETE
/processesdeployn/an/a
/processes/{processId}n/areplaceundeploy
- - - -Conformance -

The OGC API — Processes — Part 2 Standard defines the following requirements classes.

- -

The main requirements class is:

- -

  • Deploy, Replace, Undeploy.

    -
    • -
- -

This class specifies requirements that any Web API implementing Processes Part 2 must conform with.

- -

The Deploy, Replace, Undeploy class does not mandate a specific encoding or format for the formal definition of a process. However, the Part 2 extension defines the following conformance class:

- -

  • OGC Application Package

    -
    • -
- -

The OGC Application Package class defines the schema of a document that formally defines the inputs, outputs and other necessary metadata about a process that is to be dynamically deployed through the API.

- -

The Application Package encoding is not mandatory. An implementation of this extension may choose to implement some other process description instead. That said, the Deploy, Replace, Undeploy conformance class includes recommendations to support the OGC Application Package.

- -

A requirement class is dedicated to the deployment of containers as processes:

- -

  • Docker

    -
    • -
- -

In addition to the previous encoding, another conformance class is provided to enable support for the Common Workflow Language (CWL):

- -

  • CWL

    -
    • -
- -

The standardization target for all Conformance class defined in this Standard is “Web API”.

- -

Conformance with this Standard shall be checked using all the relevant tests specified in of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.

- - - - - -Terms, definitions and abbreviated terms

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

-

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

-

For the purposes of this document, the following additional terms and definitions apply.

- - -Terms and definitions - -Execution unit - - -

A component containing a process that an implementation of the Processes API Part 1 can run.

 - - - -Deploy - - -

Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard.

 - - - -Replace - - -

Replace refers to upgrading a deployed process from a Processes API implementation.

 - - - -Undeploy - - -

Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process.

 - - - - -Abbreviated terms -
CWL

Common Workflow Language

-
-
DRU

Deploy, Replace, Undeploy

-
- - - -Conventions and background -

See , Clause 5.

- - - -Requirements Class “Deploy, Replace, Undeploy (DRU)” - -Overview - Web APIOGC API — Processes — Part 1: Core, Conformance Class ‘core’RFC 2616 (HTTP/1.1)label - - -

A server that implements the DRU Requirements Class provides the ability to dynamically deploy, replace and undeploy processes.

- -

The HTTP POST method is used to deploy a new process to the API.

- -

The HTTP PUT method is used to replace the definition of a previously deployed processes that are accessible via the Processes API endpoint.

- -

Finally, the HTTP DELETE method is used to undeploy a previously deployed process that is accessible via the Processes API endpoint.

- -

Deploying or replacing a process requires that a formal description of the new or replacement process be provided by the client. This Standard does not mandate that a specific processes description language or vocabulary be used. However, to promote interoperability, this extension defines two conformance classes:

- -

  • OGC Application Package, that defines a formal process description language encoded using JSON,

    -
    • -

  • CWL, that enables support for CWL-encoded process definition.

    -
    • -
- -

A recommendation is made later in this Standard that all implementations of Processes API Part 2 extension support the OGC Application Package.

- - -HTTP status codes -

Clients implementing the Processes API Part 2 should be prepared to handle any legal HTTP or HTTPS status code.

- -

The Status Codes listed in are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations.

- - -Typical HTTP status codes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC “HTTP Semantics”.

-
Status codeDescription
200A successful request.
201The server has successfully completed the operation and a new resource has been created.
202The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
204A successful request with no additional content to send in the response.
400The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.
401The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403The server understood the request, but is refusing to execute the request. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but that the client is not authorized to perform the requested operation on the resource.
404The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
405The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.
406Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource.
412The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server.
413The server is refusing to process the request because the request content is larger than the server is willing or able to process.
415The server is refusing to service the request because the content is in a format not supported by this method on the target resource.
422The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing.
500An internal error occurred in the server.
- - - -

More specific guidance is provided for each resource, where applicable.

- - label/per/core/additional-status-codes

Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in .

- - - -

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.

- - - -Cross-origin requests -

See OGC API — Features — Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).

- - - - -Immutable processes -

The Processes API Part 2 extension recognizes that an OGC web processing API may be deployed with a set of static, built-in processes that are immutable and cannot be removed or modified via requests from a deploy-replace-undeploy API implementation. In an API Description Document (e.g. OpenAPI), such process paths would not include support for the HTTP POST, PUT or DELETE methods.

- -

However, to make it clear which processes in a collection (path: /processes) are built-in — and thus immutable — and which have been dynamically deployed, the processes collection schema is modified to add a flag indicating this aspect of a process.

- - label/req/deploy-replace-undeploy/static-indicator

The optional property mutable SHALL be used to indicate whether a process is a static or built-in process that is immutable or a dynamically added process that is mutable.

-

A value of true SHALL be used to indicate that a processes is mutable and can thus be manipulated through an API request.

-

A value of false SHALL be used to indicate that a processes is immutable and can thus not be manipulated through an API request.

-

The default value SHALL be true.

- - - -

The following schema fragment extends the process summary accessible via the /processes path to add the mutable property.

- -allOf: - - $ref: "https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/processSummary.yaml" - - type: object - properties: - mutable: - type: boolean - default: true - - - - -Deploying a new process to the API - -Sequence diagram -

The following diagram illustrates the sequence diagram for deploying a new process to the API:

- -Client Server - | | - | POST /processes HTTP/1.1 | - | Content-Type: application/ogcapppkg+json | - | | - | ... Body contains a formal description of the process to | - | add (e.g. OGC Application Package) ... | - |------------------------------------------------------------>| - | | - | HTTP/1.1 201 Created | - | Location: /processes/{processId} | - |<------------------------------------------------------------| - - - - -Operation - label/req/deploy-replace-undeploy/deploy/post-op

The server SHALL support the HTTP POST operation at the path /processes.

- - - - - -Request body - -Overview - label/req/deploy-replace-undeploy/deploy/body

The body of the POST request SHALL contain a formal description of the process to be dynamically deployed to the API.

- - - - label/per/deploy-replace-undeploy/deploy/body

A server MAY support any processes description encoding in the body of a HTTP POST operation.

- - - - label/req/deploy-replace-undeploy/deploy/content-type

The Content-Type header SHALL be used to declare the media type of the request body containing a description of the processes to be added to the API.

- - - -

See section 3.1.1.5 of RFC 7231 for details.

- - - -OGC Application Package body - label/rec/deploy-replace-undeploy/deploy/body-ogcapppkg

If a process can be represented for the intended use as an OGC Application Package, implementations SHOULD consider supporting the OGC Application Package encoding for describing the process to be added to the API.

- - - - - -CWL body - label/rec/deploy-replace-undeploy/deploy/body-cwl

If a process can be encoded for the intended use in CWL, implementations SHOULD consider supporting the CWL encoding for describing the process to be deployed to the API.

- - - - - - -Response - label/req/deploy-replace-undeploy/deploy/response-pid

If the operation completes, the server SHALL assign the processes identifier (i.e. {processId}) specified in the processes description for the newly added processes.

- - - - label/req/deploy-replace-undeploy/deploy/response-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 201.

-

A response with HTTP status code 201 SHALL include a Location header with the URI of the deployed processes (path: /processes/{processId}).

-

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

- - - - label/req/deploy-replace-undeploy/deploy/response-body

The response SHALL include a body that contains a summary description of the added process conforms to the processSummary.yaml schema.

- - - - - -Exceptions -

See for general guidance.

- - label/req/deploy-replace-undeploy/deploy/unsupported-media-type

If the server does not support the Content-Type header associated with the request body, the code of the response SHALL be 415 Unsupported Media Type.

-

The content of that response SHALL be based upon the OpenAPI 3.0 schema exception.yaml.

-

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/unsupported-media-type”.

- - - - label/req/deploy-replace-undeploy/deploy/response-duplicate

If a process with the same identifier already exists on the server, the code of the response SHALL be 409.

-

A response with HTTP status code 409 MAY include a Location header with the URI of the duplicated processes (path: /processes/{processId}).

-

The content of that response SHALL be based upon the OpenAPI 3.0 schema exception.yaml.

-

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/duplicated-process”.

- - - - label/req/deploy-replace-undeploy/deploy/response-immutable

If a process with the same identifier already exists on the server and is immutable, the code of the response SHALL be 403.

-

A response with HTTP status code 403 MAY include a Location header with the URI of the existing process (path: /processes/{processId}).

-

The content of that response shall be based upon the OpenAPI 3.0 schema exception.yaml.

-

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/immutable-process”.

- - - - - - -Replacing an existing processes - -Sequence diagram -

The following diagram illustrates the sequence diagram for replacing a -previously deployed processes. The identifier of the process does not change.

The new process definition replaces the old process definition. Version control is not discussed in this Standard.

-

- - - -Client Server - | | - | PUT /processes/{processId} HTTP/1.1 | - | Content-Type: application/ogcapppkg+json | - | | - | ... Body contains a formal description of the process to | - | replace the existing process (e.g. OGC Application | - | Package) ... | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -Operation - label/req/deploy-replace-undeploy/replace/put-op

For every dynamically deployed processes (path ‘/processes/{processId}’), the server SHALL support the HTTP PUT operation.

-

The parameter ‘processId’ is each ‘id’ property in the process collection response (JSONPath: $.processes[*].id).

- - - - - -Request body - - - -Overview - label/req/deploy-replace-undeploy/replace/body*

The body of a PUT request SHALL contain a formal description of the replacement process.

- - - - label/per/deploy-replace-undeploy/replace/body

A server MAY support any processes description encoding in the body of a HTTP PUT operation.

- - - - label/req/deploy-replace-undeploy/replace/content-type

As per HTTP 1.1 () the ‘Content-Type’ header SHALL be used to indicate the media type of a request body containing the description of the replacement processes.

- - - - -OGC Application Package body - label/rec/deploy-replace-undeploy/replace/body-ogcapppkg

If a process can be described for the intended use as an OGC Application Package, implementations SHOULD consider supporting the OGC Application Package encoding for describing the replacement process.

- - - - - -CWL body - label/rec/deploy-replace-undeploy/replace/body-cwl

If a process can be encoded for the intended use in CWL, implementations SHOULD consider supporting the CWL encoding for describing the replacement process.

- - - - - - -Response - label/req/deploy-replace-undeploy/replace/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204.

-

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

- - - -

The status code depends on the server. If the server has replaced the process, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content).

- -

If the server will process the replace request later, a 202 status code will be returned. In this case, the processing can succeed or fail, without further notification to the client.

- - - -Exceptions -

See for general guidance.

- -

If the request body’s media type is not supported by the server, then /req/deploy-replace-undeploy/deploy/unsupported-media-type applies.

- -

If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process from .

- -

If the process exist but is immutable then /req/deploy-replace-undeploy/deploy/response-immutable applies.

- - - - -Removing a processes from the API (undeployProcess) - -Sequence diagram -

The following diagram illustrates the sequence diagram for undeploying a previously deployed process.

- -Client Server - | | - | DELETE /processes/{processId} HTTP/1.1 | - |------------------------------------------------------------>| - | | - | HTTP/1.1 204 OK | - |<------------------------------------------------------------| - - - - -Operation - label/req/deploy-replace-undeploy/undeploy/delete-op

For every dynamically added process (path: /processes/{processId}), the server SHALL support the HTTP DELETE operation.

-

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

- - - - - -Response - label/req/deploy-replace-undeploy/undeploy/response

A successful execution of the operation SHALL be reported as a response with a HTTP status code ‘204’.

- - - - - -Exceptions -

See HTTP status codes for general guidance.

- -

If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process from .

- -

If the process exist but is immutable then /req/deploy-replace-undeploy/deploy/response-immutable applies.

- - - - -Retrieving the formal description -

For every mutable process, it is possible to retrieve its formal description. It corresponds to the request’s body used to deploy or replace the process.

- - -Operation - label/req/deploy-replace-undeploy/package/get-op

For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path /processes/{processId}/package.

-

The parameter processId is each id property in the process collection response (JSONPath: $.processes[*].id).

- - - - - -Response - -Overview - label/req/deploy-replace-undeploy/package/response-success

A successful access to the resource SHALL be reported as a response with a HTTP status code 200.

- - - - label/req/deploy-replace-undeploy/package/response-body

A response with HTTP status code 200 SHALL include a body that contains the request body used to deploy or replace the process.

- - - - - - -Exceptions -

See HTTP status codes for general guidance.

- -

If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process from .

- -

If the process exist but is immutable then /req/deploy-replace-undeploy/deploy/response-immutable applies.

- - - - - -Requirements Class “OGC Application Package” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeploylabel - - -

This requirements class defines the schema of an OGC Application Package. An OGC Application Package is a document that describes a process in sufficient detail so that an implementation of this extension can dynamically deploy the process and make it accessible via an OGC API — Processes implementation.

- -

The information contained in an OGC Application Package can include:

- -

  • A formal description of the process including what inputs the process takes and what outputs the process generates.

    -
    • -

  • Either an inline or by reference execution unit which is the code that the server needs to execute whenever the process is invoked.

    -
    • -

  • Additional resource information required by the execution unit.

    -
    • -
- - - -OGC Application Package schema - -Overview - label/req/ogcapppkg/schema

An OGC Application Package document SHALL be based upon the OpenAPI schema ogcapppkg.yaml.

- - - - -Schema for the OGC Application Package -Unresolved directive in sections/clause_7_apppkg.adoc - include::../../../../openapi/schemas/processes-dru/ogcapppkg.yaml[] - - - - -processDescription property -

The formal process description (i.e. its inputs, its output, etc.) is provided, either in-line using the processDescription property or may be inferred from the information provided in the execution unit.

- - label/req/ogcapppkg/process-description

The value of the processDescription property SHALL be based upon the OpenAPI schema process.yaml.

- - - - - -executionUnit property -

If the schema defined for the executionUnit property of an OGC Application Package remains open, it can be restricted in other Requirements.

- - label/rec/ogcapppkg/execution-unit-docker

If the execution unit is a Docker image, implementations SHOULD consider supporting the Docker Requirements class.

- - - - label/rec/ogcapppkg/execution-unit-cwl

If the execution unit is encoded in CWL, implementations SHOULD consider supporting the CWL Requirement class.

- - - - - - -Deploy - -OGC Application Package body - label/req/ogcapppkg/deploy/body

The media type application/ogcapppkg+json SHALL be used to indicate that request body contains a processes description encoded as an OGC Application Package.

- - - - - - -Replace - -OGC Application Package body - label/req/ogcapppkg/replace/body

The media type application/ogcapppkg+json SHALL be used to indicate that request body contains a processes description encoded as an OGC Application Package.

- - - - - - -Formal description - -OGC Application Package content - label/req/ogcapppkg/package/response-body

A response with HTTP status code 200 SHALL include a body that contains the OGC Application Package to use to deploy the process.

- - - - - - - -Requirements Class “Docker” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkglabel - - -

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 - -executionUnit property - -Overview - label/req/docker/schema

The executionUnit property of an OGC Application Package document SHALL be based upon the schema executionUnit.yaml.

- - - - -Schema for the Docker execution unit parameter -Unresolved directive in sections/clause_8_docker.adoc - include::../../../../openapi/schemas/processes-dru/executionUnit.yaml[] - - - - -type and image properties -

The execution unit can be specified by reference, using a Docker image reference.

- - label/req/docker/execution-unit

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 image property SHALL be a reference to the Docker image.

- - - - - - - - -Requirements Class “CWL” - -Overview - Web APIOGC API — Processes — Part 1: Corehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/deploy-replace-undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/req/ogcapppkgCommon Workflow Language label - - -

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 - -executionUnit property -

In case the OGC Application Package encoding is used, the following Requirement applies.

- - label/req/cwl/execution-unit

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 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 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.

- - - -

Below is an example of a deploy body request using a CWL-encoded execution unit by reference.

- -{ - "executionUnit": { - "href": "https://raw.githubusercontent.com/EOEPCA/app-snuggs/main/app-package.cwl", - "type": "application/cwl" - } -} - - -

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.

- -{ - "executionUnit": { - "value": { ... }, - "mediaType": "application/cwl+json" - } -} - - - - - -Deploy - -CWL body - label/req/cwl/deploy/body

The media type application/cwl SHALL be used to indicate that request body contains a processes description encoded as CWL.

- - - - - -w parameter -

When encoded in CWL, processes are identified as instances of the workflow class.

- - label/req/cwl/deploy/w-param

If the CWL contains more than a single workflow identifier, an additional w query parameter MAY be used to target a specific workflow id to be deployed. If not used, the first process found SHALL be deployed.

- - - - - -Exception - label/req/cwl/deploy/exception-workflow-not-found

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.

-

The content of that response SHALL be based upon the schema exception.yaml.

-

The type of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/workflow-not-found”.

- - - - - - -Replace - -CWL body - label/req/cwl/replace/body

The media type application/cwl SHALL be used to indicate that request body contains a processes description encoded as CWL.

- - - - - - -Formal description - -CWL content - label/req/cwl/package/response-body

A response with HTTP status code 200 SHALL include a body that contains:

-

  • the CWL to use to deploy the process, in case the Content-Type used to deploy the process was application/cwl.

    -
    • -

  • the OGC Application Package to use to deploy the process, in case the Content-Type used to deploy the process was application/ogcapppkg+json.

    -
    • -
- - - - - - - -OpenAPI 3.0 -

See , Clause 9.

- - - -Media Types -

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

    -
    • -
- -

Additional CWL media types that would typically be used in a server that supports CWL are:

- -

  • application/cwl

    -
    • -
- - - - - - - - - - -Abstract Test Suite - -Introduction -

OGC Web Application Programming Interfaces (APIs) are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web API. Therefore, an API endpoint may expose resources in addition to those defined by the standard. A test engine must be able to traverse an implementation of the API, identify and validate test points, and ignore resource paths which are not to be tested.

- -

The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes “basic” and “bearer”, API keys, and OAuth2 flow “authorizationCode”.

- -

The following requirements apply for a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy under test:

- - /req/dru/mutable-process

Ensure that a mutable process is offered by the server being tested.

-

If a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy is tested using CITE tests, the server SHALL offer at least one mutable process.

- - - -

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:

- - /req/dru/test-process

Ensure that an application package URL can be provided in CWL encodig to test deploying processes using OGC Application Package and CWL conformance classes.

-

If a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy is tested using CITE tests, it should provide a URL to an example application package encoded in CWL for tests against the OGC Application Package and CWL conformance classes.

- - - - - -Conformance Class Deploy, Replace, Undeploy - -Deploy, Replace, Undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/deploy-replace-undeployhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/deploy-replace-undeployTarget TypeWeb API /conf/dru/static-indicator /conf/dru/deploy/post-op /conf/dru/deploy/content-type /conf/dru/deploy/unsupported-content-type /conf/dru/replace/put-op /conf/dru/replace/content-type /conf/dru/undeploy/delete-op /conf/dru/undeploy/response /conf/dru/undeploy/response-immutable - - - - -Immutable processes - /conf/dru/static-indicatortarget/req/deploy-replace-undeploy/static-indicator

Validate that the process list contains processes with the mutable property.

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Issue an HTTP GET request for each path

    -
    3. -

  3. Validate the process list is composed of processes that get the mutable Boolean parameter set to true or false

    -
    4. -
- - - - - -Deploy operation - /conf/dru/deploy/post-optarget/req/deploy-replace-undeploy/deploy/post-op

Validate that the server support HTTP POST operation at the path /processes

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Issue an HTTP POST request for each path.

    -
    3. -

  3. Validate that the response header does not contain 405 Method not allowed

    -
    4. -
- - - - /conf/dru/deploy/content-typetarget/req/deploy-replace-undeploy/deploy/content-type

Validate that the server support the Content-type header to declare the media type of the request body

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Issue an HTTP POST request associated with an unsupported media type, i.e. text/plain.

    -
    3. -

  3. Validate the response using /conf/dru/deploy/unsupported-content-type

    -
    4. -
- - - - /conf/dru/deploy/unsupported-content-typetarget/req/deploy-replace-undeploy/deploy/unsupported-content-type

Validate that the server returns a 415 status code with a relevant exception

-

  1. Validate that a document was returned with an HTTP status code of 415.

    -
    2. -

  2. Validate that the document in the response body is conform to the exception.yaml schema.

    -
    3. -

  3. Validate that the type of the exception is “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/unsupported-media-type”.

    -
    4. -
- - - - - -Replace operation - /conf/dru/replace/put-optarget/req/deploy-replace-undeploy/replace/put-op

Validate that the server supports HTTP PUT operation at the path /processes

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is not an existing process id, i.e. not-existing-process.

    -
    3. -

  3. Issue an HTTP PUT request for each path.

    -
    4. -

  4. Validate that the response header does not contain 405 Method not allowed.

    -
    5. -
- - - - /conf/dru/replace/content-typetarget/req/deploy-replace-undeploy/replace/content-type

Validate that the server supports the Content-type header to declare the media type of the request body

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is a mutable process id.

    -
    3. -

  3. Issue an HTTP PUT request with an unsupported media type, i.e. text/plain, on each path.

    -
    4. -

  4. Validate the response using /conf/dru/deploy/unsupported-content-type

    -
    5. -
- - - - - -Undeploy operation - /conf/dru/undeploy/delete-optarget/req/deploy-replace-undeploy/undeploy/delete-op

Validate that the server supports HTTP DELETE operation at the path /processes/{processId}

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is not an existing process id, i.e. not-existing-process.

    -
    3. -

  3. Issue an HTTP DELETE request for each path.

    -
    4. -

  4. Validate that the response header does not contain 405 Method not allowed.

    -
    5. -
- - - - /conf/dru/undeploy/responsetarget/req/deploy-replace-undeploy/undeploy/response

Validate that the server returns a 204 status code when removing a mutable process

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is a mutable process id.

    -
    3. -

  3. Issue an HTTP DELETE request on one path.

    -
    4. -

  4. Validate that no content was returned with an HTTP status code of 204.

    -
    5. -
- - - - /conf/dru/undeploy/response-immutabletarget/req/deploy-replace-undeploy/deploy/response-immutable

Validate that the server returns a 403 status code when removing an immutable process

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is not a mutable process id.

    -
    3. -

  3. Issue an HTTP DELETE request on each path.

    -
    4. -

  4. Validate the response contains a document content, and was returned with an HTTP status code of 403

    -
    5. -

  5. Validate the document is conform to the exception.yaml schema.

    -
    6. -

  6. Validate the type of the exception is “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/immutable-process”.

    -
    7. -
- - - - - - -Conformance Class OGC Application Package - -OGC Application Packagehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/ogcapppkghttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/ogcapppkgTarget TypeWeb API /conf/ogcapppkg/deploy/body /conf/ogcapppkg/deploy/response /conf/ogcapppkg/deploy/response-success /conf/ogcapppkg/deploy/response-duplicate /conf/ogcapppkg/replace/body /conf/ogcapppkg/replace/response - - - - -Deploy operation - /conf/ogcapppkg/deploy/bodytarget/req/ogcapppkg/deploy/body

Validate that the server supports OGC Application Package encoding

-

  1. Retrieve all links from the landing page with “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” and /processes

    -
    2. -

  2. Issue an HTTP POST request using the content type “application/ogcapppkg+json” with as body a default OGC Application Package or the application package as reference, if any, on one path

    -
    3. -

  3. Validate the response with /conf/ogcapppkg/deploy/response

    -
    4. -

  4. Send the same POST request again

    -
    5. -

  5. Validate the response with /conf/ogcapppkg/deploy/response-duplicate

    -
    6. -
- - - - /conf/ogcapppkg/deploy/responsetarget/req/deploy-replace-undeploy/deploy/response-success

Validate that the server returns HTTP Status code 201 or 202

-

  1. Validate that a document is returned and the status code is 201 or 202

    -
    2. -

  2. If status code was 201, validate the document using /conf/ogcapppkg/deploy/response-success

    -
    3. -
- - - - /conf/ogcapppkg/deploy/response-successtarget/req/deploy-replace-undeploy/deploy/response-success

Validate that the server returns a Location header and a process summary

-

  1. Validate the Location header contains a URI of the deployed process.

    -
    2. -

  2. Validate the document conforms to the processSummary.yaml schema.

    -
    3. -
- - - - /conf/ogcapppkg/deploy/response-duplicatetarget/req/deploy-replace-undeploy/deploy/response-duplicate

Validate that the server return HTTP Status code 409

-

  1. Validate that the response contains a document content was returned with an HTTP status code of 409

    -
    2. -

  2. Validate that the document is conform to the JSON Schema: exception.yaml

    -
    3. -

  3. Validate that the type of the exception is “http://www.opengis.net/def/exceptions/ogcapi-processes-2/1.0/duplicated-process”.

    -
    4. -
- - - - - -Replace operation - /conf/ogcapppkg/replace/bodytarget/req/ogcapppkg/replace/body

Validate that the server supports OGC Application Package encoding

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is the process id retrieved from /conf/ogcapppkg/deploy/response-success.

    -
    3. -

  3. Issue an HTTP PUT request using the media type “application/ogcapppkg+json” with as body a default OGC Application Package or the application package URL, if any, for each path

    -
    4. -

  4. Validate the response with /conf/ogcapppkg/replace/response

    -
    5. -
- - - - /conf/ogcapppkg/replace/responsetarget/req/deploy-replace-undeploy/response-success

Validate that the server returns HTTP Status code 200, 202 or 204

-

  1. Validate that the status code is 200, 202 or 204.

    -
    2. -
- - - - - - -Conformance Class Docker - -Dockerhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/dockerhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/dockerTarget TypeWeb API /conf/docker/deploy/body /conf/docker/replace/body - - - - -Deploy operation - /conf/docker/deploy/bodytarget/rec/deploy-replace-undeploy/deploy/body-docker

Validate that the server supports deploy operation using a Docker image as execution unit

-

  1. Retrieve all links from the landing page with “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” and /processes

    -
    2. -

  2. Issue an HTTP POST request using the media type “application/ogcapppkg+json” with as body a default OGC Application Package

    -
    3. -

  3. Validate the response with /conf/ogcapppkg/deploy/response

    -
    4. -

  4. Send the same POST request again

    -
    5. -

  5. Validate the response with /conf/ogcapppkg/deploy/response-duplicate

    -
    6. -
- - - - - -Replace operation - /conf/docker/replace/bodytarget/req/docker/replace/body

Validate that the server support replace operation using a Docker image as execution unit

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is the process id retrieved from /conf/ogcapppkg/deploy/response-success.

    -
    3. -

  3. Send a PUT request for one path using the media type “application/ogcapppkg+json” with as body a default OGC Application Package

    -
    4. -

  4. Validate the response with /conf/ogcapppkg/replace/response

    -
    5. -
- - - - - - -Conformance Class CWL - -Common Workflow Languagehttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/cwlhttp://www.opengis.net/spec/ogcapi-processes-2/1.0/conf/cwlTarget TypeWeb API /conf/cwl/deploy/body /conf/cwl/replace/body - - - - -Deploy operation - /conf/cwl/deploy/bodytarget/req/cwl/deploy/body

Validate that the server support deploy operation using the Common Workflow Language encoding

-

  1. Retrieve all links from the landing page with “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” and /processes

    -
    2. -

  2. Issue an HTTP POST request using the media type “application/cwl” and the application package content

    -
    3. -

  3. Validate the response with /conf/ogcapppkg/deploy/response

    -
    4. -

  4. Send the same POST request again

    -
    5. -

  5. Validate the response with /conf/ogcapppkg/deploy/response-duplicate

    -
    6. -
- - - - - -Replace operation - /conf/cwl/replace/bodytarget/req/cwl/replace/body

Validate that the server support replace operation using the Common Workflow Language encoding

-

  1. Construct a path for each “rel=http://www.opengis.net/def/rel/ogc/1.0/processes” link on the landing page as well as for the {root}/processes path.

    -
    2. -

  2. Append /{processId} to each path, where {processId} is a mutable process id.

    -
    3. -

  3. Send a PUT request for one path using the media type “application/cwl” and the application package content

    -
    4. -

  4. Validate the response with /conf/ogcapppkg/replace/response

    -
    5. -
- - - - - -Revision History - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DateReleaseEditorPrimary clauses modifiedDescription
2020-05-19NonePanagiotis (Peter) A. VretanosallInitial check in of draft transactions extension.
2020-06-23NonePanagiotis (Peter) A. VretanosallAdd initial draft of an example Open API document
2021-10-18NonePanagiotis (Peter) A. VretanosallRename transaction directory to deploy_replace_undeploy.
2022-10-04NoneGérald FenoyallUse relative path to exception and problem+json
2022-10-05NoneGérald FenoyallUpdate the Deploy, Replace, Undeploy extension
2022-12-12NoneGérald FenoyallChange the status code to be returned (immutable)
2023-02-20NonePanagiotis (Peter) A. VretanosallRealign abstract test with requirements.
2023-05-30NoneGérald FenoyallUpdate status code and schema.
2023-10-16NoneGérald FenoyallAdd content to the Abstract Test Suite
2023-11-28NoneGérald FenoyallUpdate test for validating support of a given HTTP method
2023-12-06NoneGérald FenoyallAbstract Test Suite Updates
2023-12-07NoneGérald FenoyallFix mixed status code and value in security consideration
2023-12-08NoneGérald FenoyallAdd requirements for managing docker image as execution unit
2024-04-26NoneGérald FenoyallAdd section for retrieving formal description of a mutable process
- -Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

- - 2024-08-28 - -OGC API - - -Processes - - -Part 1: Core - - -OGC API — Processes — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-processes-1/1.0.0 - https://docs.ogc.org/is/18-062r2/18-062r2.html - 18-062r2 - - 2021-12-20 - - - - - - Benjamin Pross - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - -Open Geospatial Consortium - - - - 2 - en - - The OGC API — Processes — Part 1: Core Standard supports the wrapping of computational tasks into executable processes that can be offered by a server through a Web API and be invoked by a client application. The standard specifies a processing interface to communicate over a RESTful protocol using JavaScript Object Notation (JSON) encodings. The standard leverages concepts from the OGC Web Processing Service (WPS) 2.0 Interface Standard but does not require implementation of a WPS. - -By way of background and context, in many cases geospatial or location data, including data from sensors, must be processed before the information can be effectively used. The WPS Standard provides a standard interface that simplifies the task of making simple or complex computational geospatial processing services accessible via web services. Such services include well-known processes found in Geographic Information Systems (GIS) as well as specialized processes for spatiotemporal modeling and simulation. While the WPS standard was designed with spatial processing in mind, the standard could also be used to readily insert non-spatial processing tasks into a web services environment. - -The OGC API — Processes Standard is a newer and more modern way of programming and interacting with resources over the web while allowing better integration into existing software packages. The OGC API — Processes Standard addresses all of the use cases that were addressed by the WPS Standard, while also leveraging the OpenAPI specification and a resource-oriented approach. - -The resources that are provided by a server implementing the OGC API — Processes Standard are listed in Table 1 below and include information about the server, the list of available processes (Process list and Process description), jobs (running processes) and results of process executions. - - - - 2024-08-28 - -OGC API - - -Features - - -Part 1: Core - - -OGC API — Features — Part 1: Core - - http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.0 - https://docs.ogc.org/is/17-069r3/17-069r3.html - 17-069r3 - - 2019-10-07 - - - - - - Clemens Portele - - - - - - - - Panagiotis (Peter) A. Vretanos - - - - - - - - Charles Heazel - - - - - - - -Open Geospatial Consortium - - - - 3 - en - - OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks. - -The OGC API family of standards is organized by resource type. This standard specifies the fundamental API building blocks for interacting with features. The spatial data community uses the term ‘feature’ for things in the real world that are of interest. - - - -Bibliography - OpenAPI Initiative. OpenAPI Specification 3.0.2. Available at: -. - OpenAPI Specification 3.0.2 - 3.0.2 - - Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. - [2] - - OpenEO: OpenEO Developers API Reference / Process Graphs. - [3] - - - - - - From 160869af4a5aee30ae94f713ad56962138e90b54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 19:15:20 +0200 Subject: [PATCH 08/29] Remove the quotation and replace Recommendation by Permission --- .../create/PER_content-schema.adoc | 7 +++++++ .../update/PER_content-schema.adoc | 7 +++++++ .../create/PER_content-schema.adoc | 7 +++++++ .../update/PER_content-schema.adoc | 7 +++++++ .../openeo/create/PER_content-schema.adoc | 7 +++++++ .../openeo/update/PER_content-schema.adoc | 7 +++++++ .../update/REQ_content-type.adoc | 2 +- .../job-management/update/REQ_response.adoc | 1 - .../ogcapi-processes/REQ_body.adoc | 7 ------- .../REQ_process-description.adoc | 7 ------- .../ogcapi-processes/REQ_profile-docker.adoc | 7 ------- .../ogcapi-processes/REQ_schema.adoc | 2 +- .../definition/REQ_response-body.adoc | 2 +- .../requirements/openeo/REQ_body.adoc | 7 ------- .../openeo/REQ_process-description.adoc | 7 ------- .../openeo/REQ_profile-docker.adoc | 7 ------- .../requirements/openeo/create/REQ_body.adoc | 2 +- .../requirements/openeo/update/REQ_body.adoc | 2 +- .../requirements_class_ogcapi-processes.adoc | 1 + .../requirements_class_openeo.adoc | 1 - .../requirements_class_quotation.adoc | 11 ----------- .../sections/clause_11_media_types.adoc | 9 --------- .../sections/clause_3_references.adoc | 6 +++--- .../clause_4_terms_and_definitions.adoc | 19 ++----------------- .../sections/clause_6_job_management.adoc | 11 ++++++----- .../sections/clause_7_ogcapi-processes.adoc | 16 ++++++++++------ .../standard/sections/clause_8_openeo.adoc | 14 +++++++++----- 27 files changed, 78 insertions(+), 105 deletions(-) create mode 100644 extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc create mode 100644 extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc create mode 100644 extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc create mode 100644 extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc create mode 100644 extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc create mode 100644 extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc delete mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc delete mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc delete mode 100644 extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc delete mode 100644 extensions/job_management/standard/requirements/openeo/REQ_body.adoc delete mode 100644 extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc delete mode 100644 extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc delete mode 100644 extensions/job_management/standard/requirements/requirements_class_quotation.adoc diff --git a/extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc new file mode 100644 index 00000000..3872d04e --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc @@ -0,0 +1,7 @@ +[[per_job-management_create_content-schema]] +[permission] +==== +[%metadata] +label:: /per/job-management/create/content-schema +part:: The `Content-Schema` header MAY be an URI to a JSON or OpenAPI 3.0 Schema document that describes the structure of the request body. +==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc new file mode 100644 index 00000000..2b976b93 --- /dev/null +++ b/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc @@ -0,0 +1,7 @@ +[[per_job-management_update_content-schema]] +[permission] +==== +[%metadata] +label:: /per/job-management/update/content-schema +part:: The `Content-Schema` header MAY be used to indicate the schema of a request body for creating a job. +==== diff --git a/extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc new file mode 100644 index 00000000..e1eadef7 --- /dev/null +++ b/extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc @@ -0,0 +1,7 @@ +[[per_ogcapi-processes_create_content-schema]] +[permission] +==== +[%metadata] +label:: /per/ogcapi-processes/create/content-schema +part:: The `Content-Schema` header MAY be pointing to the OpenAPI 3.0 schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflows.yaml]. +==== diff --git a/extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc new file mode 100644 index 00000000..59539b1c --- /dev/null +++ b/extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc @@ -0,0 +1,7 @@ +[[per_ogcapi-processes_update_content-schema]] +[permission] +==== +[%metadata] +label:: /per/ogcapi-processes/update/content-schema +part:: The `Content-Schema` header MAY be pointing to the OpenAPI 3.0 schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflows.yaml]. +==== diff --git a/extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc new file mode 100644 index 00000000..7eed8051 --- /dev/null +++ b/extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc @@ -0,0 +1,7 @@ +[[per_openeo_create_content-schema]] +[permission] +==== +[%metadata] +label:: /per/openeo/create/content-schema +part:: The `Content-Schema` header MAY be pointing to https://raw.githubusercontent.com/Open-EO/openeo-processes/master/meta/subtype-schemas.json#/definitions/process-graph[OpenEO Process Graph schema]. +==== diff --git a/extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc new file mode 100644 index 00000000..1bee9208 --- /dev/null +++ b/extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc @@ -0,0 +1,7 @@ +[[per_openeo_update_content-schema]] +[permission] +==== +[%metadata] +label:: /per/openeo/update/content-schema +part:: The `Content-Schema` header MAY be pointing to https://raw.githubusercontent.com/Open-EO/openeo-processes/master/meta/subtype-schemas.json#/definitions/process-graph[OpenEO Process Graph schema]. +==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc index 3ceb094c..b9328329 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/job-management/update/content-type -part:: As per <> (https://tools.ietf.org/html/rfc2616#section-14.17) the 'Content-Type' header SHALL be used to indicate the media type of a request body containing the description of the replacement processes. +part:: As per <> (https://tools.ietf.org/html/rfc2616#section-14.17) the 'Content-Type' header SHALL be used to indicate the media type of a request body. ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc index 8bf0901c..4124f18d 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc @@ -4,5 +4,4 @@ [%metadata] label:: /req/job-management/update/response part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code `200` or `204`. -part:: If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code `202`. ==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc deleted file mode 100644 index 286bbc0d..00000000 --- a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_body.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_ogcappkg_body]] -[requirement] -==== -[%metadata] -label:: /req/ogcapppkg/body -part:: The media type `application/ogcapppkg+json` SHALL be used to indicate that request body contains a processes description encoded as an <>. -==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc deleted file mode 100644 index d483da05..00000000 --- a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_process-description.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_ogcapppkg_process-description]] -[requirement] -==== -[%metadata] -label:: /req/ogcapppkg/process-description -part:: The value of the processDescription property SHALL be based upon the OpenAPI schema https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/process.yaml[process.yaml]. -==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc deleted file mode 100644 index 04c0da48..00000000 --- a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_profile-docker.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_ogcapppkg_profile-docker]] -[requirement] -==== -[%metadata] -label:: /req/ogcapppkg/profile-docker -part:: If the execution unit is a Docker image, the value of the `deploymentProfile` property shall be `http://www.opengis.net/profiles/eoc/dockerizedApplication`. -==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc index 4ca75722..883341da 100644 --- a/extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc +++ b/extensions/job_management/standard/requirements/ogcapi-processes/REQ_schema.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/ogcapi-processes/schema -part:: An `OGC API - Processes` document SHALL be based upon the JSON schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflow.yaml]. +part:: An `OGC API - Processes - Workflow - Execute Request` document SHALL be based upon the JSON schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflow.yaml]. ==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc index 5a0eeb21..bdd2170b 100644 --- a/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/ogcapi-processes/definition/response-body -part:: A response with HTTP status code `200` SHALL include a body that contains the <> to use to deploy the process. +part:: A response with HTTP status code `200` SHALL include a body that contains the <> to use to deploy the process. ==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/REQ_body.adoc deleted file mode 100644 index 286bbc0d..00000000 --- a/extensions/job_management/standard/requirements/openeo/REQ_body.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_ogcappkg_body]] -[requirement] -==== -[%metadata] -label:: /req/ogcapppkg/body -part:: The media type `application/ogcapppkg+json` SHALL be used to indicate that request body contains a processes description encoded as an <>. -==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc b/extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc deleted file mode 100644 index d483da05..00000000 --- a/extensions/job_management/standard/requirements/openeo/REQ_process-description.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_ogcapppkg_process-description]] -[requirement] -==== -[%metadata] -label:: /req/ogcapppkg/process-description -part:: The value of the processDescription property SHALL be based upon the OpenAPI schema https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/process.yaml[process.yaml]. -==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc b/extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc deleted file mode 100644 index 04c0da48..00000000 --- a/extensions/job_management/standard/requirements/openeo/REQ_profile-docker.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_ogcapppkg_profile-docker]] -[requirement] -==== -[%metadata] -label:: /req/ogcapppkg/profile-docker -part:: If the execution unit is a Docker image, the value of the `deploymentProfile` property shall be `http://www.opengis.net/profiles/eoc/dockerizedApplication`. -==== diff --git a/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc index 21358437..87603fba 100644 --- a/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/openeo/create/body -part:: The media type `application/openeo+json` SHALL be used to indicate that request body contains a processes description encoded as an <>. +part:: The media type `application/json` SHALL be used to indicate that request body contains a processes description encoded as an <>. ==== diff --git a/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc index c8fbad9d..11cf3e2b 100644 --- a/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/openeo/update/body -part:: The media type `application/openeo+json` SHALL be used to indicate that request body contains a job encoded as an <>. +part:: The media type `application/json` SHALL be used to indicate that request body contains a job encoded as an <>. ==== diff --git a/extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc b/extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc index 630cb76a..8055d503 100644 --- a/extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc +++ b/extensions/job_management/standard/requirements/requirements_class_ogcapi-processes.adoc @@ -6,5 +6,6 @@ label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/ogcapi-processes obligation:: requirement subject:: Web API inherit:: <> +inherit:: <> inherit:: <> ==== diff --git a/extensions/job_management/standard/requirements/requirements_class_openeo.adoc b/extensions/job_management/standard/requirements/requirements_class_openeo.adoc index 4677ed90..33da4b0f 100644 --- a/extensions/job_management/standard/requirements/requirements_class_openeo.adoc +++ b/extensions/job_management/standard/requirements/requirements_class_openeo.adoc @@ -5,6 +5,5 @@ label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/openeo obligation:: requirement subject:: Web API -inherit:: <> inherit:: <> ==== diff --git a/extensions/job_management/standard/requirements/requirements_class_quotation.adoc b/extensions/job_management/standard/requirements/requirements_class_quotation.adoc deleted file mode 100644 index bb06ba07..00000000 --- a/extensions/job_management/standard/requirements/requirements_class_quotation.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[[rc_quotation]] -[requirements_class] -==== -[%metadata] -label:: http://www.opengis.net/spec/ogcapi-processes-4/1.0/req/quotation -obligation:: requirement -subject:: Web API -inherit:: <> -inherit:: <> -inherit:: <> -==== diff --git a/extensions/job_management/standard/sections/clause_11_media_types.adoc b/extensions/job_management/standard/sections/clause_11_media_types.adoc index 82e621ec..656fc359 100644 --- a/extensions/job_management/standard/sections/clause_11_media_types.adoc +++ b/extensions/job_management/standard/sections/clause_11_media_types.adoc @@ -2,12 +2,3 @@ == Media Types 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 - -Additional CWL media types that would typically be used in a server that supports CWL are: - -* application/cwl \ No newline at end of file diff --git a/extensions/job_management/standard/sections/clause_3_references.adoc b/extensions/job_management/standard/sections/clause_3_references.adoc index d03081c4..71ab4ace 100644 --- a/extensions/job_management/standard/sections/clause_3_references.adoc +++ b/extensions/job_management/standard/sections/clause_3_references.adoc @@ -4,10 +4,10 @@ * [[[OAProc-1,OGC 18-062]]] Pross, B.: OGC 18-062, *OGC API - Processes - Part 1: Core* -* [[[OAProc-2,OGC 20-044]]] Pross, B.: OGC 18-062, *OGC API - Processes - Part 2: Deploy, Replace, Undeploy* +* [[[OAProc-2,OGC 20-044]]] Fenoy, G.: OGC 20-044, *OGC API - Processes - Part 2: Deploy, Replace, Undeploy* -* [[[OAProc-3,OGC 18-062]]] Pross, B.: OGC 18-062, *OGC API - Processes - Part 1: Core* +* [[[OAProc-3,OGC 21-009]]] Jacovella-St-Louis J.: OGC 21-009, *OGC API - Processes - Part 3: Workflows* -* [[[OAFeat-1,OGC 17-069r3]]], OGC 17-069r3, OGC API - Features - Part 1: Core +* [[[OAFeat-1,OGC 17-069r3]]], OGC Portele C.: 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 diff --git a/extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc b/extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc index 7807e494..b81b8bf2 100644 --- a/extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc +++ b/extensions/job_management/standard/sections/clause_4_terms_and_definitions.adoc @@ -3,23 +3,8 @@ === Terms and definitions -==== Execution unit - -A component containing a process that an implementation of the Processes API Part 1 can run. - -==== Deploy - -Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard. - -==== Replace - -Replace refers to upgrading a deployed process from a Processes API implementation. - -==== Undeploy - -Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process. +See <>, Clause 4.1. === Abbreviated Terms -CWL:: Common Workflow Language -DRU:: Deploy, Replace, Undeploy +See <>, Clause 4.2. \ No newline at end of file diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index b1de6f88..77674064 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -106,6 +106,8 @@ include::../requirements/job-management/create/REQ_content-type.adoc[] See https://www.rfc-editor.org/rfc/rfc7231#section-3.1.1.5[section 3.1.1.5 of RFC 7231] for details. +include::../recommendations/job-management/create/PER_content-schema.adoc[] + ===== OGC API - Processes - Workflow Execute Request body include::../recommendations/job-management/create/REC_body-ogcapi-processes.adoc[] @@ -165,11 +167,13 @@ include::../recommendations/job-management/update/PER_body.adoc[] include::../requirements/job-management/update/REQ_content-type.adoc[] -===== OGC API - Processes - Workflow Execute Request body +include::../recommendations/job-management/update/PER_content-schema.adoc[] + +===== OGC API - Processes - Workflow Execute Request include::../recommendations/job-management/update/REC_body-ogcapi-processes.adoc[] -===== OpenEO Process Graph body +===== OpenEO Process Graph include::../recommendations/job-management/update/REC_body-openeo.adoc[] @@ -179,8 +183,6 @@ include::../requirements/job-management/update/REQ_response.adoc[] The status code depends on the server. If the server has replaced the job, the response is either `200` (if the response includes additional content) or `204` (if the response has no additional content). -If the server will process the replace request later, a `202` status code will be returned. In this case, the processing can succeed or fail, without further notification to the client. - ==== Exceptions See <> for general guidance. @@ -223,7 +225,6 @@ See <> for general guidance. If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. - [[job-management-definition]] === Job definition diff --git a/extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc b/extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc index 947e659e..8d624b1a 100644 --- a/extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc +++ b/extensions/job_management/standard/sections/clause_7_ogcapi-processes.adoc @@ -8,26 +8,30 @@ include::../requirements/requirements_class_ogcapi-processes.adoc[] This requirements class defines that the OGC API - Process - Workflow Execute Request is supported as an encoding for job definitions. -=== OGC API - Processes +=== OGC API - Processes - Workflow Execute Request ==== Overview include::../requirements/ogcapi-processes/REQ_schema.adoc[] -=== Create +=== Creating a new job -==== OGC API - Processes body +==== Request body include::../requirements/ogcapi-processes/create/REQ_body.adoc[] -=== Update +include::../recommendations/ogcapi-processes/create/PER_content-schema.adoc[] -==== OGC API - Processes body +=== Updating an existing job + +==== Request body include::../requirements/ogcapi-processes/update/REQ_body.adoc[] +include::../recommendations/ogcapi-processes/update/PER_content-schema.adoc[] + === Job definition -==== OGC API - Processes content +==== Response content include::../requirements/ogcapi-processes/definition/REQ_response-body.adoc[] \ No newline at end of file diff --git a/extensions/job_management/standard/sections/clause_8_openeo.adoc b/extensions/job_management/standard/sections/clause_8_openeo.adoc index b9689362..67b8eeba 100644 --- a/extensions/job_management/standard/sections/clause_8_openeo.adoc +++ b/extensions/job_management/standard/sections/clause_8_openeo.adoc @@ -21,20 +21,24 @@ include::../requirements/openeo/REQ_schema.adoc[] include::../../../../openapi/schemas/processes-job-management/openeo-process-graph.yaml[] ---- -=== Create +=== Creating a new job -==== OpenEO body +==== Request body include::../requirements/openeo/create/REQ_body.adoc[] -=== Update +include::../recommendations/openeo/create/PER_content-schema.adoc[] -==== OpenEO body +=== Updating an existing job + +==== Request body include::../requirements/openeo/update/REQ_body.adoc[] +include::../recommendations/openeo/update/PER_content-schema.adoc[] + === Job definition -==== OpenEO content +==== Response content include::../requirements/openeo/definition/REQ_response-body.adoc[] \ No newline at end of file From c127cb7d0c25cabc4d151a7fa333638726e37e69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 29 Aug 2024 19:48:52 +0200 Subject: [PATCH 09/29] Update statusCode.yaml to use created as mentioned in #419 --- openapi/schemas/processes-job-management/statusCode.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/schemas/processes-job-management/statusCode.yaml b/openapi/schemas/processes-job-management/statusCode.yaml index ccdde642..b4bf1e6e 100644 --- a/openapi/schemas/processes-job-management/statusCode.yaml +++ b/openapi/schemas/processes-job-management/statusCode.yaml @@ -1,7 +1,7 @@ type: string nullable: false enum: - - pending + - created - accepted - running - successful From c40f9f3d03725576a1e0d0054f3d567c7fb59315 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Mon, 2 Sep 2024 13:38:12 +0200 Subject: [PATCH 10/29] Use in place of in statusInfo Use a different OpenEO JSON Schema --- .../job-management/create/REQ_response-body.adoc | 2 +- .../standard/requirements/openeo/REQ_schema.adoc | 2 +- .../standard/sections/clause_6_job_management.adoc | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc index 8206f860..faf346fa 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc @@ -4,5 +4,5 @@ [%metadata] label:: /req/job-management/create/response-body part:: The response SHALL include a body that contains a status information of the created job conforms to the https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/statusInfo.yaml[statusInfo.yaml] schema. -part:: The response SHALL contains a `pending` status code and the `jobId` property that contains the job identifier. +part:: The response SHALL contains a `created` status code and the `jobId` property that contains the job identifier. ==== diff --git a/extensions/job_management/standard/requirements/openeo/REQ_schema.adoc b/extensions/job_management/standard/requirements/openeo/REQ_schema.adoc index c458ca50..84634a7f 100644 --- a/extensions/job_management/standard/requirements/openeo/REQ_schema.adoc +++ b/extensions/job_management/standard/requirements/openeo/REQ_schema.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/openeo/schema -part:: An `OpenEO Process Graph` document SHALL be based upon the JSON schema https://raw.githubusercontent.com/Open-EO/openeo-processes/master/meta/subtype-schemas.json#/definitions/process-graph. +part:: An `OpenEO Process Graph` document SHALL be based upon the OpenEO Process Graph JSON schema https://openeo.org/documentation/1.0/developers/api/assets/pg-schema.json. ==== diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 77674064..7779431b 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -15,12 +15,13 @@ The HTTP PUT method is used to update the definition of a previously created job Finally, the HTTP POST method is used to start a job. Creating or updating a job requires that a formal description of the new or -updated jobs be provided by the client. This Standard does +updated jobs be provided by the client. This Standar does not mandate that a specific jobs schema be used. However, this extension defines the following conformance classe: - * <>, that enables support for OpenEO-encoded jobs definition. + * <>, that enables support for OGC API - Processes - Part 3: Wofklows for jobs definitions. + * <>, that enables support for OpenEO-encoded jobs definitions. [[job-management-http_status_codes]] From de992c964ed1c449468094d18bf8cef8cc956e88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Mon, 2 Sep 2024 14:02:04 +0200 Subject: [PATCH 11/29] Typo in security section --- .../standard/sections/clause_12_security_considerations.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/job_management/standard/sections/clause_12_security_considerations.adoc b/extensions/job_management/standard/sections/clause_12_security_considerations.adoc index 3377d4a7..853730a8 100644 --- a/extensions/job_management/standard/sections/clause_12_security_considerations.adoc +++ b/extensions/job_management/standard/sections/clause_12_security_considerations.adoc @@ -7,8 +7,8 @@ Since creating and updating jobs will change the jobs available to a client, ser Users making modifications to process resources need to: . Be authenticated, -. Have "modification privileges" on the processes offered through the API, -. Have access to one or more of the POST and/or PUT methods on the processes /jobs/{jobId} endpoints. +. Have "modification privileges" on the jobs offered through the API, +. Have access to one or more of the POST and/or PUT methods on the jobs /jobs/{jobId} endpoints. The API definition, as defined in Clause 7.3 from <>, must reflect this in the resource paths and their available methods. From 18bad7286fbd243eea3dc372fad1de303860b032 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 5 Sep 2024 18:01:32 +0200 Subject: [PATCH 12/29] Fix Abstract test conformance class --- .../job_management/standard/abstract_tests/ATS_class_jm.adoc | 2 +- .../standard/abstract_tests/jm/create/ATS_post-op.adoc | 2 +- extensions/job_management/standard/sections/annex_ats.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc b/extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc index d6aaf738..29691f59 100644 --- a/extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc +++ b/extensions/job_management/standard/abstract_tests/ATS_class_jm.adoc @@ -1,4 +1,4 @@ -[[ats_dru]] +[[ats_jm]] [conformance_class] .Job Management ==== diff --git a/extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc b/extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc index a4e1809b..85451f21 100644 --- a/extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc +++ b/extensions/job_management/standard/abstract_tests/jm/create/ATS_post-op.adoc @@ -1,4 +1,4 @@ -[[ats_dru_deploy_post-op]] +[[ats_jm_deploy_post-op]] [abstract_test] ==== diff --git a/extensions/job_management/standard/sections/annex_ats.adoc b/extensions/job_management/standard/sections/annex_ats.adoc index 1a1e8744..91d9d95a 100644 --- a/extensions/job_management/standard/sections/annex_ats.adoc +++ b/extensions/job_management/standard/sections/annex_ats.adoc @@ -9,7 +9,7 @@ OGC Web Application Programming Interfaces (APIs) are not Web Services in the tr The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes "basic" and "bearer", API keys, and OAuth2 flow "authorizationCode". -=== Conformance Class Deploy, Replace, Undeploy +=== Conformance Class Job Management include::../abstract_tests/ATS_class_jm.adoc[] From 5469b35ce75f2feb1feaadd3884b4e3103215d16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 5 Sep 2024 18:46:42 +0200 Subject: [PATCH 13/29] Use PATCH method rather PUT to update the JOB Add the job-locked exception requirement --- .../requirements/job-management/update/REQ_body.adoc | 2 +- .../update/{REQ_put-op.adoc => REQ_patch-op.adoc} | 6 +++--- .../job-management/update/REQ_response-locked.adoc | 9 +++++++++ .../standard/sections/clause_6_job_management.adoc | 8 +++++--- 4 files changed, 18 insertions(+), 7 deletions(-) rename extensions/job_management/standard/requirements/job-management/update/{REQ_put-op.adoc => REQ_patch-op.adoc} (62%) create mode 100644 extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc index 6ae70501..0239f0bc 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/job-management/update/body* -part:: The body of a PUT request SHALL be in JSON format. +part:: The body of a PATCH request SHALL be in JSON format. ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_put-op.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc similarity index 62% rename from extensions/job_management/standard/requirements/job-management/update/REQ_put-op.adoc rename to extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc index 38f84197..15459a43 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_put-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc @@ -1,8 +1,8 @@ -[[req_job-management_update_put-op]] +[[req_job-management_update_patch-op]] [requirement] ==== [%metadata] -label:: /req/job-management/update/put-op -part:: For every created jobs (path '/jobs/{jobId}'), the server SHALL support the HTTP PUT operation. +label:: /req/job-management/update/patch-op +part:: For every created jobs (path '/jobs/{jobId}'), the server SHALL support the HTTP PATCH operation. part:: The parameter 'jobId' is each 'jobID' property in the jobs list response (JSONPath: `$.jobs[*].jobID`). ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc new file mode 100644 index 00000000..14c763fd --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc @@ -0,0 +1,9 @@ +[[req_job-management_update_response-locked]] +[requirement] +==== +[%metadata] +label:: /req/job-management/update/response-locked +part:: If a job is locked, meaning that it is currently being processed (status set to `accepted` or `running`), the server SHALL respond with HTTP status code `409 Conflict`. +part:: The response body SHALL be based upon the OpenAPI 3.0 schema https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/exception.yaml[exception.yaml]. +part:: The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-4/1.0/locked”. +==== diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 7779431b..327edc62 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -10,7 +10,7 @@ create, update and start jobs. The HTTP POST method is used to create new jobs. -The HTTP PUT method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint. +The HTTP PATCH method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint. Finally, the HTTP POST method is used to start a job. @@ -145,7 +145,7 @@ NOTE: The new job definition replaces the old job definition. Version control is ``` Client Server | | - | PUT /jobs/{jobId} HTTP/1.1 | + | PATCH /jobs/{jobId} HTTP/1.1 | | Content-Type: application/json | | | |------------------------------------------------------------>| @@ -156,7 +156,7 @@ Client Server ==== Operation -include::../requirements/job-management/update/REQ_put-op.adoc[] +include::../requirements/job-management/update/REQ_patch-op.adoc[] ==== Request body @@ -192,6 +192,8 @@ If the request body's media type is not supported by the server, see requirement If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. +include::../requirements/job-management/update/REQ_response-locked.adoc[] + [[undeploy]] === Staring a job From dfe6472800adaed0073f880a96c297b14637684a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 5 Sep 2024 18:54:00 +0200 Subject: [PATCH 14/29] Fix typo in front_material nad add reference to the exception when starting an execution --- .../standard/sections/clause_0_front_material.adoc | 2 +- .../standard/sections/clause_6_job_management.adoc | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/extensions/job_management/standard/sections/clause_0_front_material.adoc b/extensions/job_management/standard/sections/clause_0_front_material.adoc index 3d0ff1bc..c5cf3944 100644 --- a/extensions/job_management/standard/sections/clause_0_front_material.adoc +++ b/extensions/job_management/standard/sections/clause_0_front_material.adoc @@ -12,7 +12,7 @@ The OGC API - Processes - Part 3: Workflows draft specification extends the core The OGC API - Processes - Part 4: Job Management draft specification extends the core capabilities specified in OGC API - Processes - Part 1: Core [<>] with the ability to create, manage and monitor jobs that are associated with processes execution. This part of the standard also defines how to ensure provenance information is preserved and findable. -CAUTION: This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion. +CAUTION: This is a DRAFT version of the 4th part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion. == Submitters diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 327edc62..357b5f96 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -250,3 +250,5 @@ include::../requirements/job-management/definition/REQ_response-body.adoc[] See <> for general guidance. If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. + +If the job with the specified identifier is locked, see requirement /req/job-management/update/response-locked from <>. From a3ed0c0b1b6e5a3cb091aaec1b70a650e8718b2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 5 Sep 2024 19:15:06 +0200 Subject: [PATCH 15/29] Fix typo in sequence diagram --- .../standard/sections/clause_6_job_management.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 357b5f96..02eaf96d 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -206,7 +206,7 @@ the execution of a previously created jobs. ``` Client Server | | - | POST /jobs/{jobId} HTTP/1.1 | + | POST /jobs/{jobId}/results HTTP/1.1 | |------------------------------------------------------------>| | | | HTTP/1.1 204 OK | From a36f218070308f7c300a117d079b405075781735 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 5 Sep 2024 19:18:40 +0200 Subject: [PATCH 16/29] reference to the update exception job locked --- .../standard/sections/clause_6_job_management.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 02eaf96d..ed5c9914 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -68,7 +68,7 @@ See <>, section link:http://www.open -[[create]] +[[job-management-create]] === Creating a new job ==== Sequence diagram @@ -132,7 +132,7 @@ See <> for general guidance. If the request body's media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from <>. -[[update]] +[[job-management-update]] === Updating an existing job ==== Sequence diagram @@ -194,7 +194,7 @@ If the job with the specified identifier does not exist on the server, see requi include::../requirements/job-management/update/REQ_response-locked.adoc[] -[[undeploy]] +[[job-management-start]] === Staring a job ==== Sequence diagram @@ -251,4 +251,4 @@ See <> for general If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. -If the job with the specified identifier is locked, see requirement /req/job-management/update/response-locked from <>. +If the job with the specified identifier is locked, see requirement /req/job-management/update/response-locked from <>. From 16c0fdaefe286a00978c7e69f188348b7be8669a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 10 Sep 2024 18:29:37 +0200 Subject: [PATCH 17/29] Update after hearing from the GDC SWG meeting --- .../schemas/processes-core/statusCode.yaml | 2 +- .../schemas/processes-core/statusInfo.yaml | 4 +- .../processes-job-management/jobList.yaml | 13 +++++++ .../processes-type.yaml | 5 +++ .../processes-job-management/statusCode.yaml | 2 +- .../processes-job-management/statusInfo.yaml | 38 +++++++++++++++++++ 6 files changed, 60 insertions(+), 4 deletions(-) create mode 100644 openapi/schemas/processes-job-management/jobList.yaml create mode 100644 openapi/schemas/processes-job-management/processes-type.yaml create mode 100644 openapi/schemas/processes-job-management/statusInfo.yaml diff --git a/openapi/schemas/processes-core/statusCode.yaml b/openapi/schemas/processes-core/statusCode.yaml index f30262c9..8c6a6850 100644 --- a/openapi/schemas/processes-core/statusCode.yaml +++ b/openapi/schemas/processes-core/statusCode.yaml @@ -3,6 +3,6 @@ nullable: false enum: - accepted - running - - successful + - succeeded - failed - dismissed diff --git a/openapi/schemas/processes-core/statusInfo.yaml b/openapi/schemas/processes-core/statusInfo.yaml index 31afed5e..2324d49f 100644 --- a/openapi/schemas/processes-core/statusInfo.yaml +++ b/openapi/schemas/processes-core/statusInfo.yaml @@ -4,14 +4,14 @@ required: - status - type properties: + id: + type: string processID: type: string type: type: string enum: - process - jobID: - type: string status: $ref: "statusCode.yaml" message: diff --git a/openapi/schemas/processes-job-management/jobList.yaml b/openapi/schemas/processes-job-management/jobList.yaml new file mode 100644 index 00000000..6791b0d0 --- /dev/null +++ b/openapi/schemas/processes-job-management/jobList.yaml @@ -0,0 +1,13 @@ +type: object +required: + - jobs + - links +properties: + jobs: + type: array + items: + $ref: "statusInfo.yaml" + links: + type: array + items: + $ref: "../common-core/link.yaml" diff --git a/openapi/schemas/processes-job-management/processes-type.yaml b/openapi/schemas/processes-job-management/processes-type.yaml new file mode 100644 index 00000000..8a6f399f --- /dev/null +++ b/openapi/schemas/processes-job-management/processes-type.yaml @@ -0,0 +1,5 @@ +type: string +nullable: false +enum: + - process + - openeo diff --git a/openapi/schemas/processes-job-management/statusCode.yaml b/openapi/schemas/processes-job-management/statusCode.yaml index b4bf1e6e..e5c61562 100644 --- a/openapi/schemas/processes-job-management/statusCode.yaml +++ b/openapi/schemas/processes-job-management/statusCode.yaml @@ -4,6 +4,6 @@ enum: - created - accepted - running - - successful + - succeeded - failed - dismissed diff --git a/openapi/schemas/processes-job-management/statusInfo.yaml b/openapi/schemas/processes-job-management/statusInfo.yaml new file mode 100644 index 00000000..c6ca40b5 --- /dev/null +++ b/openapi/schemas/processes-job-management/statusInfo.yaml @@ -0,0 +1,38 @@ +type: object +required: + - id + - status + - type +properties: + id: + type: string + processID: + type: string + type: + $ref: "processes-type.yaml" + status: + $ref: "statusCode.yaml" + message: + type: string + exception: + $ref: "../common-core/exception.yaml" + created: + type: string + format: date-time + started: + type: string + format: date-time + finished: + type: string + format: date-time + updated: + type: string + format: date-time + progress: + type: integer + minimum: 0 + maximum: 100 + links: + type: array + items: + $ref: "../common-core/link.yaml" From 33677d85f5f9d3b21164a71e9634bf70fa65bb60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 12 Sep 2024 11:20:19 +0200 Subject: [PATCH 18/29] Typo in processes-core/statusInfo.yaml in required fields --- openapi/schemas/processes-core/statusInfo.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/schemas/processes-core/statusInfo.yaml b/openapi/schemas/processes-core/statusInfo.yaml index 2324d49f..b80f0bbc 100644 --- a/openapi/schemas/processes-core/statusInfo.yaml +++ b/openapi/schemas/processes-core/statusInfo.yaml @@ -1,12 +1,12 @@ type: object required: - - jobID + - id - status - type properties: id: type: string - processID: + process: type: string type: type: string From df465c50244a84ba828d89eda482a39ff3052e32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 24 Sep 2024 14:10:31 +0200 Subject: [PATCH 19/29] Take into acount the remarks made by @fmignault --- .gitignore | 1 + .../sections/clause_0_front_material.adoc | 2 +- extensions/job_management/.DS_Store | Bin 8196 -> 0 bytes extensions/job_management/README.md | 4 +++- extensions/job_management/standard/24-051.adoc | 2 +- extensions/job_management/standard/README.md | 2 +- .../abstract_tests/jm/create/ATS_post-op.adoc | 2 +- .../standard/recommendations/README.md | 2 +- .../PER_additional-status-codes.adoc | 2 +- .../definition/REC_response-cwl.adoc | 4 ++-- .../job-management/update/PER_body.adoc | 2 +- .../update/PER_content-schema.adoc | 2 +- .../job-management/create/REQ_response-body.adoc | 4 ++-- .../job-management/definition/REQ_get-op.adoc | 4 ++-- .../job-management/update/REQ_body.adoc | 2 +- .../update/REQ_response-locked.adoc | 2 +- .../processes-job-management/statusInfo.yaml | 2 +- 17 files changed, 21 insertions(+), 18 deletions(-) delete mode 100644 extensions/job_management/.DS_Store diff --git a/.gitignore b/.gitignore index d7cf78b7..c066f3e8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.DS_Store .idea .vscode *.pdf diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc index 297dbd50..0218e57e 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc @@ -20,5 +20,5 @@ All questions regarding this submission should be directed to the editors or the | Panagiotis (Peter) A. Vretanos _(editor)_ | CubeWerx Inc. | Gérald Fenoy _(editor)_ | GeoLabs | Pedro Gonçalves | Terradue Srl. -| Francis Charette Migneault | Centre de Recherche en Informatique de Montréal (CRIM) |=== + diff --git a/extensions/job_management/.DS_Store b/extensions/job_management/.DS_Store deleted file mode 100644 index af55a34c49d9869bc5141e4ae331815e6a78c28e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 8196 zcmeHMU2GIp6u#fIz|54|DYj5{0&HjmEL&-j7AY9E?H2hFLAIr(fa~ne028J&WoLF5 zB*aGJivdhD#wYRrQ4(YH0VTqd#5YYrRgB6*XulVCLX2%0D z0x<$H0x<$H0x<&j0s{2S=1rdCyDzM9A0rSWa9<+8-w#Q;xJ*ZKLdfvdL0wn^kmMym z*yx_>fY2uy$#f(qgbZEjnWB0?!l20d@j^u=p!kt05Gej#Rs!$NFPJYR7 zIzw8>xQ`Kt5txYpPam22ETGEWy|aGLJ6@h_pXJ9L+YdTAzJpX#J8%91d4XIfAI={0 zD%rpYN`9YFJjk^{&vWwCdn3Q!wkkQTso!%0!*;D==wO=`O*u4dyQWv^^GdGihrU^1 zkQG_UY5M8Y?VVj+kEW9Co4U@VlBYX6HguZe6_ezwpYzuYfEt4UNtyIu`VQS0>KkppT@TU4g~?->tl&-M3PMW19&Yw#(~9R<(b zTeP@+xZpXZG1t#&jRnIglpG_ldL1WgKWF(Pfps$AccZ>n4En=~BR2W+v7Dxrd~2UY z4tCkfkelB$ZSznrE^J=5a@E?7uAZ%#9lM{Ntbd?EYh0wNqXd>4*hg%uI8?FC;Mf7f zFIcW=yGMu1wr}ShYtS{utVU!MWwL(pl9r_jU7u^}NGWfhDA~a&tyPx8HI}c?)k7xj zX}4$cRZQ&@nVv(dx319jgWS?zw5T^Dht+Fzb>, implementations SHOULD consider supporting the <> encoding. diff --git a/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc b/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc index e380f46e..60094b97 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /per/job-management/update/body -part:: A server MAY support any encoding in the body of a HTTP PUT operation. +part:: A server MAY support any encoding in the body of a HTTP PATCH operation. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc index 2b976b93..06b0db9f 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /per/job-management/update/content-schema -part:: The `Content-Schema` header MAY be used to indicate the schema of a request body for creating a job. +part:: The `Content-Schema` header MAY be used to indicate the schema of a request body for updating a job. ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc index faf346fa..3f6712f0 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc @@ -3,6 +3,6 @@ ==== [%metadata] label:: /req/job-management/create/response-body -part:: The response SHALL include a body that contains a status information of the created job conforms to the https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/statusInfo.yaml[statusInfo.yaml] schema. -part:: The response SHALL contains a `created` status code and the `jobId` property that contains the job identifier. +part:: The response SHALL include a body that contains a status information of the created job that conforms to the https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/statusInfo.yaml[statusInfo.yaml] schema. +part:: The response SHALL contain a `created` status code and the `jobId` property that contains the job identifier. ==== diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc index d89a7165..5ce43cb0 100644 --- a/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc @@ -3,7 +3,7 @@ ==== [%metadata] label:: /req/job-management/definition/get-op -part:: For every dynamically added process (using method: POST on path: /processes/{processId}), the server SHALL support the HTTP GET operation at the path `/processes/{processId}/package`. -part:: The parameter `processId` is each `id` property in the process collection response (JSONPath: `$.processes[*].id`). +part:: For every jobs (using method: POST on path: /jobs/{jobId}), the server SHALL support the HTTP GET operation at the path `/jobs/{jobId}/definition`. +part:: The parameter `jobId` is each `id` property in the job-list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc index 0239f0bc..843e33cf 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/update/body* +label:: /req/job-management/update/body part:: The body of a PATCH request SHALL be in JSON format. ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc index 14c763fd..d75a8708 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc @@ -3,7 +3,7 @@ ==== [%metadata] label:: /req/job-management/update/response-locked -part:: If a job is locked, meaning that it is currently being processed (status set to `accepted` or `running`), the server SHALL respond with HTTP status code `409 Conflict`. +part:: If a job is locked, meaning that it is currently being processed (status set to `accepted` or `running`), the server SHALL respond with HTTP status code `423 Locked`. part:: The response body SHALL be based upon the OpenAPI 3.0 schema https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/exception.yaml[exception.yaml]. part:: The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-4/1.0/locked”. ==== diff --git a/openapi/schemas/processes-job-management/statusInfo.yaml b/openapi/schemas/processes-job-management/statusInfo.yaml index c6ca40b5..4f9accfd 100644 --- a/openapi/schemas/processes-job-management/statusInfo.yaml +++ b/openapi/schemas/processes-job-management/statusInfo.yaml @@ -6,7 +6,7 @@ required: properties: id: type: string - processID: + process: type: string type: $ref: "processes-type.yaml" From dacc37094755618aa55e1a5d29d3e0723ffd0027 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 24 Sep 2024 14:15:06 +0200 Subject: [PATCH 20/29] Add @fmignault as author of the draft --- .../job-management/definition/REC_response-cwl.adoc | 9 --------- .../definition/REC_response-ogcapppkg.adoc | 8 -------- .../standard/sections/clause_0_front_material.adoc | 1 + 3 files changed, 1 insertion(+), 17 deletions(-) delete mode 100644 extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc delete mode 100644 extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc diff --git a/extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc b/extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc deleted file mode 100644 index dea7d3f9..00000000 --- a/extensions/job_management/standard/recommendations/job-management/definition/REC_response-cwl.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[rec_job-management_package_response-cwl]] -[recommendation] -==== -[%metadata] -label:: /rec/job-management/package/response-cwl - -part:: If a process deployed as a <>, implementations SHOULD consider supporting the <> encoding. - -==== diff --git a/extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc b/extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc deleted file mode 100644 index 0de7b211..00000000 --- a/extensions/job_management/standard/recommendations/job-management/definition/REC_response-ogcapppkg.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[rec_deploy-replace-undeploy_package_response-ogcapppkg]] -[recommendation] -==== -[%metadata] -label:: /rec/deploy-replace-undeploy/package/response-ogcapppkg - -part:: If a process was deployed as an <>, implementations SHOULD consider supporting the <> encoding. -==== diff --git a/extensions/job_management/standard/sections/clause_0_front_material.adoc b/extensions/job_management/standard/sections/clause_0_front_material.adoc index c5cf3944..ec23fb8d 100644 --- a/extensions/job_management/standard/sections/clause_0_front_material.adoc +++ b/extensions/job_management/standard/sections/clause_0_front_material.adoc @@ -22,5 +22,6 @@ All questions regarding this submission should be directed to the editors or the |=== | Name | Affiliation | Gérald Fenoy _(editor)_ | GeoLabs +| Francis Charette Mignault _(editor)_ | Centre de recherche informatique de Montréal (CRIM) |=== From 60c04ab7073c90157e07ad7375e923a6423c9a21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 24 Sep 2024 15:56:34 +0200 Subject: [PATCH 21/29] Fix typo and add paths to the clause_6 --- .../job-management/PER_additional-status-codes.adoc | 2 +- .../requirements/job-management/create/REQ_body.adoc | 2 +- .../standard/sections/clause_6_job_management.adoc | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc b/extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc index f5cfbd31..6d477a7a 100644 --- a/extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc +++ b/extensions/job_management/standard/recommendations/job-management/PER_additional-status-codes.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/core/additional-status-codes +label:: /per/job-management/additional-status-codes part:: Servers MAY support other HTTP protocol capabilities. Therefore, the server may return other status codes than those listed in <>. ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc index c5b04bd4..88965636 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc @@ -1,4 +1,4 @@ -[[req_deploy-replace-undeploy_deploy_body]] +[[req_job-management_create_body]] [requirement] ==== [%metadata] diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index ed5c9914..95475d62 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -8,11 +8,11 @@ include::../requirements/requirements_class_job-management.adoc[] A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs. -The HTTP POST method is used to create new jobs. +The HTTP POST method on the `/jobs` path is used on to create new jobs. -The HTTP PATCH method is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint. +The HTTP PATCH method on the `/jobs/{jobId}` is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint. -Finally, the HTTP POST method is used to start a job. +Finally, the HTTP POST method on the `/job/{jobId}/results` is used to start a job. Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standar does not From 166d80516f6e69652cb3b17fffd5d086436024ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 24 Sep 2024 16:06:57 +0200 Subject: [PATCH 22/29] Fix typos --- .../requirements/job-management/start/REQ_start-op.adoc | 2 +- .../requirements/job-management/update/REQ_patch-op.adoc | 2 +- .../requirements/ogcapi-processes/update/REQ_body.adoc | 2 +- .../standard/requirements/provenance/inputs/REQ_get-op.adoc | 2 +- .../standard/requirements/provenance/outputs/REQ_get-op.adoc | 2 +- .../standard/requirements/provenance/run/REQ_get-op.adoc | 2 +- .../standard/sections/clause_6_job_management.adoc | 4 ++-- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc b/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc index e00e9e0a..fa724d48 100644 --- a/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc @@ -4,5 +4,5 @@ [%metadata] label:: /req/job-management/start/start-op part:: For every created jobs (path: `/jobs/{jobId}/results`), the server SHALL support the HTTP POST operation. -part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc index 15459a43..69188650 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc @@ -4,5 +4,5 @@ [%metadata] label:: /req/job-management/update/patch-op part:: For every created jobs (path '/jobs/{jobId}'), the server SHALL support the HTTP PATCH operation. -part:: The parameter 'jobId' is each 'jobID' property in the jobs list response (JSONPath: `$.jobs[*].jobID`). +part:: The parameter 'jobId' is each 'jobID' property in the jobs list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc index 77285285..d99660ed 100644 --- a/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc @@ -3,5 +3,5 @@ ==== [%metadata] label:: /req/ogcapi-processes/update/body -part:: The media type `application/ogcapi-processes+json` SHALL be used to indicate that request body contains a job encoded as an <>. +part:: The media type `application/ogcapi-processes+json` SHALL be used to indicate that request body contains a job encoded as an <>. ==== diff --git a/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc index 3d515131..598ea8d4 100644 --- a/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc @@ -4,5 +4,5 @@ [%metadata] label:: /req/provenance/inputs/get-op part:: For every created jobs (path: `/jobs/{jobId}/inputs`), the server SHALL support the HTTP GET operation. -part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc index 4f580354..cf122b03 100644 --- a/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc @@ -4,5 +4,5 @@ [%metadata] label:: /req/provenance/outputs/get-op part:: For every created jobs (path: `/jobs/{jobId}/outputs`), the server SHALL support the HTTP GET operation. -part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc index 6e5d2770..20b636bc 100644 --- a/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc @@ -4,5 +4,5 @@ [%metadata] label:: /req/provenance/run/get-op part:: For every created jobs (path: `/jobs/{jobId}/run`), the server SHALL support the HTTP GET operation. -part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].jobID`). +part:: The parameter `{jobId}` is each `id` property in the job list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 95475d62..2b9b6fd8 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -150,7 +150,7 @@ Client Server | | |------------------------------------------------------------>| | | - | HTTP/1.1 204 OK | + | HTTP/1.1 200 OK | |<------------------------------------------------------------| ``` @@ -209,7 +209,7 @@ Client Server | POST /jobs/{jobId}/results HTTP/1.1 | |------------------------------------------------------------>| | | - | HTTP/1.1 204 OK | + | HTTP/1.1 200 OK | |<------------------------------------------------------------| ``` From d12e0a63b939cc289d127f458b7188d60fd7892d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 24 Sep 2024 16:09:48 +0200 Subject: [PATCH 23/29] Update extensions/job_management/standard/sections/annex_bibliography.adoc Co-authored-by: Michael R. Crusoe <1330696+mr-c@users.noreply.github.com> --- .../job_management/standard/sections/annex_bibliography.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/job_management/standard/sections/annex_bibliography.adoc b/extensions/job_management/standard/sections/annex_bibliography.adoc index 351430db..af4cdf44 100644 --- a/extensions/job_management/standard/sections/annex_bibliography.adoc +++ b/extensions/job_management/standard/sections/annex_bibliography.adoc @@ -21,7 +21,7 @@ Springer LNCS is widely used in technical and computer science journals and othe // * [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2016): Common Workflow Language, v1.0. Specification, Common Workflow Language working group. https://w3id.org/cwl/v1.0/ https://doi.org/10.6084/m9.figshare.3115156.v2 -* [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. https://w3id.org/cwl/ +* [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. https://w3id.org/cwl/v1.2/ * [[[OpenEO_Process_Graphs,2]]], OpenEO: OpenEO Developers API Reference / Process Graphs. https://openeo.org/documentation/1.0/developers/api/reference.html#section/Processes/Process-Graphs From 37375036cdb6e0126179ab8a306692106c54007b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 24 Sep 2024 16:14:30 +0200 Subject: [PATCH 24/29] Update part 1 schema to remove the limitation for the type of job --- openapi/schemas/processes-core/statusInfo.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/openapi/schemas/processes-core/statusInfo.yaml b/openapi/schemas/processes-core/statusInfo.yaml index b80f0bbc..b6f1fc93 100644 --- a/openapi/schemas/processes-core/statusInfo.yaml +++ b/openapi/schemas/processes-core/statusInfo.yaml @@ -10,8 +10,10 @@ properties: type: string type: type: string - enum: + example: - process + - wps + - openeo status: $ref: "statusCode.yaml" message: From 80cbc5d2913aaebbdc6944aba8acd66f22bb6120 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Tue, 24 Sep 2024 16:25:12 +0200 Subject: [PATCH 25/29] Add unsupported-schema requirement for job-management/create --- .../job-management/create/REQ_unsupported-schema.adoc | 11 +++++++++++ .../standard/sections/clause_6_job_management.adoc | 4 ++++ 2 files changed, 15 insertions(+) create mode 100644 extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc new file mode 100644 index 00000000..85632fec --- /dev/null +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc @@ -0,0 +1,11 @@ +[[req_job-management_create_unsupported-schema]] +[requirement] +==== +[%metadata] +label:: /req/job-management/create/unsupported-schema + +part:: If the server does not support the Content-Schema header associated with the request body, the code of the response SHALL be `422 Unprocessable Content`. +part:: The content of that response SHALL be based upon the OpenAPI +3.0 schema https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/exception.yaml[exception.yaml]. +part:: The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-4/1.0/unsupported-schema”. +==== diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 2b9b6fd8..501a1b2f 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -132,6 +132,10 @@ See <> for general guidance. If the request body's media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from <>. +include::../requirements/job-management/create/REQ_unsupported-schema.adoc[] + + + [[job-management-update]] === Updating an existing job From 40e94ab0cad337a3bd56e97d75ad07e6f95f50d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 26 Sep 2024 15:33:07 +0200 Subject: [PATCH 26/29] Update following @fmignault comments https://github.com/opengeospatial/ogcapi-processes/pull/437/files#r1771964925 --- .../standard/sections/annex_bibliography.adoc | 2 +- .../run/PER_content-negotiation.adoc | 10 +++++++++ .../provenance/outputs/REQ_get-op.adoc | 8 ------- .../provenance/outputs/REQ_response.adoc | 8 ------- .../provenance/run/REQ_response.adoc | 9 ++++++++ .../sections/clause_6_job_management.adoc | 1 - .../sections/clause_9_provenance.adoc | 17 +++++--------- .../processes-job-management/inputs.yaml | 22 +++++++++++++++++-- .../processes-job-management/outputs.yaml | 3 --- 9 files changed, 46 insertions(+), 34 deletions(-) create mode 100644 extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc delete mode 100644 extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc delete mode 100644 extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc create mode 100644 extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc delete mode 100644 openapi/schemas/processes-job-management/outputs.yaml diff --git a/extensions/deploy_replace_undeploy/standard/sections/annex_bibliography.adoc b/extensions/deploy_replace_undeploy/standard/sections/annex_bibliography.adoc index 351430db..af4cdf44 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/annex_bibliography.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/annex_bibliography.adoc @@ -21,7 +21,7 @@ Springer LNCS is widely used in technical and computer science journals and othe // * [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2016): Common Workflow Language, v1.0. Specification, Common Workflow Language working group. https://w3id.org/cwl/v1.0/ https://doi.org/10.6084/m9.figshare.3115156.v2 -* [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. https://w3id.org/cwl/ +* [[[Common_Workflow_Language,1]]], Peter Amstutz, Michael R. Crusoe, Nebojša Tijanić (editors), Brad Chapman, John Chilton, Michael Heuer, Andrey Kartashov, Dan Leehr, Hervé Ménager, Maya Nedeljkovich, Matt Scales, Stian Soiland-Reyes, Luka Stojanovic (2020): Common Workflow Language, v1.2. Specification, Common Workflow Language working group. https://w3id.org/cwl/v1.2/ * [[[OpenEO_Process_Graphs,2]]], OpenEO: OpenEO Developers API Reference / Process Graphs. https://openeo.org/documentation/1.0/developers/api/reference.html#section/Processes/Process-Graphs diff --git a/extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc b/extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc new file mode 100644 index 00000000..443d4d87 --- /dev/null +++ b/extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc @@ -0,0 +1,10 @@ +[[per_job-provenance_run_content-negotiation]] +[permission] +==== +[%metadata] +label:: /per/provenance/run/content-negotiation +part:: Content negotiation MAY be supported to provide alternate representations of the response. +part:: The server MAY support the following additional content type: `application/ld+json` for PROV-O as JSON-LD +part:: The server MAY support the following additional content type: `application/xml` for PROV-XML +part:: The server MAY support the following additional content type: `text/provenance-notation; charset="UTF-8"` for PROV-N. +==== diff --git a/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc deleted file mode 100644 index cf122b03..00000000 --- a/extensions/job_management/standard/requirements/provenance/outputs/REQ_get-op.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[req_job-provenance_outputs_get-op]] -[requirement] -==== -[%metadata] -label:: /req/provenance/outputs/get-op -part:: For every created jobs (path: `/jobs/{jobId}/outputs`), the server SHALL support the HTTP GET operation. -part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].id`). -==== diff --git a/extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc b/extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc deleted file mode 100644 index a6ac8568..00000000 --- a/extensions/job_management/standard/requirements/provenance/outputs/REQ_response.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[req_provenance_outputs_response]] -[requirement] -==== -[%metadata] -label:: /req/provenance/outputs/response -part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. -part:: The response SHALL contains a JSON document that conforms to the schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-job-management/outputs.yaml[outputs.yaml]. -==== diff --git a/extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc b/extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc new file mode 100644 index 00000000..c659a687 --- /dev/null +++ b/extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc @@ -0,0 +1,9 @@ +[[req_provenance_run_response]] +[requirement] +==== +[%metadata] +label:: /req/provenance/run/response +part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. +part:: Per default, the response SHALL contains a JSON document that conforms to the https://www.w3.org/submissions/prov-json/schema[schema for PROV-JSON]. +part:: In case content-negotiation is used, the response MAY contain other representations including PROV-O as JSON-LD, PROV-XML or PROV-N. +==== diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index 501a1b2f..ddfce94b 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -135,7 +135,6 @@ If the request body's media type is not supported by the server, see requirement include::../requirements/job-management/create/REQ_unsupported-schema.adoc[] - [[job-management-update]] === Updating an existing job diff --git a/extensions/job_management/standard/sections/clause_9_provenance.adoc b/extensions/job_management/standard/sections/clause_9_provenance.adoc index ca2e76c5..ab3d4e1a 100644 --- a/extensions/job_management/standard/sections/clause_9_provenance.adoc +++ b/extensions/job_management/standard/sections/clause_9_provenance.adoc @@ -21,23 +21,18 @@ include::../requirements/provenance/inputs/REQ_get-op.adoc[] include::../requirements/provenance/inputs/REQ_response.adoc[] -==== Outputs +==== Run -The server MUST provide an endpoint to retrieve the outputs of a job run. +The server MUST provide an endpoint to retrieve the run of a job. ===== Operation -include::../requirements/provenance/outputs/REQ_get-op.adoc[] - -===== Response +include::../requirements/provenance/run/REQ_get-op.adoc[] -include::../requirements/provenance/outputs/REQ_response.adoc[] +include::../recommendations/provenance/run/PER_content-negotiation.adoc[] -==== Run +===== Response -The server MUST provide an endpoint to retrieve the run of a job. +include::../requirements/provenance/run/REQ_response.adoc[] -===== Operation - -include::../requirements/provenance/run/REQ_get-op.adoc[] diff --git a/openapi/schemas/processes-job-management/inputs.yaml b/openapi/schemas/processes-job-management/inputs.yaml index 77bf8df0..88701fe2 100644 --- a/openapi/schemas/processes-job-management/inputs.yaml +++ b/openapi/schemas/processes-job-management/inputs.yaml @@ -1,3 +1,21 @@ type: object -additionalProperties: - $ref: "input.yaml" \ No newline at end of file +required: + - inputs + - outputs +properties: + inputs: + type: object + additionalProperties: + $ref: "../processes-workflow/input-workflow.yaml" + outputs: + type: object + additionalProperties: + $ref: "../processes-workflow/output-workflow.yaml" + links: + type: array + items: + $ref: "../common-core/link.yaml" + metadata: + type: array + items: + $ref: "../processes-core/metadata.yaml" diff --git a/openapi/schemas/processes-job-management/outputs.yaml b/openapi/schemas/processes-job-management/outputs.yaml deleted file mode 100644 index 04f0bfe4..00000000 --- a/openapi/schemas/processes-job-management/outputs.yaml +++ /dev/null @@ -1,3 +0,0 @@ -type: object -additionalProperties: - $ref: "output.yaml" \ No newline at end of file From 06656a8cacb7acd6fccf3e7173a023881c1bd46f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Mon, 30 Sep 2024 16:35:19 +0200 Subject: [PATCH 27/29] Update the requirements / permissions / recommendations conform to OGC-NA --- .../recommendations/job-management/create/PER_body.adoc | 2 +- .../job-management/create/PER_content-schema.adoc | 2 +- .../job-management/create/REC_body-ogcapi-processes.adoc | 2 +- .../job-management/create/REC_body-openeo.adoc | 2 +- .../recommendations/job-management/update/PER_body.adoc | 2 +- .../job-management/update/PER_content-schema.adoc | 2 +- .../job-management/update/REC_body-ogcapi-processes.adoc | 2 +- .../job-management/update/REC_body-openeo.adoc | 2 +- .../ogcapi-processes/create/PER_content-schema.adoc | 2 +- .../ogcapi-processes/update/PER_content-schema.adoc | 2 +- .../recommendations/openeo/create/PER_content-schema.adoc | 2 +- .../recommendations/openeo/update/PER_content-schema.adoc | 2 +- .../provenance/run/PER_content-negotiation.adoc | 2 +- .../standard/requirements/job-management/create/REQ_body.adoc | 2 +- .../requirements/job-management/create/REQ_content-type.adoc | 2 +- .../requirements/job-management/create/REQ_post-op.adoc | 2 +- .../requirements/job-management/create/REQ_response-body.adoc | 2 +- .../job-management/create/REQ_response-jobid.adoc | 2 +- .../job-management/create/REQ_response-success.adoc | 2 +- .../job-management/create/REQ_unsupported-media-type.adoc | 2 +- .../job-management/create/REQ_unsupported-schema.adoc | 2 +- .../requirements/job-management/definition/REQ_get-op.adoc | 2 +- .../job-management/definition/REQ_response-body.adoc | 2 +- .../job-management/definition/REQ_response-success.adoc | 2 +- .../start/{REQ_start-op.adoc => REQ_post-op.adoc} | 4 ++-- .../requirements/job-management/start/REQ_response.adoc | 2 +- .../standard/requirements/job-management/update/REQ_body.adoc | 2 +- .../requirements/job-management/update/REQ_content-type.adoc | 2 +- .../requirements/job-management/update/REQ_patch-op.adoc | 2 +- .../job-management/update/REQ_response-locked.adoc | 2 +- .../requirements/job-management/update/REQ_response.adoc | 2 +- .../requirements/ogcapi-processes/create/REQ_body.adoc | 2 +- .../ogcapi-processes/definition/REQ_response-body.adoc | 2 +- .../requirements/ogcapi-processes/update/REQ_body.adoc | 2 +- .../standard/requirements/openeo/create/REQ_body.adoc | 2 +- .../requirements/openeo/definition/REQ_response-body.adoc | 2 +- .../standard/requirements/openeo/update/REQ_body.adoc | 2 +- .../standard/requirements/provenance/inputs/REQ_get-op.adoc | 2 +- .../standard/requirements/provenance/inputs/REQ_response.adoc | 2 +- .../standard/requirements/provenance/run/REQ_get-op.adoc | 2 +- .../standard/requirements/provenance/run/REQ_response.adoc | 2 +- .../standard/sections/clause_6_job_management.adoc | 2 +- 42 files changed, 43 insertions(+), 43 deletions(-) rename extensions/job_management/standard/requirements/job-management/start/{REQ_start-op.adoc => REQ_post-op.adoc} (75%) diff --git a/extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc b/extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc index bda2f16c..226bdafc 100644 --- a/extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc +++ b/extensions/job_management/standard/recommendations/job-management/create/PER_body.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/job-management/create/body +label:: /per/job-management/create-body part:: A server MAY support any encoding in the body of a HTTP POST operation. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc index 3872d04e..a08ca702 100644 --- a/extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc +++ b/extensions/job_management/standard/recommendations/job-management/create/PER_content-schema.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/job-management/create/content-schema +label:: /per/job-management/create-content-schema part:: The `Content-Schema` header MAY be an URI to a JSON or OpenAPI 3.0 Schema document that describes the structure of the request body. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc b/extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc index fc7a9df8..639d65c1 100644 --- a/extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc +++ b/extensions/job_management/standard/recommendations/job-management/create/REC_body-ogcapi-processes.adoc @@ -2,7 +2,7 @@ [recommendation] ==== [%metadata] -label:: /rec/job-management/create/body-ogcapi-processes +label:: /rec/job-management/create-body-ogcapi-processes part:: If the job can be encoded as an <>, implementation SHOULD consider supporting the <> encoding. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc b/extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc index bc924f5c..c352c0f5 100644 --- a/extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc +++ b/extensions/job_management/standard/recommendations/job-management/create/REC_body-openeo.adoc @@ -2,7 +2,7 @@ [recommendation] ==== [%metadata] -label:: /rec/job-management/create/body-openeo +label:: /rec/job-management/create-body-openeo part:: If the job can be encoded as an <>, implementation SHOULD consider supporting the <> encoding. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc b/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc index 60094b97..1cbdf74f 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/PER_body.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/job-management/update/body +label:: /per/job-management/update-body part:: A server MAY support any encoding in the body of a HTTP PATCH operation. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc index 06b0db9f..b7f4b949 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/PER_content-schema.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/job-management/update/content-schema +label:: /per/job-management/update-content-schema part:: The `Content-Schema` header MAY be used to indicate the schema of a request body for updating a job. ==== diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc index bd66fb6c..04cac3ae 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/REC_body-ogcapi-processes.adoc @@ -2,7 +2,7 @@ [recommendation] ==== [%metadata] -label:: /rec/job-management/update/body-ogcapi-processes +label:: /rec/job-management/update-body-ogcapi-processes part:: If a job can be created from an <>, implementations SHOULD consider supporting the <> encoding. diff --git a/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc b/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc index 460ad751..a9aebe4e 100644 --- a/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc +++ b/extensions/job_management/standard/recommendations/job-management/update/REC_body-openeo.adoc @@ -2,7 +2,7 @@ [recommendation] ==== [%metadata] -label:: /rec/job-management/update/body-openeo +label:: /rec/job-management/update-body-openeo part:: If a job can be created from an <>, implementations SHOULD consider supporting the <> encoding. diff --git a/extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc index e1eadef7..b045e411 100644 --- a/extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc +++ b/extensions/job_management/standard/recommendations/ogcapi-processes/create/PER_content-schema.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/ogcapi-processes/create/content-schema +label:: /per/ogcapi-processes/create-content-schema part:: The `Content-Schema` header MAY be pointing to the OpenAPI 3.0 schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflows.yaml]. ==== diff --git a/extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc index 59539b1c..971cd3d3 100644 --- a/extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc +++ b/extensions/job_management/standard/recommendations/ogcapi-processes/update/PER_content-schema.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/ogcapi-processes/update/content-schema +label:: /per/ogcapi-processes/update-content-schema part:: The `Content-Schema` header MAY be pointing to the OpenAPI 3.0 schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflows.yaml]. ==== diff --git a/extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc index 7eed8051..d332114f 100644 --- a/extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc +++ b/extensions/job_management/standard/recommendations/openeo/create/PER_content-schema.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/openeo/create/content-schema +label:: /per/openeo/create-content-schema part:: The `Content-Schema` header MAY be pointing to https://raw.githubusercontent.com/Open-EO/openeo-processes/master/meta/subtype-schemas.json#/definitions/process-graph[OpenEO Process Graph schema]. ==== diff --git a/extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc b/extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc index 1bee9208..fbe1c196 100644 --- a/extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc +++ b/extensions/job_management/standard/recommendations/openeo/update/PER_content-schema.adoc @@ -2,6 +2,6 @@ [permission] ==== [%metadata] -label:: /per/openeo/update/content-schema +label:: /per/openeo/update-content-schema part:: The `Content-Schema` header MAY be pointing to https://raw.githubusercontent.com/Open-EO/openeo-processes/master/meta/subtype-schemas.json#/definitions/process-graph[OpenEO Process Graph schema]. ==== diff --git a/extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc b/extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc index 443d4d87..4feb104a 100644 --- a/extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc +++ b/extensions/job_management/standard/recommendations/provenance/run/PER_content-negotiation.adoc @@ -2,7 +2,7 @@ [permission] ==== [%metadata] -label:: /per/provenance/run/content-negotiation +label:: /per/provenance/run-content-negotiation part:: Content negotiation MAY be supported to provide alternate representations of the response. part:: The server MAY support the following additional content type: `application/ld+json` for PROV-O as JSON-LD part:: The server MAY support the following additional content type: `application/xml` for PROV-XML diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc index 88965636..f5569e5c 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/body +label:: /req/job-management/create-body part:: The body of the POST request SHALL be in JSON format. ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc index 0282edc2..fd7f0ac2 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_content-type.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/content-type +label:: /req/job-management/create-content-type part:: The `Content-Type` https://tools.ietf.org/html/rfc2616#section-14.17[header] SHALL be used to declare the media type of the request. ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc index dc8dca0e..a6519248 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_post-op.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/post-op +label:: /req/job-management/create-post-op part:: The server SHALL support the HTTP POST operation at the path `/jobs`. ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc index 3f6712f0..764d1639 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/response-body +label:: /req/job-management/create-response-body part:: The response SHALL include a body that contains a status information of the created job that conforms to the https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/statusInfo.yaml[statusInfo.yaml] schema. part:: The response SHALL contain a `created` status code and the `jobId` property that contains the job identifier. ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc index 0f250b65..bd8ec9c9 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-jobid.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/response-jobid +label:: /req/job-management/create-response-jobid part:: If the operation completes, the server SHALL generate a job identifier (i.e. `{jobId}`) for the created job. ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc index 026c1a02..aea1e23f 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-success.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/response-success +label:: /req/job-management/create-response-success part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code `201`. part:: A response with HTTP status code `201` SHALL include a `Location` header with the URI of the deployed processes (path: `/jobs/{jobId}`). ==== diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc index 4a433a58..504e2949 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-media-type.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/unsupported-media-type +label:: /req/job-management/create-unsupported-media-type part:: If the server does not support the Content-Type header associated with the request body, the code of the response SHALL be `415 Unsupported Media Type`. part:: The content of that response SHALL be based upon the OpenAPI diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc index 85632fec..a0a94d1a 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_unsupported-schema.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/create/unsupported-schema +label:: /req/job-management/create-unsupported-schema part:: If the server does not support the Content-Schema header associated with the request body, the code of the response SHALL be `422 Unprocessable Content`. part:: The content of that response SHALL be based upon the OpenAPI diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc index 5ce43cb0..f3a25f2d 100644 --- a/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_get-op.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/definition/get-op +label:: /req/job-management/definition-get-op part:: For every jobs (using method: POST on path: /jobs/{jobId}), the server SHALL support the HTTP GET operation at the path `/jobs/{jobId}/definition`. part:: The parameter `jobId` is each `id` property in the job-list response (JSONPath: `$.jobs[*].id`). diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc index 5f9faf06..64ea12ca 100644 --- a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/definition/response-body +label:: /req/job-management/definition-response-body part:: A response with HTTP status code `200` SHALL include a body that contains the request body used to create or update the job. ==== diff --git a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc index b638a2d7..ce526a09 100644 --- a/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc +++ b/extensions/job_management/standard/requirements/job-management/definition/REQ_response-success.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/definition/response-success +label:: /req/job-management/definition-response-success part:: A successful access to the resource SHALL be reported as a response with a HTTP status code `200`. ==== diff --git a/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc b/extensions/job_management/standard/requirements/job-management/start/REQ_post-op.adoc similarity index 75% rename from extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc rename to extensions/job_management/standard/requirements/job-management/start/REQ_post-op.adoc index fa724d48..ec2a6278 100644 --- a/extensions/job_management/standard/requirements/job-management/start/REQ_start-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/start/REQ_post-op.adoc @@ -1,8 +1,8 @@ -[[req_job-management_start_start-op]] +[[req_job-management_start_post-op]] [requirement] ==== [%metadata] -label:: /req/job-management/start/start-op +label:: /req/job-management/start-post-op part:: For every created jobs (path: `/jobs/{jobId}/results`), the server SHALL support the HTTP POST operation. part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc b/extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc index 14d351e4..15d04d16 100644 --- a/extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc +++ b/extensions/job_management/standard/requirements/job-management/start/REQ_response.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/start/response +label:: /req/job-management/start-response part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. part:: A response SHALL be a document that conforms to statusInfo.yaml. ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc index 843e33cf..57eb938d 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/update/body +label:: /req/job-management/update-body part:: The body of a PATCH request SHALL be in JSON format. ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc index b9328329..797615ca 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_content-type.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/update/content-type +label:: /req/job-management/update-content-type part:: As per <> (https://tools.ietf.org/html/rfc2616#section-14.17) the 'Content-Type' header SHALL be used to indicate the media type of a request body. ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc index 69188650..75a25576 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_patch-op.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/update/patch-op +label:: /req/job-management/update-patch-op part:: For every created jobs (path '/jobs/{jobId}'), the server SHALL support the HTTP PATCH operation. part:: The parameter 'jobId' is each 'jobID' property in the jobs list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc index d75a8708..14dc811c 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_response-locked.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/job-management/update/response-locked +label:: /req/job-management/update-response-locked part:: If a job is locked, meaning that it is currently being processed (status set to `accepted` or `running`), the server SHALL respond with HTTP status code `423 Locked`. part:: The response body SHALL be based upon the OpenAPI 3.0 schema https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/core/openapi/schemas/exception.yaml[exception.yaml]. part:: The `type` of the exception SHALL be “http://www.opengis.net/def/exceptions/ogcapi-processes-4/1.0/locked”. diff --git a/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc b/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc index 4124f18d..8bcc709a 100644 --- a/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc +++ b/extensions/job_management/standard/requirements/job-management/update/REQ_response.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/job-management/update/response +label:: /req/job-management/update-response part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code `200` or `204`. ==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc index 01b6d117..22902e62 100644 --- a/extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/ogcapi-processes/create/REQ_body.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/ogcapi-processes/create/body +label:: /req/ogcapi-processes/create-body part:: The body of the POST request SHALL be based upon the OpenAPI 3.0 schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-workflows/execute-workflows.yaml[execute-workflows.yaml] part:: The media type `application/json` SHALL be used to indicate that request body contains a processes description encoded as an <>. ==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc index bdd2170b..145d0a76 100644 --- a/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/ogcapi-processes/definition/REQ_response-body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/ogcapi-processes/definition/response-body +label:: /req/ogcapi-processes/definition-response-body part:: A response with HTTP status code `200` SHALL include a body that contains the <> to use to deploy the process. ==== diff --git a/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc b/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc index d99660ed..fcb3e18d 100644 --- a/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/ogcapi-processes/update/REQ_body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/ogcapi-processes/update/body +label:: /req/ogcapi-processes/update-body part:: The media type `application/ogcapi-processes+json` SHALL be used to indicate that request body contains a job encoded as an <>. ==== diff --git a/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc index 87603fba..4a24c5ba 100644 --- a/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/openeo/create/REQ_body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/openeo/create/body +label:: /req/openeo/create-body part:: The media type `application/json` SHALL be used to indicate that request body contains a processes description encoded as an <>. ==== diff --git a/extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc b/extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc index 7dfdcdd9..3bd5c4dc 100644 --- a/extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/openeo/definition/REQ_response-body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/openeo/definition/response-body +label:: /req/openeo/definition-response-body part:: A response with HTTP status code `200` SHALL include a body that contains the <> to use to deploy the process. ==== diff --git a/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc b/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc index 11cf3e2b..ed51285a 100644 --- a/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc +++ b/extensions/job_management/standard/requirements/openeo/update/REQ_body.adoc @@ -2,6 +2,6 @@ [requirement] ==== [%metadata] -label:: /req/openeo/update/body +label:: /req/openeo/update-body part:: The media type `application/json` SHALL be used to indicate that request body contains a job encoded as an <>. ==== diff --git a/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc index 598ea8d4..d4174f99 100644 --- a/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/provenance/inputs/REQ_get-op.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/provenance/inputs/get-op +label:: /req/provenance/inputs-get-op part:: For every created jobs (path: `/jobs/{jobId}/inputs`), the server SHALL support the HTTP GET operation. part:: The parameter `jobId` is each `jobID` property in the job list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc b/extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc index 4b0307e7..9d4d29a3 100644 --- a/extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc +++ b/extensions/job_management/standard/requirements/provenance/inputs/REQ_response.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/provenance/inputs/response +label:: /req/provenance/inputs-response part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. part:: The response SHALL contains a JSON document that conforms to the schema https://github.com/opengeospatial/ogcapi-processes/blob/master/openapi/schemas/processes-job-management/inputs.yaml[inputs.yaml]. ==== diff --git a/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc b/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc index 20b636bc..a2ca4da7 100644 --- a/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc +++ b/extensions/job_management/standard/requirements/provenance/run/REQ_get-op.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/provenance/run/get-op +label:: /req/provenance/run-get-op part:: For every created jobs (path: `/jobs/{jobId}/run`), the server SHALL support the HTTP GET operation. part:: The parameter `{jobId}` is each `id` property in the job list response (JSONPath: `$.jobs[*].id`). ==== diff --git a/extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc b/extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc index c659a687..f31d4963 100644 --- a/extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc +++ b/extensions/job_management/standard/requirements/provenance/run/REQ_response.adoc @@ -2,7 +2,7 @@ [requirement] ==== [%metadata] -label:: /req/provenance/run/response +label:: /req/provenance/run-response part:: A successful execution of the operation SHALL be reported as a response with a HTTP status code '200'. part:: Per default, the response SHALL contains a JSON document that conforms to the https://www.w3.org/submissions/prov-json/schema[schema for PROV-JSON]. part:: In case content-negotiation is used, the response MAY contain other representations including PROV-O as JSON-LD, PROV-XML or PROV-N. diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index ddfce94b..bdd7d53c 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -218,7 +218,7 @@ Client Server ==== Operation -include::../requirements/job-management/start/REQ_start-op.adoc[] +include::../requirements/job-management/start/REQ_post-op.adoc[] ==== Response From 7b79c502c609ee7ea352499a7fc521ab16551a65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Mon, 30 Sep 2024 17:24:18 +0200 Subject: [PATCH 28/29] Revert to processID in the statusInfo.yaml schema --- openapi/schemas/processes-core/statusInfo.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/schemas/processes-core/statusInfo.yaml b/openapi/schemas/processes-core/statusInfo.yaml index b6f1fc93..85e4eb3e 100644 --- a/openapi/schemas/processes-core/statusInfo.yaml +++ b/openapi/schemas/processes-core/statusInfo.yaml @@ -6,7 +6,7 @@ required: properties: id: type: string - process: + processID: type: string type: type: string From efb4e8e32af27c626771dbaf1f00686e4c66ae08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Fenoy?= Date: Thu, 17 Oct 2024 15:47:05 +0200 Subject: [PATCH 29/29] Update part 4 with required missing files identified by @fmigneault Add @pvretano as submitter --- .../create/REQ_response-body.adoc | 2 +- .../sections/clause_0_front_material.adoc | 1 + .../sections/clause_6_job_management.adoc | 3 +- .../paths/processes-job-management/pJob.yaml | 53 +++++++++++++++++++ .../pJobDefinition.yaml | 16 ++++++ .../processes-job-management/pJobInputs.yaml | 16 ++++++ .../processes-job-management/pJobResults.yaml | 24 +++++++++ .../processes-job-management/pJobsList.yaml | 50 +++++++++++++++++ .../processes-job-management/rInputs.yaml | 8 +++ .../processes-job-management/rLocked.yaml | 8 +++ .../rUnsupportedSchema.yaml | 8 +++ 11 files changed, 187 insertions(+), 2 deletions(-) create mode 100644 openapi/paths/processes-job-management/pJob.yaml create mode 100644 openapi/paths/processes-job-management/pJobDefinition.yaml create mode 100644 openapi/paths/processes-job-management/pJobInputs.yaml create mode 100644 openapi/paths/processes-job-management/pJobResults.yaml create mode 100644 openapi/paths/processes-job-management/pJobsList.yaml create mode 100644 openapi/responses/processes-job-management/rInputs.yaml create mode 100644 openapi/responses/processes-job-management/rLocked.yaml create mode 100644 openapi/responses/processes-job-management/rUnsupportedSchema.yaml diff --git a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc index 764d1639..3a456e40 100644 --- a/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc +++ b/extensions/job_management/standard/requirements/job-management/create/REQ_response-body.adoc @@ -4,5 +4,5 @@ [%metadata] label:: /req/job-management/create-response-body part:: The response SHALL include a body that contains a status information of the created job that conforms to the https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/statusInfo.yaml[statusInfo.yaml] schema. -part:: The response SHALL contain a `created` status code and the `jobId` property that contains the job identifier. +part:: The response SHALL contain a `created` status code and the `id` property that contains the job identifier. ==== diff --git a/extensions/job_management/standard/sections/clause_0_front_material.adoc b/extensions/job_management/standard/sections/clause_0_front_material.adoc index ec23fb8d..6bfafa81 100644 --- a/extensions/job_management/standard/sections/clause_0_front_material.adoc +++ b/extensions/job_management/standard/sections/clause_0_front_material.adoc @@ -23,5 +23,6 @@ All questions regarding this submission should be directed to the editors or the | Name | Affiliation | Gérald Fenoy _(editor)_ | GeoLabs | Francis Charette Mignault _(editor)_ | Centre de recherche informatique de Montréal (CRIM) +| Panagiotis (Peter) A. Vretanos | CubeWerx Inc. |=== diff --git a/extensions/job_management/standard/sections/clause_6_job_management.adoc b/extensions/job_management/standard/sections/clause_6_job_management.adoc index bdd7d53c..6b39e92f 100644 --- a/extensions/job_management/standard/sections/clause_6_job_management.adoc +++ b/extensions/job_management/standard/sections/clause_6_job_management.adoc @@ -230,6 +230,8 @@ See <> for general guidance. If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. +If the job with the specified identifier is locked, see requirement /req/job-management/update/response-locked from <>. + [[job-management-definition]] === Job definition @@ -254,4 +256,3 @@ See <> for general If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from <>. -If the job with the specified identifier is locked, see requirement /req/job-management/update/response-locked from <>. diff --git a/openapi/paths/processes-job-management/pJob.yaml b/openapi/paths/processes-job-management/pJob.yaml new file mode 100644 index 00000000..d5b3f12a --- /dev/null +++ b/openapi/paths/processes-job-management/pJob.yaml @@ -0,0 +1,53 @@ +patch: + summary: update a job. + description: | + Update a job resulting in the creation of a job resource. + operationId: updateJob + tags: + - Jobs Management + parameters: + - $ref: "../../parameters/processes-core/jobId.yaml" + # If we want to use similar mechanism as the workflows, we can use the + # following parameter. + #- $ref: "../../parameters/processes-workflows/response.yaml" + # If we want to use similar mechanism as in the Part 1, we can use the + # following parameter. + #- $ref: "../../parameters/processes-core/prefer-header-execution.yaml" + requestBody: + description: An execution request specifying any inputs for the process to execute, and optionally to select specific outputs. + required: true + content: + application/json: + schema: + $ref: "../../schemas/processes-workflows/execute-workflows.yaml" + responses: + # In case we do not agree to force asynchornous mode for the /jobs + # endpoint, we can also use the following response. + #200: + # $ref: "../../responses/processes-core/rExecuteSync.yaml" + 201: + $ref: "../../responses/processes-core/rExecuteAsync.yaml" + # If the Server Implementation support the Collection output conformance class. + #303: + # $ref: "../../responses/processes-workflows/rExecuteCollectionRedirect.yaml" + 404: + $ref: "../../responses/common-core/rNotFound.yaml" + 422: + $ref: "../../responses/common-core/rUnprocessableEntity.yaml" + 423: + $ref: "../../responses/common-core/rLocked.yaml" + 500: + $ref: "../../responses/common-core/rServerError.yaml" + callbacks: + # Where are the other callbacks (ie. jobFailed, jobUpdated)? + jobCompleted: + "{$request.body#/subscriber/successUri}": + post: + requestBody: + content: + application/json: + schema: + $ref: "../../schemas/processes-core/results.yaml" + responses: + 200: + description: Results received successfully diff --git a/openapi/paths/processes-job-management/pJobDefinition.yaml b/openapi/paths/processes-job-management/pJobDefinition.yaml new file mode 100644 index 00000000..ef2c5b2e --- /dev/null +++ b/openapi/paths/processes-job-management/pJobDefinition.yaml @@ -0,0 +1,16 @@ +get: + summary: retrieve the definition of a job + description: | + Retrieve the definition of a job. + operationId: getJobDefinition + tags: + - Jobs Management + parameters: + - $ref: "../../parameters/processes-core/jobId.yaml" + responses: + 200: + $ref: "../../schemas/processes-workflows/execute-workflows.yaml" + 404: + $ref: "../../responses/common-core/rNotFound.yaml" + 500: + $ref: "../../responses/common-core/rServerError.yaml" diff --git a/openapi/paths/processes-job-management/pJobInputs.yaml b/openapi/paths/processes-job-management/pJobInputs.yaml new file mode 100644 index 00000000..96ef8b02 --- /dev/null +++ b/openapi/paths/processes-job-management/pJobInputs.yaml @@ -0,0 +1,16 @@ +get: + summary: retrieve the information about a job + description: | + Retrieve the information about a job. + operationId: getJobInputs + tags: + - Jobs Management + parameters: + - $ref: "../../parameters/processes-core/jobId.yaml" + responses: + 200: + $ref: "../../schemas/processes-management/rInputs.yaml" + 404: + $ref: "../../responses/common-core/rNotFound.yaml" + 500: + $ref: "../../responses/common-core/rServerError.yaml" diff --git a/openapi/paths/processes-job-management/pJobResults.yaml b/openapi/paths/processes-job-management/pJobResults.yaml new file mode 100644 index 00000000..a5baeab6 --- /dev/null +++ b/openapi/paths/processes-job-management/pJobResults.yaml @@ -0,0 +1,24 @@ +post: + summary: start the executino of a job + description: | + Starts the execution of a job. + operationId: postResult + requestBody: + description: An empty body. + required: true + content: + application/json: + schema: + type: object + nullable: true + tags: + - Jobs Management + parameters: + - $ref: "../../parameters/processes-core/jobId.yaml" + responses: + 200: + $ref: "../../responses/processes-core/rExecuteAsync.yaml" + 404: + $ref: "../../responses/common-core/rNotFound.yaml" + 500: + $ref: "../../responses/common-core/rServerError.yaml" diff --git a/openapi/paths/processes-job-management/pJobsList.yaml b/openapi/paths/processes-job-management/pJobsList.yaml new file mode 100644 index 00000000..8c10ae06 --- /dev/null +++ b/openapi/paths/processes-job-management/pJobsList.yaml @@ -0,0 +1,50 @@ +post: + summary: create a job. + description: | + Create a job resulting in the creation of a job resource. + operationId: createJob + tags: + - Jobs Management + parameters: + # If we want to use similar mechanism as the workflows, we can use the + # following parameter. + #- $ref: "../../parameters/processes-workflows/response.yaml" + # If we want to use similar mechanism as in the Part 1, we can use the + # following parameter. + #- $ref: "../../parameters/processes-core/prefer-header-execution.yaml" + requestBody: + description: An execution request specifying any inputs for the process to execute, and optionally to select specific outputs. + required: true + content: + application/json: + schema: + $ref: "../../schemas/processes-workflows/execute-workflows.yaml" + responses: + # In case we do not agree to force asynchornous mode for the /jobs + # endpoint, we can also use the following response. + #200: + # $ref: "../../responses/processes-core/rExecuteSync.yaml" + 201: + $ref: "../../responses/processes-core/rExecuteAsync.yaml" + # If the Server Implementation support the Collection output conformance class. + #303: + # $ref: "../../responses/processes-workflows/rExecuteCollectionRedirect.yaml" + 404: + $ref: "../../responses/common-core/rNotFound.yaml" + 422: + $ref: "../../responses/common-core/rUnprocessableEntity.yaml" + 500: + $ref: "../../responses/common-core/rServerError.yaml" + callbacks: + # Where are the other callbacks (ie. jobFailed, jobUpdated)? + jobCompleted: + "{$request.body#/subscriber/successUri}": + post: + requestBody: + content: + application/json: + schema: + $ref: "../../schemas/processes-core/results.yaml" + responses: + 200: + description: Results received successfully diff --git a/openapi/responses/processes-job-management/rInputs.yaml b/openapi/responses/processes-job-management/rInputs.yaml new file mode 100644 index 00000000..e80203a8 --- /dev/null +++ b/openapi/responses/processes-job-management/rInputs.yaml @@ -0,0 +1,8 @@ +description: Proivenance information about a job. +content: + application/json: + schema: + $ref: '../../schemas/processes-job-management/inputs.yaml' + text/html: + schema: + type: string diff --git a/openapi/responses/processes-job-management/rLocked.yaml b/openapi/responses/processes-job-management/rLocked.yaml new file mode 100644 index 00000000..c015d651 --- /dev/null +++ b/openapi/responses/processes-job-management/rLocked.yaml @@ -0,0 +1,8 @@ +description: Job is locked. For example, the `status` of the job is currently something else than `succeeded`, `failed` and `created`. +content: + application/json: + schema: + $ref: '../../schemas/common-core/exception.yaml' + text/html: + schema: + type: string diff --git a/openapi/responses/processes-job-management/rUnsupportedSchema.yaml b/openapi/responses/processes-job-management/rUnsupportedSchema.yaml new file mode 100644 index 00000000..2c080eef --- /dev/null +++ b/openapi/responses/processes-job-management/rUnsupportedSchema.yaml @@ -0,0 +1,8 @@ +description: Unprocessable Content. For example, the `Content-Schema` header submitted in the request did not support any of schemas supported by the server for the requested resource. +content: + application/json: + schema: + $ref: '../../schemas/common-core/exception.yaml' + text/html: + schema: + type: string