Definition for outputs

[JaeAeich]

Problem

The current [WES response schema for outputs](

workflow-execution-service-schemas/openapi/workflow_execution_service.openapi.yaml

Lines 824 to 826 in 03c795c

	outputs:
	type: object
	description: The outputs from the workflow run.

) defines outputs simply as an object. While this is flexible, it’s also very broad, which risks divergence among client implementations.

I understand the challenge of keeping WES general enough to support all workflow engines, but I believe the specification could benefit from stronger recommendations—or even minimal conventions—for how outputs are represented.

---

Proposed Output Classification

In practice, I’ve found it useful to categorize outputs into three broad types:

• meta: Files produced by the engine itself, such as cache files, logs, or system information.
• stage: Intermediate artifacts needed by the engine or backend to run the workflow (e.g., .command.run, .command.sh, or cache files that downstream steps depend on).
• results: The actual outputs of the workflow that are meaningful to the user.

From a user’s perspective, all of these categories matter, but implementations should be smart about filtering out noise (e.g., cache files in meta likely don’t need to be returned to clients).

---

Example Structure

Here’s a simplified version of how I’ve modeled outputs in my own use case:

outputs:
  results:
    relative_path_of_my_results_1:
      url: "presigned S3 URL, file path (e.g. file://results/result_1), or other access method"
      checksum:
        type: sha256
        value: "<checksum_value>"
    relative_path_of_my_results_2:
      url: "presigned S3 URL, file path (e.g. file://results/result_2), or other access method"
      checksum:
        type: sha256
        value: "<checksum_value>"
  meta:
    relative_path_of_my_meta_1:
      url: "presigned S3 URL, file path (e.g. file://meta/meta_1), or other access method"
      checksum:
        type: sha256
        value: "<checksum_value>"

This isn’t the exact implementation, but it conveys the idea.

---

Performance Considerations

This approach worked well for my use case, but running larger workflows exposed a new problem: returning a large number of results in a single API call can degrade performance.

Possible solutions:

1. Separate endpoint – Keep outputs lightweight, but add a new endpoint that returns detailed outputs (potentially with streaming support).
2. Streaming response – Make the existing outputs field itself streamable for large payloads.

---

Suggestion

I propose that the WES spec:

• Recommends (or defines) a minimal schema for categorizing outputs (meta, stage, results).
• Defines how clients should consume outputs (e.g., URLs, checksums).
• Considers large-output workflows by supporting either a separate or streaming endpoint.

This would reduce ambiguity, improve client interoperability, and help implementers balance usability with performance.

[JaeAeich]

cc: @uniqueg @vschnei @vinjana

[uniqueg]

I think these are all very reasonable points that probably need to be addressed for WES to be ready to be used in the real world. I also think that we should perhaps consider allowing engines to optionally specify types and data models for each of the returned objects, to further help clients understand the response. To this end, the discussion is probably related to existing issues on specifying input types etc.

I'm curious how others feel about this.

[vinjana]

I agree. Returning just some JSON object is to arbitrary. So there should be at least some structure. I'm not sure about the exact requirements that structure must fulfill. It would be good to see what other existing WES implementations are returning here.

Concerning the separation into meta, stage, results:

1. If I see this correctly, than for many files in the "meta" and "stage" sections, a WES will be able to identify these files (e.g., log-files that the WES itself produces, and caches/logs/etc., that are produced routinely by the workflow engine).
2. What do you mean by "cache files that downstream steps depend on" (stage files)? Will the identification as "stage" files be known to the workflow engine or WES? Or will it depend on the workflow? The WES cannot be assumed to have detailed knowledge of the workflows, unless the workflows inform the WES somehow (e.g., via a RO-crate file).
3. Probably everything else goes to "results". So whatever goes here is what is not identified as "meta" or "stage", right?

If that is correct, then the results section would give access to the (bioinformatic) result files (that are independent of workflow engine and WES implementation). Having such a section makes sense to me.

[JaeAeich]

To clarify the stage separation: using Nextflow as an example, it’s important for workflows to define storeDir. This directive specifies where intermediate outputs are stored, which is crucial because "downstream steps in the DAG" rely on those files. Without it, the workflow fails (I’ve personally run into this issue).

That said, I agree with you, I wouldn’t be too finicky about enforcing strict separation in the response. The goal is to find a sweet spot: not overwhelming for either implementors or clients. Whether we keep it to results (bioinformatics outputs) and meta (everything else), or introduce another layer as you, the balance matters more than rigid separation.