From 821c86ec75068bc1fec76c3021fdb8fdfe1d19e8 Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Wed, 24 Jun 2026 07:16:47 -0400 Subject: [PATCH 1/2] Add support for the /jobs/{jobId}/results/{outputID}/{N} path. --- .../core/ATS_job-result-op.adoc | 4 +- .../ATS_data-access-apis.adoc | 2 +- .../ATS_data-classes.adoc | 2 +- .../ATS_execution-unit-requirements.adoc | 2 +- ...-async-one-multi-valued-other-formats.adoc | 24 +++ ...R_process-execute-multiple-values-pkg.adoc | 8 + ...s-sync-one-multi-valued-other-formats.adoc | 24 +++ ...-one-multi-valued-json-prefer-minimal.adoc | 24 +++ ...ync-one-multi-valued-json-prefer-none.adoc | 24 +++ ...lti-valued-json-prefer-representation.adoc | 19 ++ ...-one-multi-valued-json-prefer-minimal.adoc | 24 +++ ...ync-one-multi-valued-json-prefer-none.adoc | 24 +++ ...lti-valued-json-prefer-representation.adoc | 19 ++ .../PER_extend-data-access-apis-values.adoc | 2 +- .../core/REQ_job-result-op-0th.adoc | 8 + .../core/REQ_job-result-op-Nth.adoc | 24 +++ ...EQ_job-results-param-outputs-response.adoc | 2 +- ...REQ_job-results-success-async-one-Nth.adoc | 35 ++++ ...esults-success-async-one-multi-valued.adoc | 40 ++++ .../REQ_job-results-success-async-one.adoc | 10 + ...ess-execute-success-async-outputs-Nth.adoc | 31 +++ ...s-execute-success-async-outputs-empty.adoc | 2 +- ...te-success-sync-one-multi-valued-json.adoc | 36 ++++ core/requirements/kvp-execute/REQ_output.adoc | 2 + .../REQ_execution-unit-requirements.adoc | 2 +- .../requirements_class_callback.adoc | 6 + .../requirements_class_collection-input.adoc | 6 + .../requirements_class_collection-output.adoc | 6 + .../requirements/requirements_class_core.adoc | 6 + .../requirements_class_dismiss.adoc | 6 + .../requirements/requirements_class_html.adoc | 6 + .../requirements_class_job-list.adoc | 6 + .../requirements/requirements_class_json.adoc | 6 + .../requirements_class_kvp-execute.adoc | 6 + .../requirements_class_local-filtering.adoc | 6 + core/requirements/requirements_class_oas.adoc | 6 + .../requirements_class_oas30.adoc | 6 + .../requirements_class_oas31.adoc | 6 + ...rements_class_ogc-process-description.adoc | 6 + ...equirements_class_query-param-profile.adoc | 6 + ...requirements_class_remote-collections.adoc | 6 + core/sections/annex-history.adoc | 8 +- core/sections/clause_12_oas.adoc | 2 +- core/sections/clause_16_kvp-execute.adoc | 11 +- core/sections/clause_2_conformance.adoc | 8 +- core/sections/clause_6_overview.adoc | 3 +- core/sections/clause_7_core.adoc | 183 ++++++++++++++++-- core/sections/clause_8_collections.adoc | 6 +- .../clause_9_process-description.adoc | 4 - 49 files changed, 668 insertions(+), 47 deletions(-) create mode 100644 core/recommendations/core/PER_job-results-success-async-one-multi-valued-other-formats.adoc create mode 100644 core/recommendations/core/PER_process-execute-multiple-values-pkg.adoc create mode 100644 core/recommendations/core/PER_process-execute-success-sync-one-multi-valued-other-formats.adoc create mode 100644 core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-minimal.adoc create mode 100644 core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-none.adoc create mode 100644 core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-representation.adoc create mode 100644 core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-minimal.adoc create mode 100644 core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-none.adoc create mode 100644 core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-representation.adoc create mode 100644 core/requirements/core/REQ_job-result-op-0th.adoc create mode 100644 core/requirements/core/REQ_job-result-op-Nth.adoc create mode 100644 core/requirements/core/REQ_job-results-success-async-one-Nth.adoc create mode 100644 core/requirements/core/REQ_job-results-success-async-one-multi-valued.adoc create mode 100644 core/requirements/core/REQ_process-execute-success-async-outputs-Nth.adoc create mode 100644 core/requirements/core/REQ_process-execute-success-sync-one-multi-valued-json.adoc diff --git a/core/abstract_tests/core/ATS_job-result-op.adoc b/core/abstract_tests/core/ATS_job-result-op.adoc index 030674c4..cc1c78df 100644 --- a/core/abstract_tests/core/ATS_job-result-op.adoc +++ b/core/abstract_tests/core/ATS_job-result-op.adoc @@ -5,12 +5,12 @@ [%metadata] identifier:: /conf/core/job-result-op target:: /req/core/job-result-op -test-purpose:: Validate that each process output with identifier `{outputID}` can be retrived from the `/jobs/{jobID}/results/{outputID}` endpoint. +test-purpose:: Validate that each process output with identifier `{outputID}` can be retrieved from the `/jobs/{jobID}/results/{outputID}` endpoint. test-method:: + -- 1. Negotiate asynchronous process execution as per test <> or <>. -2. Validate that each process output can be retrived as per requirement <>. +2. Validate that each process output can be retrieved as per requirement <>. -- ==== diff --git a/core/abstract_tests/ogc-process-description/ATS_data-access-apis.adoc b/core/abstract_tests/ogc-process-description/ATS_data-access-apis.adoc index 9a39e0a3..4abdd7ce 100644 --- a/core/abstract_tests/ogc-process-description/ATS_data-access-apis.adoc +++ b/core/abstract_tests/ogc-process-description/ATS_data-access-apis.adoc @@ -10,7 +10,7 @@ test-method:: -- 1. Retrieve the description of each process the server offers according to test <>. -2. Inspect each input of each process and determine if the `dataAccessApi` parmater is present. +2. Inspect each input of each process and determine if the `dataAccessApi` parameter is present. 3. If it is present then verify that the value of the parameter is either empty or contains a list of data access APIs (e.g. ogc-api-features, ogc-api-coverages, etc.). diff --git a/core/abstract_tests/ogc-process-description/ATS_data-classes.adoc b/core/abstract_tests/ogc-process-description/ATS_data-classes.adoc index a473c736..392bbcb9 100644 --- a/core/abstract_tests/ogc-process-description/ATS_data-classes.adoc +++ b/core/abstract_tests/ogc-process-description/ATS_data-classes.adoc @@ -11,7 +11,7 @@ test-method:: -- 1. Retrieve the description of each process the server offers according to test <>. -2. Inspect each input of each process and determine if the `dataClasses` parmater is present. +2. Inspect each input of each process and determine if the `dataClasses` parameter is present. 3. If it is present then verify that the value of the parameter is an array of strings. diff --git a/core/abstract_tests/ogc-process-description/ATS_execution-unit-requirements.adoc b/core/abstract_tests/ogc-process-description/ATS_execution-unit-requirements.adoc index 2ba66ae6..ac7953bd 100644 --- a/core/abstract_tests/ogc-process-description/ATS_execution-unit-requirements.adoc +++ b/core/abstract_tests/ogc-process-description/ATS_execution-unit-requirements.adoc @@ -11,7 +11,7 @@ test-method:: -- 1. Retrieve the description of each process the server offers according to test <>. -2. Inspect each input of each process and determine if the `executionUnitRequirements` parmater is present. +2. Inspect each input of each process and determine if the `executionUnitRequirements` parameter is present. 3. If the `remote-access` member is specified, verify that its value is either `true` or `false`. diff --git a/core/recommendations/core/PER_job-results-success-async-one-multi-valued-other-formats.adoc b/core/recommendations/core/PER_job-results-success-async-one-multi-valued-other-formats.adoc new file mode 100644 index 00000000..a6bad41a --- /dev/null +++ b/core/recommendations/core/PER_job-results-success-async-one-multi-valued-other-formats.adoc @@ -0,0 +1,24 @@ +[[per_core_job-results-async-one-multi-valued-other-formats]] +[permission] +==== +[%metadata] +identifier:: /per/core/job-results-async-one-multi-valued-other-formats + +[.component,class=conditions] +-- +. The <> is asynchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +. In the <> the output is defined as having `maxOccurs>1`. +-- + +[.component,class=part] +-- +Servers MAY support other response formats or encodings (e.g. ZIP or `multipart/*`) that do not conform to https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/values.yaml[values.yaml]. +-- + +[.component,class=part] +-- +This Standard does not provide any guidance on these other formats or encodings. +-- + +==== diff --git a/core/recommendations/core/PER_process-execute-multiple-values-pkg.adoc b/core/recommendations/core/PER_process-execute-multiple-values-pkg.adoc new file mode 100644 index 00000000..6aeceb6f --- /dev/null +++ b/core/recommendations/core/PER_process-execute-multiple-values-pkg.adoc @@ -0,0 +1,8 @@ +[[per_core_process-execute-multiple-values-pkg]] +[permission] +==== +[%metadata] +identifier:: /per/core/process-execute-multiple-values-pkg + +A server MAY, through content negotiation, respond with something other than that specified by requirement <>. A server MAY, for example, respond with a https://www.iso.org/standard/60101.html[ZIP] file or a https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html[multi-part MIME] document containing all the requested output values. +==== diff --git a/core/recommendations/core/PER_process-execute-success-sync-one-multi-valued-other-formats.adoc b/core/recommendations/core/PER_process-execute-success-sync-one-multi-valued-other-formats.adoc new file mode 100644 index 00000000..28133ebe --- /dev/null +++ b/core/recommendations/core/PER_process-execute-success-sync-one-multi-valued-other-formats.adoc @@ -0,0 +1,24 @@ +[[per_core_process-execute-sync-one-multi-valued-other-formats]] +[permission] +==== +[%metadata] +identifier:: /per/core/process-execute-sync-one-multi-valued-other-formats + +[.component,class=conditions] +-- +. The <> is synchronous. +. The number of requested (whether <>) outputs in the <> is 1. +. In the <> the requested output is defined as having `maxOccurs>1`. +-- + +[.component,class=part] +-- +Servers MAY support other response formats or encodings (e.g. ZIP or `multipart/*`) that do not conform to https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/values.yaml[values.yaml]. +-- + +[.component,class=part] +-- +This Standard does not provide any guidance on these other formats or encodings. +-- + +==== diff --git a/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-minimal.adoc b/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-minimal.adoc new file mode 100644 index 00000000..dad2eeb8 --- /dev/null +++ b/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-minimal.adoc @@ -0,0 +1,24 @@ +[[rec_core_job-results-async-one-multi-valued-json-prefer-minimal]] +[recommendation] +==== +[%metadata] +identifier:: /rec/core/job-results-async-one-multi-valued-json-prefer-minimal + +[.component,class=conditions] +-- +. The <> is asynchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +. In the <> the output is defined as having `maxOccurs>1`. +. The negotiated https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[return preference] is `minimal`. +-- + +[.component,class=part] +-- +If the server deems that the size of an output value is _small_, that value SHOULD be included in-line in the response. +-- + +[.component,class=part] +-- +If the server deems that the size of an output value is _large_, that value SHOULD be included by reference via hyperlink in the response. +-- +==== diff --git a/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-none.adoc b/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-none.adoc new file mode 100644 index 00000000..fa60892d --- /dev/null +++ b/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-none.adoc @@ -0,0 +1,24 @@ +[[rec_core_job-results-async-one-multi-valued-json-prefer-none]] +[recommendation] +==== +[%metadata] +identifier:: /rec/core/job-results-async-one-multi-valued-json-prefer-none + +[.component,class=conditions] +-- +. The <> is asynchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +. In the <> the output is defined as having `maxOccurs>1`. +. A return preference is _**not**_ specified via the HTTP https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[`prefer`] header. +-- + +[.component,class=part] +-- +If the server deems that the size of an output value is _small_, that value SHOULD be included in-line in the response. +-- + +[.component,class=part] +-- +If the server deems that the size of an output value is _large_, that value SHOULD be included by reference via hyperlink in the response. +-- +==== diff --git a/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-representation.adoc b/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-representation.adoc new file mode 100644 index 00000000..dadc461b --- /dev/null +++ b/core/recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-representation.adoc @@ -0,0 +1,19 @@ +[[rec_core_job-results-async-one-multi-valued-json-prefer-representation]] +[recommendation] +==== +[%metadata] +identifier:: /rec/core/job-results-async-one-multi-valued-json-prefer-representation + +[.component,class=conditions] +-- +. The <> is asynchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +. In the <> the output is defined as having `maxOccurs>1`. +. The negotiated https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[return preference] is `representation`. +-- + +[.component,class=part] +-- +Each requested output value SHOULD be included in-line in the response. +-- +==== diff --git a/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-minimal.adoc b/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-minimal.adoc new file mode 100644 index 00000000..7b9b397c --- /dev/null +++ b/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-minimal.adoc @@ -0,0 +1,24 @@ +[[rec_core_process-execute-sync-one-multi-valued-json-prefer-minimal]] +[recommendation] +==== +[%metadata] +identifier:: /rec/core/process-execute-sync-one-multi-valued-json-prefer-minimal + +[.component,class=conditions] +-- +. The <> is synchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +. In the <> the output is defined as having `maxOccurs>1`. +. The negotiated https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[return preference] is `minimal`. +-- + +[.component,class=part] +-- +If the server deems that the size of an output value is _small_, that value SHOULD be included in-line in the response. +-- + +[.component,class=part] +-- +If the server deems that the size of an output value is _large_, that value SHOULD be included by reference via hyperlink in the response. +-- +==== diff --git a/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-none.adoc b/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-none.adoc new file mode 100644 index 00000000..de6df29c --- /dev/null +++ b/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-none.adoc @@ -0,0 +1,24 @@ +[[rec_core_process-execute-sync-one-multi-valued-json-prefer-none]] +[recommendation] +==== +[%metadata] +identifier:: /rec/core/process-execute-sync-one-multi-valued-json-prefer-none + +[.component,class=conditions] +-- +. The <> is synchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +. In the <> the output is defined as having `maxOccurs>1`. +. No https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[return preference] accompanies the request. +-- + +[.component,class=part] +-- +If the server deems that the size of the output values is _small_, that value SHOULD be included in-line in the response. +-- + +[.component,class=part] +-- +If the server deems that the size of an output values is _large_, that value SHOULD be included by reference via hyperlink in the response. +-- +==== diff --git a/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-representation.adoc b/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-representation.adoc new file mode 100644 index 00000000..c71020ca --- /dev/null +++ b/core/recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-representation.adoc @@ -0,0 +1,19 @@ +[[rec_core_process-execute-sync-one-multi-valued-json-prefer-representation]] +[recommendation] +==== +[%metadata] +identifier:: /rec/core/process-execute-sync-one-multi-valued-json-prefer-representation + +[.component,class=conditions] +-- +. The <> is synchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +. In the <> the output is defined as having `maxOccurs>1`. +. The negotiated https://datatracker.ietf.org/doc/html/rfc7240#section-4.2[return preference] is `representation`. +-- + +[.component,class=part] +-- +Each requested output value SHOULD be included in-line in the response. +-- +==== diff --git a/core/recommendations/ogc-process-description/PER_extend-data-access-apis-values.adoc b/core/recommendations/ogc-process-description/PER_extend-data-access-apis-values.adoc index 05bbbc33..2842b2e7 100644 --- a/core/recommendations/ogc-process-description/PER_extend-data-access-apis-values.adoc +++ b/core/recommendations/ogc-process-description/PER_extend-data-access-apis-values.adoc @@ -4,5 +4,5 @@ [%metadata] identifier:: /per/ogc-process-description/extend-data-access-apis-values -The list of values for the `dataAccessApi` paramater MAY be extended as necessary to accomondate other, perhaps even non_OGC, data access APIs. +The list of values for the `dataAccessApi` paramater MAY be extended as necessary to accommodate other, perhaps even non_OGC, data access APIs. ==== diff --git a/core/requirements/core/REQ_job-result-op-0th.adoc b/core/requirements/core/REQ_job-result-op-0th.adoc new file mode 100644 index 00000000..e0be3954 --- /dev/null +++ b/core/requirements/core/REQ_job-result-op-0th.adoc @@ -0,0 +1,8 @@ +[[req_core_job-result-op-0th]] +[requirement] +==== +[%metadata] +identifier:: /req/core/job-result-op-0th + +For each output, with output identifier `outputID`, defined in the <> and requested (whether <> or <>) in an <>, the server SHALL support the HTTP GET operation at the path `/jobs/{jobID}/results/{outputID}/0`. +==== diff --git a/core/requirements/core/REQ_job-result-op-Nth.adoc b/core/requirements/core/REQ_job-result-op-Nth.adoc new file mode 100644 index 00000000..4d69659b --- /dev/null +++ b/core/requirements/core/REQ_job-result-op-Nth.adoc @@ -0,0 +1,24 @@ +[[req_core_job-result-op-Nth]] +[requirement] +==== +[%metadata] +identifier:: /req/core/job-result-op-Nth + + +[.component,class=conditions] +-- +. The output with output identifier `outputID` is defined in the <> as having `maxOccurs>1`. +. The output with output identifier `outputID` is <> or <> requested in an <>. +-- + +[.component,class=part] +-- +The server SHALL support the HTTP GET operation at the path `/jobs/{jobID}/results/{outputID}/{N}`. +-- + +[.component,class=part] +-- +The path element _N_ is a 0-based index into the array of values generated by the process for this output. +-- + +==== diff --git a/core/requirements/core/REQ_job-results-param-outputs-response.adoc b/core/requirements/core/REQ_job-results-param-outputs-response.adoc index c193427d..8a5b6c6e 100644 --- a/core/requirements/core/REQ_job-results-param-outputs-response.adoc +++ b/core/requirements/core/REQ_job-results-param-outputs-response.adoc @@ -4,5 +4,5 @@ [%metadata] identifier:: /req/core/job-results-param-outputs-response -Only the outputs with identifers specified using the optional <> SHALL be included in the response. +Only the outputs with identifiers specified using the optional <> SHALL be included in the response. ==== diff --git a/core/requirements/core/REQ_job-results-success-async-one-Nth.adoc b/core/requirements/core/REQ_job-results-success-async-one-Nth.adoc new file mode 100644 index 00000000..ba9230d3 --- /dev/null +++ b/core/requirements/core/REQ_job-results-success-async-one-Nth.adoc @@ -0,0 +1,35 @@ +[[req_core_job-results-async-one-Nth]] +[requirement] +==== +[%metadata] +identifier:: /req/core/job-results-async-one-Nth + +[.component,class=conditions] +-- +. The <> is asynchronous, +. The number of requested (whether <> or <>) outputs in the <> is 1. +. The requested output with identifier `outputID` is defined in the <> as having `maxOccurs>1`. +. The path `/jobs/{jobID}/results/{outputID}/{N}` is accessed to retrieve the 0-based _N^th^_ value from the array of values produced for this output. +-- + +[.component,class=part] +-- +The server SHALL respond with an HTTP status code of 200. +-- + +[.component,class=part] +-- +In the response headers, the server SHALL include an HTTP header named `OGC-Output-Values-Count` indicating how many processing values are retrievable for this output. +-- + +[.component,class=part] +-- +The media type of the response SHALL be as negotiated as per the https://datatracker.ietf.org/doc/html/rfc2616#section-12[HTTP content negotiation rules]. +-- + +[.component,class=part] +-- +The content of the response body SHALL be the 0-based _N^th^_ value in the negotiated output format. +-- + +==== diff --git a/core/requirements/core/REQ_job-results-success-async-one-multi-valued.adoc b/core/requirements/core/REQ_job-results-success-async-one-multi-valued.adoc new file mode 100644 index 00000000..b8bf9ba5 --- /dev/null +++ b/core/requirements/core/REQ_job-results-success-async-one-multi-valued.adoc @@ -0,0 +1,40 @@ +[[req_core_job-results-async-one-multi-valued]] +[requirement] +==== +[%metadata] +identifier:: /req/core/job-results-async-one-multi-valued + +[.component,class=conditions] +-- +. The <> is asynchronous. +. The number of requested (whether <> or <>) outputs in the <> is 1. +- In its <> the requested output is defined as having `maxOccurs>1`. +. The results are retrieved from the `/jobs/{jobID}/results/{outputID}` endpoint. +-- + +[.component,class=part] +-- +The server SHALL respond with an HTTP status code of 200. +-- + +[.component,class=part] +-- +In the response headers, the server SHALL include an HTTP header named `OGC-Output-Values-Count` indicating how many processing values are retrievable for this output. +-- + +[.component,class=part] +-- +The media type of the response SHALL be `application/json`. +-- + +[.component,class=part] +-- +The response HTTP headers SHALL include a `Link: href="https://www.opengis.net/def/profile/OGC/0/ogc-values", rel="profile"`. +-- + +[.component,class=part] +-- +The content of response SHALL conform to the <> schema. +-- + +==== diff --git a/core/requirements/core/REQ_job-results-success-async-one.adoc b/core/requirements/core/REQ_job-results-success-async-one.adoc index 998f75f1..ed9ca989 100644 --- a/core/requirements/core/REQ_job-results-success-async-one.adoc +++ b/core/requirements/core/REQ_job-results-success-async-one.adoc @@ -16,6 +16,11 @@ identifier:: /req/core/job-results-async-one The server SHALL respond with an HTTP status code of 200. -- +[.component,class=part] +-- +In the response headers, the server SHALL include an HTTP header named `OGC-Output-Values-Count` indicating how many processing values are retrievable for this output. +-- + [.component,class=part] -- The media type of the response SHALL be as negotiated as per the https://datatracker.ietf.org/doc/html/rfc2616#section-12[HTTP content negotiation rules]. @@ -27,3 +32,8 @@ The content of response body SHALL be the requested process output value in the -- ==== + +NOTE: Unless the definition of an output sets `maxOccurs>1`, the value of the `OGC-Output-Values-Count` HTTP header will usually be 1. + +NOTE: If the requested output is multi-valued (i.e. `maxOccurs>1` in the <>), then the negotiated response will need to be some type of container for the array of values generated by the process for this output. For example, this could be a JSON response where the array of values is encoded as a JSON array or a multi-part response where each part contains one value from the array or some archive (e.g. ZIP or tar) where each array value is stored in an individual file. + diff --git a/core/requirements/core/REQ_process-execute-success-async-outputs-Nth.adoc b/core/requirements/core/REQ_process-execute-success-async-outputs-Nth.adoc new file mode 100644 index 00000000..814b1284 --- /dev/null +++ b/core/requirements/core/REQ_process-execute-success-async-outputs-Nth.adoc @@ -0,0 +1,31 @@ +[[req_core_process-execute-success-async-outputs-Nth]] +[requirement] +==== +[%metadata] +identifier:: /req/core/process-execute-success-async-outputs-Nth + +[.component,class=conditions] +-- +. The <> is asynchronous. +. The output with identifier `{outputID}` is specified in the <>. +. The output with identifier `{outputID}` is defined as having `maxOccurs>1` in the <>. +-- + +[.component,class=part] +-- +The server SHALL produce and make available for retrieval all the values of the output with identifier `{outputID}`. +-- + +[.component,class=part] +-- +The server SHALL respond with an HTTP status code of `404` if an attempt is made to access an unrequested output via the `/jobs/{jobsID}/resultes/{outputID}` path. +-- + +[.component,class=part] +-- +The server SHALL respond with an HTTP status code of `404` if an attempt is made to access an array element with an out-of-bound index, _N_, via the `/jobs/{jobsID}/resultes/{outputID}/{N}` path. +-- + +==== + +NOTE: The number of retrievable values for an output can be determined by reading the `OGC-Output-Values-Count` header. Using the HTTP HEAD method can obtain this information without incurring the cost of transmitting the actual output value. diff --git a/core/requirements/core/REQ_process-execute-success-async-outputs-empty.adoc b/core/requirements/core/REQ_process-execute-success-async-outputs-empty.adoc index b6e8e308..5285550b 100644 --- a/core/requirements/core/REQ_process-execute-success-async-outputs-empty.adoc +++ b/core/requirements/core/REQ_process-execute-success-async-outputs-empty.adoc @@ -17,7 +17,7 @@ The server SHALL asynchronously execute the process but SHALL not produce any re [.component,class=part] -- -Attempting to retieve any of the process's defined outputs via the `/jobs/{jobID}/results[/{outputID}]` path SHALL result in a HTTP status code 404 response. +Attempting to retrieve any of the process's defined outputs via the `/jobs/{jobID}/results[/{outputID}]` path SHALL result in a HTTP status code 404 response. -- ==== diff --git a/core/requirements/core/REQ_process-execute-success-sync-one-multi-valued-json.adoc b/core/requirements/core/REQ_process-execute-success-sync-one-multi-valued-json.adoc new file mode 100644 index 00000000..0cdc6bde --- /dev/null +++ b/core/requirements/core/REQ_process-execute-success-sync-one-multi-valued-json.adoc @@ -0,0 +1,36 @@ +[[req_core_process-execute-sync-one-multi-valued-json]] +[requirement] +==== +[%metadata] +identifier:: /req/core/process-execute-sync-one-multi-valued-json + +[.component,class=conditions] +-- +. The <> is synchronous. +. The number of requested (whether <>) outputs in the <> is 1. +- In its <> the requested output is defined as having `maxOccurs>1`. +. The negotiated output content type is `application/json`. +. Optionally, the negotiated profile is `https://www.opengis.net/def/profile/OGC/0/ogc-values`. +-- + +[.component,class=part] +-- +The server SHALL respond with an HTTP status code of 200. +-- + +[.component,class=part] +-- +The media type of the response SHALL be `application/json`. +-- + +[.component,class=part] +-- +The response HTTP headers SHALL include a `Link: href="https://www.opengis.net/def/profile/OGC/0/ogc-values", rel="profile"`. +-- + +[.component,class=part] +-- +The content of response SHALL conform to the <> schema. +-- + +==== diff --git a/core/requirements/kvp-execute/REQ_output.adoc b/core/requirements/kvp-execute/REQ_output.adoc index 3612ac8f..fe742e8a 100644 --- a/core/requirements/kvp-execute/REQ_output.adoc +++ b/core/requirements/kvp-execute/REQ_output.adoc @@ -29,6 +29,8 @@ schema: type: string encoding: type: string + index: + type: integer schema: oneOf: - type: string diff --git a/core/requirements/ogc-process-description/REQ_execution-unit-requirements.adoc b/core/requirements/ogc-process-description/REQ_execution-unit-requirements.adoc index 8658b221..2cbe75b8 100644 --- a/core/requirements/ogc-process-description/REQ_execution-unit-requirements.adoc +++ b/core/requirements/ogc-process-description/REQ_execution-unit-requirements.adoc @@ -6,7 +6,7 @@ identifier:: /req/ogc-process-description/execution-unit-requirements [.component,class=part] -- -The `executionUnitRequrements` parameter SHALL be used to specify runtime requirements for the corresponding input. +The `executionUnitRequirements` parameter SHALL be used to specify runtime requirements for the corresponding input. -- [.component,class=part] diff --git a/core/requirements/requirements_class_callback.adoc b/core/requirements/requirements_class_callback.adoc index d7d65c4b..b7ba9ec5 100644 --- a/core/requirements/requirements_class_callback.adoc +++ b/core/requirements/requirements_class_callback.adoc @@ -8,3 +8,9 @@ subject:: Web API inherit:: /req/core requirement:: /req/callback/job-callback ==== + +[[cc_callback]] +[.conformance_class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_collection-input.adoc b/core/requirements/requirements_class_collection-input.adoc index 2e2238e3..97b34a57 100644 --- a/core/requirements/requirements_class_collection-input.adoc +++ b/core/requirements/requirements_class_collection-input.adoc @@ -12,3 +12,9 @@ requirement:: /req/collection-input/pass-through requirement:: /req/collection-input/property-selection requirement:: /req/collection-input/referencing ==== + +[[cc_collection-input]] +[.conformance_class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_collection-output.adoc b/core/requirements/requirements_class_collection-output.adoc index a5f04035..b8c9dd81 100644 --- a/core/requirements/requirements_class_collection-output.adoc +++ b/core/requirements/requirements_class_collection-output.adoc @@ -12,3 +12,9 @@ requirement:: /req/collection-output/response-definition requirement:: /req/collection-output/response-response-many requirement:: /req/collection-output/response-response-one ==== + +[[cc_collection-output]] +[.conformance_class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_core.adoc b/core/requirements/requirements_class_core.adoc index db7d4caf..d5dd646d 100644 --- a/core/requirements/requirements_class_core.adoc +++ b/core/requirements/requirements_class_core.adoc @@ -63,3 +63,9 @@ requirement:: /req/core/process-list-success requirement:: /req/core/process-summary-links requirement:: /req/core/test-process ==== + +[[cc_core]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_dismiss.adoc b/core/requirements/requirements_class_dismiss.adoc index c669ecdc..10561882 100644 --- a/core/requirements/requirements_class_dismiss.adoc +++ b/core/requirements/requirements_class_dismiss.adoc @@ -10,3 +10,9 @@ requirement:: /req/dismiss/job-dismiss-op requirement:: /req/dismiss/job-dismiss-status requirement:: /req/dismiss/job-dismiss-success ==== + +[[cc_dismiss]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_html.adoc b/core/requirements/requirements_class_html.adoc index 1afd0551..97675d07 100644 --- a/core/requirements/requirements_class_html.adoc +++ b/core/requirements/requirements_class_html.adoc @@ -11,3 +11,9 @@ inherit:: /req/html requirement:: /req/html/content requirement:: /req/html/definition ==== + +[[cc_html]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_job-list.adoc b/core/requirements/requirements_class_job-list.adoc index 453d2129..c4de0e63 100644 --- a/core/requirements/requirements_class_job-list.adoc +++ b/core/requirements/requirements_class_job-list.adoc @@ -23,3 +23,9 @@ requirement:: /req/job-list/job-list-success requirement:: /req/job-list/type-definition requirement:: /req/job-list/type-response ==== + +[[cc_job-list]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_json.adoc b/core/requirements/requirements_class_json.adoc index aad5bfdc..e2ed6034 100644 --- a/core/requirements/requirements_class_json.adoc +++ b/core/requirements/requirements_class_json.adoc @@ -9,3 +9,9 @@ inherit:: <> inherit:: /req/core requirement:: /req/json/definition ==== + +[[cc_json]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_kvp-execute.adoc b/core/requirements/requirements_class_kvp-execute.adoc index adae9a52..dff89827 100644 --- a/core/requirements/requirements_class_kvp-execute.adoc +++ b/core/requirements/requirements_class_kvp-execute.adoc @@ -26,3 +26,9 @@ requirement:: /req/kvp-execute/prefer-response requirement:: /req/kvp-execute/process-execute-op requirement:: /req/kvp-execute/string-input-value ==== + +[[cc_kvp-execute]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_local-filtering.adoc b/core/requirements/requirements_class_local-filtering.adoc index ef940b82..3d47a68e 100644 --- a/core/requirements/requirements_class_local-filtering.adoc +++ b/core/requirements/requirements_class_local-filtering.adoc @@ -10,3 +10,9 @@ inherit:: /req/collection-input inherit:: /req/remote-collections requirement:: /req/local-filtering ==== + +[[cc_local-filtering]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_oas.adoc b/core/requirements/requirements_class_oas.adoc index 1009e939..347263bd 100644 --- a/core/requirements/requirements_class_oas.adoc +++ b/core/requirements/requirements_class_oas.adoc @@ -11,3 +11,9 @@ requirement:: /req/oas/exceptions-codes requirement:: /req/oas/oas-impl requirement:: /req/oas/security ==== + +[[cc_oas]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_oas30.adoc b/core/requirements/requirements_class_oas30.adoc index 2c7080f7..4aadbe3e 100644 --- a/core/requirements/requirements_class_oas30.adoc +++ b/core/requirements/requirements_class_oas30.adoc @@ -8,3 +8,9 @@ inherit:: <> inherit:: /req/oas requirement:: /req/oas30/oas-definition ==== + +[[cc_oas30]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_oas31.adoc b/core/requirements/requirements_class_oas31.adoc index c08a10a3..786b71ef 100644 --- a/core/requirements/requirements_class_oas31.adoc +++ b/core/requirements/requirements_class_oas31.adoc @@ -8,3 +8,9 @@ inherit:: <> inherit:: /req/oas requirement:: /req/oas31/oas-definition ==== + +[[cc_oas31]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_ogc-process-description.adoc b/core/requirements/requirements_class_ogc-process-description.adoc index 8232ee14..d9b78d49 100644 --- a/core/requirements/requirements_class_ogc-process-description.adoc +++ b/core/requirements/requirements_class_ogc-process-description.adoc @@ -20,3 +20,9 @@ requirement:: /req/ogc-process-description/output-multiple-types requirement:: /req/ogc-process-description/outputs-def requirement:: /req/ogc-process-description/value-passing ==== + +[[cc_ogc-process-description]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_query-param-profile.adoc b/core/requirements/requirements_class_query-param-profile.adoc index 0595935c..97e0d691 100644 --- a/core/requirements/requirements_class_query-param-profile.adoc +++ b/core/requirements/requirements_class_query-param-profile.adoc @@ -9,3 +9,9 @@ inherit:: /req/core requirement:: /req/query-param-profile/definition requirement:: /req/query-param-profile/response ==== + +[[cc_query-param-profile]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/requirements/requirements_class_remote-collections.adoc b/core/requirements/requirements_class_remote-collections.adoc index 31cf2843..29ef997e 100644 --- a/core/requirements/requirements_class_remote-collections.adoc +++ b/core/requirements/requirements_class_remote-collections.adoc @@ -9,3 +9,9 @@ inherit:: /req/collection-input requirement:: /req/remote-collections/access requirement:: /req/remote-collections/referencing ==== + +[[cc_remote-collections]] +[.conformance class] +==== +target:: <> +==== diff --git a/core/sections/annex-history.adoc b/core/sections/annex-history.adoc index 8b6e5225..8265b14f 100644 --- a/core/sections/annex-history.adoc +++ b/core/sections/annex-history.adoc @@ -94,9 +94,9 @@ |2021-03-29|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | * Remove unnecessary schemas that can now be defined using JSON Schema and propagate those changes to the other schemas. * Update some of the indentation in the yaml files so the yamllint does not complain. * Further refine the examples. * Update the text of the specification accordingly. |2021-03-29|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Move additionalProperties from output.yaml to execute.yaml to be consistent with what was done with input.yaml. |2021-03-29|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Allow simple values to be encoded directly. So, `"key": {"value":10}` becomes `"key": 10`. -|2021-03-29|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Add array, in additiona to string, number & boolean, to possible direct input types. +|2021-03-29|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Add array, in addition to string, number & boolean, to possible direct input types. |2021-04-09|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Update example to use new, more compact form for specifying simple scalar values. -|2021-04-09|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | 1. Make mediateType optional 2. Modify the schema tag to be a reference to a schema or be an inline JSON schema. 3. Change name of "encoding" tag to "characterEncoding" to make more clear what it means. +|2021-04-09|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | 1. Make mediaType optional 2. Modify the schema tag to be a reference to a schema or be an inline JSON schema. 3. Change name of "encoding" tag to "characterEncoding" to make more clear what it means. |2021-04-09|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Add missing input type array. |2021-04-09|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Patch merge inconsistency between issues #122, #152 and #155. |2021-04-09|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Fix some spacing issues with the yaml files. @@ -144,7 +144,7 @@ |2021-04-20|1.0-draft.6| Benjamin Pross|X | Remove unused schema, fixes #173 |2021-04-20|1.0-draft.6| Benjamin Pross|X | Remove link to execute endpoint from landing page |2021-04-20|1.0-draft.6| Benjamin Pross|X | Add recommendation to add link to job monitoring endpoint to the landing page -|2021-04-25|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Remove the patternProperties key that allow JSON Schema extensions keys that begin with "x-". Two point about this extension mechanism... (1) it breaks compatablity with swagger which is bad; (2) I can't really think of a good reason right now that we would want to extend the syntax of JSON Schema using this mechanism and so I think removing it is OK. +|2021-04-25|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Remove the patternProperties key that allow JSON Schema extensions keys that begin with "x-". Two point about this extension mechanism... (1) it breaks compatability with swagger which is bad; (2) I can't really think of a good reason right now that we would want to extend the syntax of JSON Schema using this mechanism and so I think removing it is OK. |2021-04-26|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | - Update ATS to handle JSON Schema compliance levels. - Update examples to add a multi-type feature collection input. - Add a general inline value structure (qualifiedValue.yaml) that allows selection of a specified input type of a multi-type input. |2021-04-26|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Remove duplicate facet definitions. |2021-04-29|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Remove the various schema levels and only support the full OpenApi 3.0 compatible version of JSON Schema (formerly called schemaLevel3.yaml). @@ -164,7 +164,7 @@ |2021-05-06|1.0-draft.6| Ubuntu|X | Make Swagger-UI working again and the api able to validate. |2021-05-10|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Remove the concept of Level 0,1,2,3 JSON schema and simply use what was called Level 3 which is the full JSON Schema. |2021-05-10|1.0-draft.6| Panagiotis (Peter) A. Vretanos|X | Make the mode on execute options with the default being specified in the process description. -|2021-05-10|1.0-draft.6| Ubuntu|X | Remove uneeded yaml file. +|2021-05-10|1.0-draft.6| Ubuntu|X | Remove unneeded yaml file. |2021-05-11|1.0-draft.6| Ubuntu|X | Get the not, allOf, oneOf, anyOf, items and contentSchema available in the meta-schema. |2021-05-11|1.0-draft.6| Gérald Fenoy|X | Reset example despite warnings messages. |2021-05-11|1.0-draft.6| Gérald Fenoy|X | Reset additionalProperties in schema.yaml diff --git a/core/sections/clause_12_oas.adoc b/core/sections/clause_12_oas.adoc index 57460254..bbfa0c2a 100644 --- a/core/sections/clause_12_oas.adoc +++ b/core/sections/clause_12_oas.adoc @@ -14,7 +14,7 @@ include::../requirements/oas/REQ_definition.adoc[] The requirements <> and <> in _Core_ require that the API definition documents are referenced from the landing page. -[[two_appraoches_oas]] +[[two_approaches_oas]] OpenAPI definitions can be created using different approaches. A typical example is the representation of the feature collections. One approach is to use a path parameter `collectionId,` i.e., the API definition has only a single path entry for all feature collections. Another approach is to explicitly define each feature collection in a separate path and without a path parameter, which supports specifying filter parameters or explicit feature schemas per feature collection. Both approaches are valid. include::../requirements/oas/REQ_implementation.adoc[] diff --git a/core/sections/clause_16_kvp-execute.adoc b/core/sections/clause_16_kvp-execute.adoc index fd636c81..48bcf116 100644 --- a/core/sections/clause_16_kvp-execute.adoc +++ b/core/sections/clause_16_kvp-execute.adoc @@ -66,7 +66,7 @@ include::../requirements/kvp-execute/REQ_f-definition.adoc[] include::../requirements/kvp-execute/REQ_f-response.adoc[] -.Negotiating a respone format. +.Negotiating a response format. ==== This is an execution example where an input image is provided, along with other parameters, to the `myProcess` process and the response format is requested to be either a PNG or JPEG image (in that order of preference). @@ -319,13 +319,13 @@ arrayOfArrays=[[1,2,3,4],["a","b","c","d"]] An array of value references: [source] ---- -images=%5B%7B%22href%22%3A%22http%3A%2F%2Fwww.imagearchive.com%2Fimages%2Fimage01.tif%22%2C%22type%22%3A%22image%2Ftiff%3Bapplcation%3Dgeotiff%22%7D%2C%7B%22href%22%3A%22http%3A%2F%2Fwww.imagearchive.com%2Fimages%2Fimage19.jp2%2C%22type%22%3A%22image%2Fjp2%22%7D%5D +images=%5B%7B%22href%22%3A%22http%3A%2F%2Fwww.imagearchive.com%2Fimages%2Fimage01.tif%22%2C%22type%22%3A%22image%2Ftiff%3Bapplication%3Dgeotiff%22%7D%2C%7B%22href%22%3A%22http%3A%2F%2Fwww.imagearchive.com%2Fimages%2Fimage19.jp2%2C%22type%22%3A%22image%2Fjp2%22%7D%5D Decoded value is: images=[ { "href":"https://www.imagearchive.com/images/image01.tif", - "type":"image/tiff;applcation=geotiff" + "type":"image/tiff;application=geotiff" }, { "href":"https://www.imagearchive.com/images/image19.jp2, @@ -501,6 +501,11 @@ include::../requirements/kvp-execute/REQ_output.adoc[] ---- ...&out1[include]=true&out1[mediaType]=application/geo+tiff&... ---- + +[source] +---- +...&out1[include]=true&out1[mediaType]=application/geo+tiff&out1[index]=4&... +---- ==== === Response diff --git a/core/sections/clause_2_conformance.adoc b/core/sections/clause_2_conformance.adoc index fa2d3a4a..695cd9e5 100644 --- a/core/sections/clause_2_conformance.adoc +++ b/core/sections/clause_2_conformance.adoc @@ -9,7 +9,7 @@ The main requirements class is: * <>. -The _Core_ specifies requirements that any implementation of the Processes API in a Web API deploymnet must implement. +The _Core_ specifies requirements that any implementation of the Processes API in a Web API deployment must implement. The _Core_ does not mandate a specific encoding or format for the representation of resources defined in this Standard. Rather, two requirements classes depend on the _Core_ and specify representations for the resources specified in the _Core_ in commonly used encodings for data on the Web: @@ -65,11 +65,11 @@ defines requirements that allow process execution to be triggered by requesting In the <> executing a process requires sending a JSON-encoded execution request to the server using the HTTP POST method. To support embedding process execution requests into other documents this Standard defines the: -* <> +* <> conformance class which allows process inputs to be encoded as query parameters on a URL and process execution to be invoked using the HTTP GET method. -The standard request and response encoding used in this Standard is JSON. The standard media type for JSON is `application/json` which does not allow for the descrimition of one JSON schema from another. In order to resolve this issue the Standard supports content negotiation by profile and defines the `profile` query parameter in the: +The standard request and response encoding used in this Standard is JSON. The standard media type for JSON is `application/json` which does not allow for the discrimination of one JSON schema from another. In order to resolve this issue the Standard supports content negotiation by profile and defines the `profile` query parameter in the: * <. @@ -81,7 +81,7 @@ Three additional conformance classes are specified that extend the basic functio * <> for cancelling active jobs or deleting completed jobs, and -* <> for supporting a callback mechnanism to get notification of completed jobs. +* <> for supporting a callback mechanism to get notification of completed jobs. Additional capabilities such as support for transactions, extended job monitoring, etc., may be specified in future parts of the OGC API - Processes series or as vendor-specific extensions. diff --git a/core/sections/clause_6_overview.adoc b/core/sections/clause_6_overview.adoc index ff4f5dbc..f675684a 100644 --- a/core/sections/clause_6_overview.adoc +++ b/core/sections/clause_6_overview.adoc @@ -7,7 +7,7 @@ The https://docs.ogc.org/is/14-065/14-065r2.html[OGC Web Processing Service (WPS)] is a legacy interface standard that defines how to offer and execute geospatial processing algorithms over the Web. The WPS standard is designed to wrap any type of GIS functionality—from a simple "buffer" tool to a complex climate model—into a Web service that can be discovered and invoked by any compliant client. The WPS standard is built around three mandatory "requests" (methods) that a client can send to a server. The methods are: * **GetCapabilites:** Returns metadata about the service including a list of all - avilable processes hosted by the server. + available processes hosted by the server. * **DescribeProcess:** Provides a detailed description of a specific process inc luding its required inputs and the output that it produces. * **Execute:** Tells the server to run a specified process with the set of provi @@ -35,6 +35,7 @@ The following table provides a summary of the resources and HTTP methods specifi |Status of a specific job|`/jobs/{jobID}` |GET |jobID (in path) |<> |The endpoint to retrieve all requested processing results|`/jobs/{jobID}/results` |GET |jobID (in path) |<> |The endpoint to retrieve a specific processing result|`/jobs/{jobID}/results/{outputID}` |GET |jobID (in path), outputID (in path) |<> +|The endpoint to retrieve the Nth value of a specific processing result|`/jobs/{jobID}/results/{outputID}/{N}` |GET |jobID (in path), outputID (in path), N (in path) |T.B.D |Dismiss a job|`/jobs/{jobID}` |DELETE| jobID (in path) | <> |=== diff --git a/core/sections/clause_7_core.adoc b/core/sections/clause_7_core.adoc index 46306027..d79bc54e 100644 --- a/core/sections/clause_7_core.adoc +++ b/core/sections/clause_7_core.adoc @@ -198,7 +198,7 @@ This includes the correct use of status codes, headers. etc. include::../recommendations/core/REC_http-head.adoc[] -Supporting the HEAD method, in addition to GET, is simple and can provide useful information such as the size of a protential response without needing to transmite the entire content of the response beforehand. +Supporting the HEAD method, in addition to GET, is simple and can provide useful information such as the size of a potential response without needing to transmit the entire content of the response beforehand. include::../recommendations/core/REC_content-length.adoc[] @@ -1034,7 +1034,7 @@ The following table maps the possible responses based on the combinations of the |=== |Negotiated execute mode |Requested # outputs<> -|Defined # of outputs +|Output cardinality |Return preference (`Prefer` header) |Response HTTP code |Response headers @@ -1042,9 +1042,9 @@ The following table maps the possible responses based on the combinations of the |Response body |Req./Rec./Perm. -.4+|sync +.7+|sync |1 -|_n/a_ +|maxOccurs=1 |_n/a_ |200 | @@ -1052,6 +1052,19 @@ The following table maps the possible responses based on the combinations of the |requested process output |See requirement: <> +1.3+|1 +.3+|maxOccurs>1 +|_none_ +.3+|200 +.3+| +.3+|application/json<> +.3+|<> +|See <>,<> +|minimal +|See <>,<> +|representation +|See <>,<> + 1.3+|N .3+|_n/a_ |_none_ @@ -1073,7 +1086,7 @@ The following table maps the possible responses based on the combinations of the |_Location_ to newly created job |application/json |<> -|See <> +|See <> |=== [NOTE] @@ -1124,6 +1137,37 @@ A process output may be requested <> or <>. ==== +[[sync_note_9]] +[NOTE] +==== +* See requirement: <>. +* See permission: <> +==== + +[[sync_note_10]] +[NOTE] +==== +* See recommendation: <>. +==== + +[[sync_note_11]] +[NOTE] +==== +* See recommendation: <>. +==== + +[[sync_note_12]] +[NOTE] +==== +* See recommendation: <>. +==== + +[[sync_note_13]] +[NOTE] +==== +* See recommendation: <>. +==== + [[schema_results]] .Schema for processing results presented as a JSON document [source,yaml] @@ -1135,7 +1179,16 @@ NOTE: This schema can also be obtained from https://raw.githubusercontent.com/op The https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/refs/heads/master/openapi/schemas/processes-core/results.yaml[`results.yaml`] schema defines a map using the respective output identifier as the key. The value of an output can be returned as an in-line value or by reference. -===== Response requesting a single processing output +[[schema_values]] +.Schema for processing values presented as a JSON document +[source,yaml] +---- +include::../../openapi/schemas/processes-core/values.yaml[] +---- + +NOTE: This schema can also be obtained from https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/refs/heads/master/openapi/schemas/processes-core/values.yaml[`values.yaml`]. + +===== Response requesting a single processing output (maxOccurs=1) When a process is executed synchronously and a single processing output is generated (whether requested <> in the <>) the following requirements and recommendations apply: @@ -1149,7 +1202,7 @@ include::../recommendations/core/PER_process-execute-sync-one-result.adoc[] *Example* -In the example below the process "compute-spectral-index" has a single output also named "spectral-index-output". This processes is implemented to store the result file in some Web-accessible location. In this example the process is executed synchronously and the single output is requested. According to <>, in this case, the server should respond with the output image generated by the process. The server can either stream the response from its Web-accessiblke location to the client OR the server can use a HTTP 303 redirect to point to the result as shown in the example. +In the example below the process "compute-spectral-index" has a single output also named "spectral-index-output". This processes is implemented to store the result file in some Web-accessible location. In this example the process is executed synchronously and the single output is requested. According to <>, in this case, the server should respond with the output image generated by the process. The server can either stream the response from its Web-accessible location to the client OR the server can use a HTTP 303 redirect to point to the result as shown in the example. .HTTP 303 redirect example. ==== @@ -1187,9 +1240,25 @@ Client Server ---- ==== +===== Response requesting a single processing output (`maxOccurs>1`) + +In the case where the cardinality of a processing output is defined as being greater than one (i.e. `maxOccurs>1`), possibly resulting in multiple values being generate by the processing server for that output, the following requirements, recommendations and permissions applies: + +include::../requirements/core/REQ_process-execute-success-sync-one-multi-valued-json.adoc[] + +include::../recommendations/core/PER_process-execute-multiple-values-pkg.adoc[] + +include::../recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-none.adoc[] + +include::../recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-minimal.adoc[] + +include::../recommendations/core/REC_process-execute-success-sync-one-multi-valued-json-prefer-representation.adoc[] + +include::../recommendations/core/PER_process-execute-success-sync-one-multi-valued-other-formats.adoc[] + ===== Response requesting multiple processing outputs -When a process is executes synchronously and a multiple processing outputs are generated (whether requested implicitly or explicitly in the <> request) the following requirements and recommendations apply: +When a process is executed synchronously and multiple processing outputs are generated (whether requested implicitly or explicitly in the <> request) the following requirements, recommendations and permissions apply: include::../requirements/core/REQ_process-execute-success-sync-many-json.adoc[] @@ -1232,7 +1301,7 @@ include::../requirements/core/REQ_job-results-success-sync.adoc[] The job reference in the header can then be used to <> of the original synchronous execution. [[async-response]] -===== Response for asynchronous processes execution +===== Response for asynchronous process execution In the case of asynchronous execution, the following requirement applies: @@ -1240,6 +1309,8 @@ include::../requirements/core/REQ_process-execute-success-async.adoc[] include::../requirements/core/REQ_process-execute-success-async-outputs.adoc[] +include::../requirements/core/REQ_process-execute-success-async-outputs-Nth.adoc[] + include::../requirements/core/REQ_process-execute-success-async-outputs-empty.adoc[] include::../requirements/core/REQ_process-execute-success-async-outputs-omitted.adoc[] @@ -1337,12 +1408,22 @@ include::../requirements/core/REQ_job-results-param-outputs-response.adoc[] include::../requirements/core/REQ_job-results-profile.adoc[] -===== Individual processing results +===== Individual processing results (maxOccurs=1) include::../requirements/core/REQ_job-result-op.adoc[] NOTE: The size of individual processing results may be determined without actually transmitting the entire result by using the <> method to retrieve the <> header. +===== Individual processing results (maxOccurs>1) + +include::../requirements/core/REQ_job-result-op-Nth.adoc[] + +NOTE: The size of the value may be determined without actually transmitting the entire result by using the <> method to retrieve the <> header. + +===== The zero-th result + +include::../requirements/core/REQ_job-result-op-0th.adoc[] + ==== Response ===== Overview @@ -1352,12 +1433,14 @@ The way a server responds when retrieving job results depends on: * The number of outputs requested (whether <> or <>) in an <>. * The negotiated content type for the response (via the https://www.rfc-editor.org/rfc/rfc2616#section-14.1[HTTP Accept] header) or lack thereof, * Any negotiated client preferences (via the HTTP Prefer header). +* Whether an output is single-valued (i.e. `maxOccurs=1`) or multi-valued (i.e. `maxOccurs>1`). The following table maps the possible responses based on the combinations of parameters in the <>. The column headers in the following table denote: . *Requested # outputs*: The number of outputs requested (whether <> or <>) in the <>. +. *Output cardinality*: The maximum number of values that can be generated for this output. . *Access path*: The API endpoint from which the result(s) can be retrieved. . *Return preference*: The negotiated <>. . *Response HTTP code*: The https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1[HTTP status code] that the server should generate in this context. @@ -1367,9 +1450,10 @@ The column headers in the following table denote: [[table_core_getresults_responses]] .Table mapping `get` results responses based on the input parameter values used on the original <>. -[cols=7,options="header"] +[cols=8,options="header"] |=== |Requested # outputs<> +|Output cardinality |Access path |Return preference (`Prefer` header) |Response HTTP code @@ -1378,6 +1462,16 @@ The column headers in the following table denote: |Req./Rec./Perm. |1 +|maxOccurs>1 +|/jobs/{jobID}/results/{outputID}/{N} +|_n/a_ +|200 +|_as negotiated_ +|Nth value of the requested process output +|See requirement: <> + +|1 +|maxOccurs=1 |/jobs/{jobID}/results/{outputID} |_n/a_ |200 @@ -1385,17 +1479,31 @@ The column headers in the following table denote: |requested process output value |See requirement: <> +1.3+|1 +.3+|maxOccurs>1 +.3+|/jobs/{jobID}/results/{outputID} +|_none_ +.3+|200 +.3+|application/json +.3+|<> +|See <>,<> +|minimal +|See <>,<> +|representation +|See <>,<> + 1.3+|N +.3+| _n/a_ .3+|/jobs/{jobID}/results |_none_ .3+|200 .3+|application/json .3+|<> -|See <>,<> +|See <>,<> |minimal -|See <>,<> +|See <>,<> |representation -|See <>,<> +|See <>,<> |=== @@ -1408,23 +1516,48 @@ The column headers in the following table denote: [[async_note_2]] [NOTE] ==== +* See requirement: <> +* See permission: <> +==== + +[[async_note_3]] +[NOTE] +==== +* See recommendation: <> +==== + +[[async_note_4]] +[NOTE] +==== +* See recommendation: <> +==== + +[[async_note_5]] +[NOTE] +==== +* See recommendation: <> +==== + +[[async_note_6]] +[NOTE] +==== * See requirement: <> * See permission: <> ==== -[[async_note_3]] +[[async_note_7]] [NOTE] ==== * See recommendation: <> ==== -[[async_note_4]] +[[async_note_8]] [NOTE] ==== * See recommendation: <> ==== -[[async_note_5]] +[[async_note_9]] [NOTE] ==== * See recommendation: <> @@ -1433,10 +1566,24 @@ The column headers in the following table denote: The following requirements apply when retrieving the results of a job that was created by executing a process asynchronously OR was created by executing a process synchronously on a server that creates a job even for synchronous execution: [[sc_retrieve_job_results_one]] -===== Retrieving results individually +===== Retrieving results individually (maxOccurs=1) include::../requirements/core/REQ_job-results-success-async-one.adoc[] +===== Retrieving results individually (maxOccurs>1) + +include::../requirements/core/REQ_job-results-success-async-one-Nth.adoc[] + +include::../requirements/core/REQ_job-results-success-async-one-multi-valued.adoc[] + +include::../recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-none.adoc[] + +include::../recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-minimal.adoc[] + +include::../recommendations/core/REC_job-results-success-async-one-multi-valued-json-prefer-representation.adoc[] + +include::../recommendations/core/PER_job-results-success-async-one-multi-valued-other-formats.adoc[] + [[sc_retrieve_job_results_many]] ===== Retrieving multiple results simultaneously diff --git a/core/sections/clause_8_collections.adoc b/core/sections/clause_8_collections.adoc index 8d95a855..c655360d 100644 --- a/core/sections/clause_8_collections.adoc +++ b/core/sections/clause_8_collections.adoc @@ -5,11 +5,11 @@ ==== Overview -The _Collection Input_ Requirements Class supports specifying as an input to a process an <> via using one or more <>. Specifically, the processing server acts as a client and fetches values from the <> using one of the available <> and then feeds the fetched values as input values to the process being executed. The server from which input values are retrieved is referred to as the <>. +The _Collection Input_ Requirements Class supports specifying as an input to a process an <> via using one or more <>. Specifically, the processing server acts as a client and fetches values from the <> using one of the available <> and then feeds the fetched values as input values to the process being executed. The server from which input values are retrieved is referred to as the <>. Unless an implementation also conforms to the <> conformance class, only <> that are locally accessible in the current <> are supported. -Unless an implementation also conforms to the <> conformance class, filtering of values retrieved from an <> is performed by the <>. +Unless an implementation also conforms to the <> conformance class, filtering of values retrieved from an <> is performed by the <>. include::../requirements/requirements_class_collection-input.adoc[] @@ -68,7 +68,7 @@ Either a date-time or an interval, half-bounded or bounded. Date and time expres **Parameter subset** -Retrieve only part of the data by slicing or trimming along one or more axis. For psecifying a trim operation: {axisAbbrev}({low}:{high}) (preserves dimensionality). An asterisk (`*`) can be used instead of {low} or {high} to indicate the minimum/maximum value. For expression a slice operation: {axisAbbrev}({value}) (reduces dimensionality). +Retrieve only part of the data by slicing or trimming along one or more axis. For specifying a trim operation: {axisAbbrev}({low}:{high}) (preserves dimensionality). An asterisk (`*`) can be used instead of {low} or {high} to indicate the minimum/maximum value. For expression a slice operation: {axisAbbrev}({value}) (reduces dimensionality). **Parameter subsetCrs** diff --git a/core/sections/clause_9_process-description.adoc b/core/sections/clause_9_process-description.adoc index bc4a78ed..1df6981d 100644 --- a/core/sections/clause_9_process-description.adoc +++ b/core/sections/clause_9_process-description.adoc @@ -394,14 +394,10 @@ NOTE: This schema can also be obtained from https://raw.githubusercontent.com/op ==== Data classes parameter -T.B.D. - See <>. ==== Data access APIs -T.B.D. - See <>. === Example From a226834babec882c4e0f56e7d8d0b27eb62dcb9b Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Wed, 24 Jun 2026 07:57:50 -0400 Subject: [PATCH 2/2] Add clarifying text about getting the "0-th" value of an output. --- core/sections/clause_7_core.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/core/sections/clause_7_core.adoc b/core/sections/clause_7_core.adoc index d79bc54e..de2a35ff 100644 --- a/core/sections/clause_7_core.adoc +++ b/core/sections/clause_7_core.adoc @@ -1420,10 +1420,12 @@ include::../requirements/core/REQ_job-result-op-Nth.adoc[] NOTE: The size of the value may be determined without actually transmitting the entire result by using the <> method to retrieve the <> header. -===== The zero-th result +===== The "0-th" result include::../requirements/core/REQ_job-result-op-0th.adoc[] +In other words, regardless of the defined cardinality of an output, the first result (i.e. at index value 0) is always accessible. If, however, the cardinality of the output is 1 (i.e. `maxOccurs=1`) then attempting to retrieve an output value using any index value other than _0_ will result in an HTTP 404 exception. Also, if the cardinality of the output is greater than one (i.e. `maxOccurs>1`) then other non-zero index values may be used to retrieve output values. However, out-of-bounds index values will results in an HTTP 404 exception (see requirement: <>). + ==== Response ===== Overview