Proposal - Unifying Status and Results in API 2.0

[christophenoel]

This proposal is in line with my earlier remarks on simplification. 😄

The API is already highly flexible, notably by supporting both synchronous and asynchronous modes, as well as return preference.

I find it excessive to define two distinct schemas (statusInfo and results). A simpler and more consistent design would be to include results within statusInfo, as most processing and workflow engine APIs do.

My proposition for API 2.0 would be:

allOf:
  - $ref: "./descriptionType.yaml"
  - type: object
    required:
      - id
      - status
      - type
    properties:
      id:
        type: string
      processID:
        type: string
        format: uri
      type:
        type: string
        example:
          - process
          - wps
          - openeo
      request:
        oneOf:
          - type: string
          - type: object
          - $ref: "../common-core/link.yaml"
      status:
        $ref: "statusCode.yaml"
      results:
        $ref: "./results.yaml"

...

[fmigneault]

I think this could be allowed.
Rather than a complete replacement, I would suggest that Profile Content Negotiation be used (see #497 and #509).
This way, a request using a new Profile URI could be sent to obtain that structure directly in the GET /jobs/{jobId} response.

[pvretano]

@christophenoel @fmigneault I would like to get a little more clarification about what is being proposed here.

If I understand @christophenoel proposal, we merge the results.yaml schema into the statusInfo.yaml schema.

So my question then becomes, what happen with the /jobs/{jobID}/results endpoint? Does it go away? That seems to be implication since why have the /jobs/{jobID}/results endpoint if you can simply do a GET /jobs/{jobID} and get the results right there?

@fmigneault I know that your proposal allows both approaches to cohabitate but my concern is that having too many ways to get to the same thing does not help the cause of standardization. I think I would prefer we either go with @christophenoel proposal and that is the way to fetch multiple results or we stick with what we have and you get the results from a separate endpoint. Personally I prefer the separate endpoint approach.

One final thought ... the way my implementation includes results in the status response is via the links section using the link relation "results" with the href being the /jobs/{jobID}/results endpoint. I also include a bunch of links with link relation "result" that allows the client for fetch each individual result. In this case the title of each link is the output name.

[fmigneault]

@pvretano

The /jobs/{jobID}/results endpoint can be used to retrieve the results in alternate ways (eg: multipart content, a ZIP, a derived STAC representation, etc.). It also serves as the prefix path for per-output /jobs/{jobID}/results/{outputId} requests.

With results directly in the Job Status, an async process could avoid the extra /jobs/{jobID}/results request if the results are already available, which can be nice. However, that enforces JSON (or at least similar YAML, XML, etc.) to provide the metadata of the job and embed results simultaneously. That limits the alternate representations that can be returned, or cause /jobs/{jobID} to be even more complex.

If it absolutely has to be a "one or the other" choice, I would keep them separate since /jobs/{jobID}/results can do much more than only return the results encoded as JSON. I wouldn't see a problem in having a permission added to the standard to include them directly in job status (already allowed technically by the unrestricted statusInfo.yaml), but it wouldn't be a substitute to /jobs/{jobID}/results requirement.

my implementation includes results in the status response is via the links section using the link relation "results" with the href being the /jobs/{jobID}/results endpoint.

Same on my end.

[christophenoel]

I believe it would be valuable for many client and server implementations if the execute operation could return a statusInfo in both synchronous and asynchronous modes, including the results when available. The current specification seems to support multiple approaches in order to address different preferences (for example, an output directly in the response, an input directly in the property, or in a qualified value, etc.). This suggests that the option in question is legitimate.

In a similar way to how the Simple Feature Profile made GML more accessible, my hope is that once the 2.0 specification becomes available, I can propose a profile for OGC API Processes that provides a reduced but flexible version. I would therefore appreciate that the approach I consider most relevant remains possible within the specification.

[fmigneault]

Another alternative could be to have this in Part 4 - Job Management.
The main issue with Core is that it is already quite large, and technically, a server is allowed to support only sync execution, where Job Status is not required. However, Part 4 is specifically designed for advanced job features (Provenance endpoints, retrieve submitted inputs, etc.).

[bpross-52n]

SWG meeting from 2025-09-15: @pvretano will summarize the discussion and close this issue.

[christophenoel]

Sorry I missed the meeting, I was in holidays.

[christophenoel]

Another alternative could be to have this in Part 4 - Job Management. The main issue with Core is that it is already quite large, and technically, a server is allowed to support only sync execution, where Job Status is not required. However, Part 4 is specifically designed for advanced job features (Provenance endpoints, retrieve submitted inputs, etc.).

You mean a service is not allowed to support only async execution where Job Status is required ??

[jerstlouis]

@christophenoel A server is allowed to support sync, async or both for any given process.

The Job Status is only required for "async" execution (it's optional for sync execution).

[fmigneault]

@christophenoel

You mean a service is not allowed to support only async execution where Job Status is required ??

If you want to enforce only async, each of your processes (summaries in listing and process description) will have to explicitly indicate:

{
  "jobControlOptions": ["async-execute"]
}

The default is that both sync/async are supported.

The minimum requirement is the "least effort" required by implementations, by using sync since it does not require jobs implementation because results are returned directly. You are still allowed to control any sync/async combination on a per-process level.

[christophenoel]

@christophenoel A server is allowed to support sync, async or both for any given process.
The Job Status is only required for "async" execution (it's optional for sync execution).

Ok, so I don't understand your point against results in the statusInfo.

[fmigneault]

@christophenoel
If a server supports only sync (or the process is marked as jobControlOptions: ["sync-execute"]), meaning it returns the output data directly as the requested media-type without any intermediate Job Status info (as async does), using a results within the Job Status JSON would not make sense for these servers/processes.

That means that if results were used, they would be relevant only for async execution, or if the server happens to still create a job reference in sync (which is allowed, but not required).

The .../results endpoint also serves to disambiguate the request/response expectations. For instance, if I want the result to be XML, requesting GET /jobs/{jobID} with Accept: text/xml is ambiguous. Is it the Job Status metadata that should be XML or the embedded results? Both could make sense. We ensure this ambiguity is removed by keeping the status and actual results access on separate endpoints. Job Status response should provide a Link reference to the results once available to guide the client where to retrieve them.