Add support for the /jobs/{jobId}/results/{outputID}/{N} path. by pvretano · Pull Request #596 · opengeospatial/ogcapi-processes

pvretano · 2026-06-24T11:18:36Z

No description provided.

pvretano · 2026-06-24T12:09:16Z

As discussed in SWG meeting 22-JUL-2026, merging so that we can hand off the document of OGC for RFC.
SWG members will have the opportunity to review the content of this PR during the RFC period; if anything comes up, create a new issue.

fmigneault

@pvretano
Comments placed inline in the PR since it is easier to keep the context this way. I'll create an RFC review issue linking to them.

fmigneault · 2026-06-24T15:36:37Z

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


This header should probably be prefixed by a X- since it is standard-specific.

fmigneault · 2026-06-24T15:40:54Z

+identifier:: /req/core/job-results-async-one-multi-valued
+
+[.component,class=conditions]
+--
+. The <<sc_execution_mode,negotiated execution mode>> is asynchronous.
+. The number of requested (whether <<implicit-process-output,implicitly>> or <<explicit-process-output,explicitly>>) outputs in the <<execute-request-body,execute request>> is 1.


For this case (and same for sync case), it seems like the "number of requested outputs" should not matter (or at least, be >=1) since the /jobs/{jobID}/results/{outputID} endpoint applies to multi-output executions as well, as long as the corresponding results are multi-occurence.

fmigneault · 2026-06-24T15:43:47Z

+[%metadata]
+identifier:: /req/core/job-result-op-0th
+
+For each output, with output identifier `outputID`, defined in the <<sc_process_description,description of a process>> and requested (whether <<implicit-process-output,implicitly>> or <<explicit-process-output,explicitly>>) in an <<execute-request-body,execute request>>, the server SHALL support the HTTP GET operation at the path `/jobs/{jobID}/results/{outputID}/0`.


{outputID} (with brackets) for consistency with other definitions

fmigneault · 2026-06-24T15:43:52Z

+. The output with output identifier `outputID` is defined in the <<sc_process_description,process description>> as having `maxOccurs>1`.
+. The output with output identifier `outputID` is  <<implicit-process-output,implicitly>> or <<explicit-process-output,explicitly>> requested in an <<execute-request-body,execute request>>.


{outputID} (with brackets) for consistency with other definitions

fmigneault · 2026-06-24T15:43:59Z

+--
+. The <<sc_execution_mode,negotiated execution mode>> is asynchronous,
+. The number of requested (whether <<implicit-process-output,implicitly>> or <<explicit-process-output,explicitly>>) outputs in the <<execute-request-body,execute request>> is 1.
+. The requested output with identifier `outputID` is defined in the <<sc_process_description,process description>> as having `maxOccurs>1`.


{outputID} (with brackets) for consistency with other definitions

fmigneault · 2026-06-24T15:50:10Z

+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 <<sc_process_description,process description>>), 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.


It might be worth moving this out (and the corresponding part about it above) into a dedicated /req. That requirement should clarify the 1 value expected when maxOccurs=1, since technically the result value in this case will NOT need to be represented in an array. Is it even erroneous to return OGC-Output-Values-Count in this case?

I am worried that an actual JSON "array-like value" might be incorrectly accessed at index 0 if a client relies on OGC-Output-Values-Count: 1 when no actual "occurence array" is employed for that result (i.e., when the structure of /jobs/{jobID}/results/{outputID} and /jobs/{jobID}/results/{outputID}/0 are identical and N>1 is an error).

This concern is partially discussed in the 'The "0-th" result' section, but it might be a bit far from where this requirement is included to be interpreted properly.

fmigneault · 2026-06-24T15:51:37Z

+--
+. The <<sc_execution_mode,negotiated execution mode>> is synchronous.
+. The number of requested (whether <<implicit-explicit-outputs,implicitly or explicitly>>) outputs in the <<execute-request-body,execute request>> is 1.
+- In its <<sc_process_description,process description>> the requested output is defined as having `maxOccurs>1`.


Not sure if this - is a . typo or not.

fmigneault · 2026-06-24T15:56:47Z

+
+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 <<rec_core_http-head,HTTP HEAD>> method to retrieve the <<rec_core_content-length,`Content-Length`>> header.


Define a /rec ? It uses "may" term.

fmigneault · 2026-06-24T16:01:38Z

+
+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: <<req_core_process-execute-success-async-outputs-Nth,/req/core/process-execute-success-async-outputs-Nth>>).  


Consider a cross-ref to Cardinality (section 9) here on first mention of the term.

fmigneault · 2026-06-24T16:10:30Z

+[[req_core_job-results-async-one-multi-valued]]
+[requirement]
+====
+[%metadata]
+identifier:: /req/core/job-results-async-one-multi-valued


This applies to all requriements about "N".

Is it necessary to make them async-specific? Technically, a server is still allowed to create a job in sync to preserve traceability (/per/core/process-execute-sync-job). It could request a Prefer: return=minimal sync response, and then access the respective ../{N} results one by one on-demand.

pvretano added 2 commits June 24, 2026 07:16

Add support for the /jobs/{jobId}/results/{outputID}/{N} path.

821c86e

Add clarifying text about getting the "0-th" value of an output.

a226834

pvretano merged commit 26f5175 into opengeospatial:master Jun 24, 2026
1 check passed

fmigneault reviewed Jun 24, 2026

View reviewed changes

fmigneault mentioned this pull request Jun 24, 2026

RFC Part 1 Core v2: Job N outputs comments #597

Open

		. The output with output identifier `outputID` is defined in the <<sc_process_description,process description>> as having `maxOccurs>1`.
		. The output with output identifier `outputID` is <<implicit-process-output,implicitly>> or <<explicit-process-output,explicitly>> requested in an <<execute-request-body,execute request>>.

		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 <<sc_process_description,process description>>), 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.


		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 <<rec_core_http-head,HTTP HEAD>> method to retrieve the <<rec_core_content-length,`Content-Length`>> header.


		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: <<req_core_process-execute-success-async-outputs-Nth,/req/core/process-execute-success-async-outputs-Nth>>).

Uh oh!

Conversation

pvretano commented Jun 24, 2026

Uh oh!

pvretano commented Jun 24, 2026

Uh oh!

Uh oh!

fmigneault left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants