diff --git a/openapi/workflow_execution_service.openapi.yaml b/openapi/workflow_execution_service.openapi.yaml
index 025b7d56..d129b50e 100644
--- a/openapi/workflow_execution_service.openapi.yaml
+++ b/openapi/workflow_execution_service.openapi.yaml
@@ -2,27 +2,28 @@ openapi: 3.0.0
info:
title: Workflow Execution Service
contact: {}
- version: '1.1.0'
+ version: '1.2.0'
x-logo:
- url: 'https://www.ga4gh.org/wp-content/themes/ga4gh-theme/gfx/GA-logo-horizontal-tag-RGB.svg'
- description: >
+ url: 'https://www.ga4gh.org/wp-content/themes/ga4gh/dist/assets/svg/logos/logo-full-color.svg'
+ description: |
*Run standard workflows on workflow execution platforms in a platform-agnostic way.*
## Executive Summary
- The Workflow Execution Service (WES) API provides a standard way for users to submit workflow requests to workflow execution systems, and to monitor their execution. This API lets users run a single workflow (currently [**CWL**](https://www.commonwl.org/) or [**WDL**](http://www.openwdl.org/) formatted workflows, other types may be supported in the future) on multiple different platforms, clouds, and environments.
+ The Workflow Execution Service (WES) API provides a standard way for users to submit workflow requests to workflow execution systems, and to monitor their execution. This API lets users run a single workflow (commonly [CWL](https://www.commonwl.org/), [WDL](http://www.openwdl.org/), [Nextflow](https://www.nextflow.io/), and [Snakemake](https://Snakemake.readthedocs.io/en/stable/) formatted workflows, WES servers describe what they support via service-info) on multiple different platforms, clouds, and environments.
Key features of the API:
- + can request that a workflow be run
- + can pass parameters to that workflow (e.g. input files, cmdline arguments)
- + can get information about running workflows (e.g. status, errors, output file locations)
- + can cancel a running workflow
+ - can request that a workflow be run
+ - can pass parameters to that workflow (e.g. input files, cmdline arguments) via both workflow-type specific parameter formats as well as a generalized parameter JSON format
+ - can get information about running workflows (e.g. status, errors, output file locations)
+ - can cancel a running workflow
+ - can retrieve logs and outputs file locations from a workflow run
servers:
- url: https://{defaultHost}/{basePath}/{apiVersion}
variables:
defaultHost:
- default: www.example.com
+ default: wes.example.com
basePath:
default: ga4gh/wes
apiVersion:
@@ -34,23 +35,23 @@ tags:
description: Submit and monitor workflows in a WES environment
- name: Introduction
description: |
- This document describes the WES API and provides details on the specific endpoints, request formats, and response. It is intended to provide key information for developers of WES-compatible services as well as clients that will call these WES services.
+ This document describes the WES API and provides details on the specific endpoints, request formats, and responses. It is intended to provide key information for developers of WES-compatible services as well as clients that will call these WES services.
Use cases include:
- + "Bring your code to the data": a researcher who has built their own custom analysis can submit it to run on a dataset owned by an external organization, instead of having to make a copy of the data
- + Best-practices pipelines: a researcher who maintains their own controlled data environment can find useful workflows in a shared directory (e.g. Dockstore.org), and run them over their data
-
+ - "Bring your code to the data": a researcher who has built their own custom analysis workflow can submit it to run on a dataset owned by an external organization, instead of having to download a copy of the data for local analysis.
+ - Best-practices pipelines: a researcher who maintains their own controlled data environment can find useful workflows in a shared repository (e.g. [Dockstore.org](https://dockstore.org)), and run them on their data
+
## Standards
- The WES API specification is written in OpenAPI and embodies a RESTful service philosophy. It uses JSON in requests and responses and standard HTTP/HTTPS for information transport.
+ The WES API specification is written in OpenAPI and embodies a RESTful service philosophy. It uses JSON in requests and responses (where applicable) and standard HTTP/HTTPS for information transport.
- name: Authorization & Authentication
- description: >
+ description: |
Users must supply credentials that establish their identity and authorization in order to use a WES endpoint. We recommend that WES implementations use an OAuth2 [**bearer token**](https://oauth.net/2/bearer-tokens/), although they can choose other mechanisms if appropriate. WES callers can use the `auth_instructions_url` from the [**`service-info` endpoint**](https://ga4gh.github.io/workflow-execution-service-schemas/#/WorkflowExecutionService/GetServiceInfo) to learn how to obtain and use a bearer token for a particular implementation.
The WES implementation is responsible for checking that a user is authorized to submit workflow run requests. The particular authorization policy is up to the WES implementer.
- Systems like WES need to also address the ability to pass credentials with jobs for input and output access. In the current version of WES, the passing of credentials to authenticate and authorize access to inputs and outputs, as well as mandates about necessary file transfer protocols to support, are out of scope. However, parallel work on the Data Object Service is addressing ways to pass around access credentials with data object references, opening up the possibility that a future version of WES will provide concrete mechanisms for workflow runs to access data using credentials different than those used for WES. This is a work in progress and support of DOS in WES will be added in a future release of WES.
+ Systems like WES need to also address the ability to pass credentials with jobs for input and output access. In the current version of WES, the passing of credentials to authenticate and authorize access to inputs and outputs, as well as mandates about necessary file transfer protocols to support, are out of scope. However, parallel work on the [GA4GH Data Repository Service](https://ga4gh.github.io/data-repository-service-schemas/) is addressing ways to pass around access credentials with data object references, opening up the possibility that a future version of WES will provide concrete mechanisms for workflow runs to access data using credentials different than those used for WES calls. This is a work in progress and support of DRS in WES will be added in a future release of WES.
- name: serviceinfo_model
x-displayName: ServiceInfo
description: |
@@ -107,6 +108,14 @@ tags:
x-displayName: WorkflowEngineVersion
description: |
+ - name: workflowoutputs_model
+ x-displayName: WorkflowOutputs
+ description: |
+
+ - name: outputobject_model
+ x-displayName: OutputObject
+ description: |
+
x-tagGroups:
- name: Overview
tags:
@@ -133,13 +142,15 @@ x-tagGroups:
- defaultworkflowengineparameter_model
- workflowtypeversion_model
- workflowengineversion_model
+ - workflowoutputs_model
+ - outputobject_model
paths:
/service-info:
get:
tags:
- Service Info
summary: GetServiceInfo
- description: May include information related (but not limited to) the workflow descriptor formats, versions supported, the WES API versions supported, and information about general service availability.
+ description: Includes information related, but not limited to, the workflow descriptor formats, workflow engines, versions supported, the WES API versions supported, and information about general service availability and access.
operationId: GetServiceInfo
parameters: [ ]
responses:
@@ -198,6 +209,9 @@ paths:
explode: true
schema:
type: string
+ security:
+ - BearerAuth: []
+ - {}
responses:
200:
description: ''
@@ -234,65 +248,115 @@ paths:
post:
tags:
- Workflow Runs
- summary: RunWorkflow
- description: >-
- This endpoint creates a new workflow run and returns a `RunId` to monitor its progress.
+ summary: RunWorkflowOrListRuns
+ description: |
+ This endpoint supports two operations based on the request body content:
+
+ 1. **Submit Workflow Run**: When request body contains `RunRequest` schema, creates a new workflow run and returns a `RunId` to monitor its progress.
+
+ 2. **List Runs with Passport**: When request body contains `RunsListRequest` schema with GA4GH passport authentication, returns a list of workflow runs (same as GET /runs but with passport auth).
+
+ **Workflow Submission (RunRequest)**:
- The `workflow_attachment` array may be used to upload files that are required to execute the workflow, including the primary workflow, tools imported by the workflow, other files referenced by the workflow, or files which are part of the input. The implementation should stage these files to a temporary directory and execute the workflow from there. These parts must have a Content-Disposition header with a "filename" provided for each part. Filenames may include subdirectories, but must not include references to parent directories with '..' -- implementations should guard against maliciously constructed filenames.
+ **Content Types Supported:**
- The `workflow_url` is either an absolute URL to a workflow file that is accessible by the WES endpoint, or a relative URL corresponding to one of the files attached using `workflow_attachment`.
+ 1. **`application/json`** (Recommended for workflows submitted by URLs): Submit a complete `RunRequest` object with structured data and type validation. The advantage of this approach is the schema is explicitly defined by OpenAPI syntax (vs. just strings in multipart-form) along with workflow_unified_params object support (see below for more info). Disadvantage is that it does not support workflow file uploads directly, which may be required for multi-file workflows not available as URLs.
- The `workflow_params` JSON object specifies input parameters, such as input files. The exact format of the JSON object depends on the conventions of the workflow language being used. Input files should either be absolute URLs, or relative URLs corresponding to files uploaded using `workflow_attachment`. The WES endpoint must understand and be able to access URLs supplied in the input. This is implementation specific.
+ 2. **`multipart/form-data`**: Submit for cases requiring workflow file uploads (rather than just a URL). Fields are JSON-encoded strings that mirror the `RunRequest` structure. Advantage is you can upload one or more workflow files directly while the disadvantage is you need to be careful in formatting the JSON-encoded string arguments correctly (multipart form submissions only support strings hence the limitation).
- The `workflow_type` is the type of workflow language and must be "CWL" or "WDL" currently (or another alternative supported by this WES instance).
+ **File Handling:**
- The `workflow_type_version` is the version of the workflow language submitted and must be one supported by this WES instance.
+ - **`application/json` requests**: Workflow file is referenced by URL or path via `workflow_url` with additional workflow files specified by `additional_workflow_urls`. Use `workflow_unified_params` for generic workflow parameterization (recommended when possible) or `workflow_params` for JSON-string encoded native workflow params passing.
- The `workflow_engine` is the engine that supports the workflow_type and must be supported by this WES instance.
-
- The `workflow_engine_version` is the version of workflow engine and must be supported by this WES instance.
+ - **`multipart/form-data` requests**: The `workflow_attachment` array uploads files required for workflow execution. Files are staged to a temporary directory with Content-Disposition headers containing filenames. Subdirectories are allowed but parent directory references ('..') are prohibited for security purposes. Use `workflow_unified_params` for generic workflow parameterization (recommended when possible) or `workflow_params` for JSON-string encoded native workflow params passing.
+
+ **Parameter Formats:**
- See the `RunRequest` documentation for details about other fields.
+ - **`workflow_params`**: Language-specific parameters (CWL, WDL, Nextflow, Snakemake format). This field is used to send the native parameterization file (encoded as a JSON string) used by the workflow engine.
+
+ - **`workflow_unified_params`**: Universal parameter format that the WES server implementation converts to the target workflow language parameterization format. This allows for a more generic way to pass parameters that can be converted to the appropriate native format for the specified `workflow_type`. This is an optional field (and the recommended way to pass params). If provided, it takes precedence over `workflow_params`.
+
+ **Required Fields:**
+
+ - `workflow_type`: Workflow language ("CWL", "WDL", "Nextflow", "Snakemake", or another alternative supported by this WES instance, see service-info)
+
+ - `workflow_type_version`: The workflow descriptor type version, must be one supported by this WES instance, see service-info
+
+ - `workflow_url`: Absolute URL to primary workflow file, or relative path to uploaded attachment
+
+ See the `RunRequest` schema documentation for complete field descriptions and validation rules when encoding as strings in the multipart/form-data request.
operationId: RunWorkflow
parameters: [ ]
requestBody:
content:
+ application/json:
+ schema:
+ oneOf:
+ - $ref: '#/components/schemas/PassportRunRequest'
+ - $ref: '#/components/schemas/RunsListRequest'
multipart/form-data:
encoding: { }
schema:
type: object
properties:
+ passport:
+ $ref: '#/components/schemas/PassportRequestNotRequired'
workflow_params:
type: string
+ description: JSON-encoded native workflow parameters (see RunRequest for how to encode)
+ workflow_unified_params:
+ type: string
+ description: JSON-encoded universal workflow parameters (see RunRequest for how to encode)
workflow_type:
type: string
+ description: Workflow descriptor type must be "CWL", "WDL", "Nextflow", or "Snakemake" currently (or another alternative supported by this WES instance, see service-info)
workflow_type_version:
type: string
+ description: The workflow descriptor type version, must be one supported by this WES instance, see service-info
tags:
type: string
+ description: JSON-encoded object containing key-value tags for the workflow run (e.g., '{"experiment":"rna-seq","user":"john","sample_id":"SAMPLE_001"}')
workflow_engine:
type: string
+ description: The workflow engine, must be one supported by this WES instance. Required if workflow_engine_version is provided.
workflow_engine_version:
type: string
+ description: The workflow engine version, must be one supported by this WES instance. If workflow_engine is provided, but workflow_engine_version is not, servers can make no assumptions with regard to the engine version the WES instance uses to process the request if that WES instance supports multiple versions of the requested engine.
workflow_engine_parameters:
type: string
+ description: JSON-encoded engine-specific parameters (see RunRequest for how to encode)
workflow_url:
type: string
+ description: The workflow document. When workflow_attachment is used to attach files, the workflow_url may be a relative path to one of the attachments.
+ additional_workflow_urls:
+ type: string
+ description: JSON-encoded array of additional workflow URLs (see RunRequest for how to encode)
workflow_attachment:
type: array
items:
type: string
format: binary
- description: ''
- required: false
+ description: >-
+ Files to be staged for workflow execution. You set the filename/path using the Content-Disposition header in the multipart form submission. For example 'Content-Disposition: form-data; name="workflow_attachment"; filename="workflows/helper.wdl"'. The files are staged to a temporary directory and can be referenced by relative path in the workflow_url.
+ required:
+ - workflow_type
+ - workflow_type_version
+ - workflow_url
+ required: true
+ security:
+ - BearerAuth: []
+ - PassportAuth: []
+ - {}
responses:
200:
- description: ''
+ description: 'Success - returns either RunId (for workflow submission) or RunListResponse (for passport-based listing)'
headers: { }
content:
application/json:
schema:
- $ref: '#/components/schemas/RunId'
+ oneOf:
+ - $ref: '#/components/schemas/RunId'
+ - $ref: '#/components/schemas/RunListResponse'
400:
description: The request is malformed.
content:
@@ -333,6 +397,9 @@ paths:
style: simple
schema:
type: string
+ security:
+ - BearerAuth: []
+ - {}
responses:
200:
description: ''
@@ -366,6 +433,62 @@ paths:
schema:
$ref: '#/components/schemas/ErrorResponse'
deprecated: false
+ post:
+ tags:
+ - Workflow Runs
+ summary: GetRunLogWithPassport
+ description: Same as GetRunLog but supports GA4GH passport authentication via POST body. This endpoint provides detailed information about a given workflow run.
+ operationId: GetRunLogWithPassport
+ parameters:
+ - name: run_id
+ in: path
+ description: ''
+ required: true
+ style: simple
+ schema:
+ type: string
+ security:
+ - PassportAuth: []
+ - {}
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PassportRequest'
+ responses:
+ 200:
+ description: ''
+ headers: {}
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RunLog'
+ 401:
+ description: The request is unauthorized.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 403:
+ description: The requester is not authorized to perform this action.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 404:
+ description: The requested workflow run not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 500:
+ description: An unexpected error occurred.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ deprecated: false
'/runs/{run_id}/status':
get:
tags:
@@ -381,6 +504,9 @@ paths:
style: simple
schema:
type: string
+ security:
+ - BearerAuth: []
+ - {}
responses:
200:
description: ''
@@ -414,6 +540,62 @@ paths:
schema:
$ref: '#/components/schemas/ErrorResponse'
deprecated: false
+ post:
+ tags:
+ - Workflow Runs
+ summary: GetRunStatusWithPassport
+ description: Same as GetRunStatus but supports GA4GH passport authentication via POST body. This provides an abbreviated status of the running workflow.
+ operationId: GetRunStatusWithPassport
+ parameters:
+ - name: run_id
+ in: path
+ description: ''
+ required: true
+ style: simple
+ schema:
+ type: string
+ security:
+ - PassportAuth: []
+ - {}
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PassportRequest'
+ responses:
+ 200:
+ description: ''
+ headers: {}
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RunStatus'
+ 401:
+ description: The request is unauthorized.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 403:
+ description: The requester is not authorized to perform this action.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 404:
+ description: The requested workflow run wasn't found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 500:
+ description: An unexpected error occurred.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ deprecated: false
'/runs/{run_id}/tasks':
get:
tags:
@@ -459,6 +641,65 @@ paths:
explode: true
schema:
type: string
+ security:
+ - BearerAuth: []
+ - {}
+ responses:
+ 200:
+ description: ''
+ headers: {}
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TaskListResponse'
+ 401:
+ description: The request is unauthorized.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 403:
+ description: The requester is not authorized to perform this action.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 404:
+ description: The requested workflow run wasn't found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 500:
+ description: An unexpected error occurred.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ deprecated: false
+ post:
+ tags:
+ - Workflow Runs
+ summary: ListTasksWithPassport
+ description: Same as ListTasks but supports GA4GH passport authentication via POST body. This endpoint provides a paginated list of tasks that were executed as part of a given workflow run.
+ operationId: ListTasksWithPassport
+ parameters:
+ - name: run_id
+ in: path
+ description: ''
+ required: true
+ style: simple
+ schema:
+ type: string
+ security:
+ - PassportAuth: []
+ - {}
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TasksListRequest'
responses:
200:
description: ''
@@ -515,6 +756,9 @@ paths:
style: simple
schema:
type: string
+ security:
+ - BearerAuth: []
+ - {}
responses:
200:
description: ''
@@ -548,6 +792,69 @@ paths:
schema:
$ref: '#/components/schemas/ErrorResponse'
deprecated: false
+ post:
+ tags:
+ - Workflow Runs
+ summary: GetTaskWithPassport
+ description: Same as GetTask but supports GA4GH passport authentication via POST body. This endpoint provides information on a specific task.
+ operationId: GetTaskWithPassport
+ parameters:
+ - name: run_id
+ in: path
+ description: ''
+ required: true
+ style: simple
+ schema:
+ type: string
+ - name: task_id
+ in: path
+ description: ''
+ required: true
+ style: simple
+ schema:
+ type: string
+ security:
+ - PassportAuth: []
+ - {}
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PassportRequest'
+ responses:
+ 200:
+ description: ''
+ headers: {}
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TaskLog'
+ 401:
+ description: The request is unauthorized.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 403:
+ description: The requester is not authorized to perform this action.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 404:
+ description: The requested task wasn't found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ 500:
+ description: An unexpected error occurred.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ErrorResponse'
+ deprecated: false
'/runs/{run_id}/cancel':
post:
tags:
@@ -563,6 +870,16 @@ paths:
style: simple
schema:
type: string
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PassportRequestNotRequired'
+ security:
+ - BearerAuth: []
+ - PassportAuth: []
+ - {}
responses:
200:
description: ''
@@ -597,6 +914,19 @@ paths:
$ref: '#/components/schemas/ErrorResponse'
deprecated: false
components:
+ securitySchemes:
+ BearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ description: Standard OAuth2 bearer token authentication
+ PassportAuth:
+ type: http
+ scheme: bearer
+ x-in: body
+ bearerFormat: JWT
+ description:
+ A valid GA4GH Passport must be passed in the body of an HTTP POST request as a passports[] array.
schemas:
ServiceInfo:
title: ServiceInfo
@@ -604,6 +934,10 @@ components:
- $ref: 'https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/v1.0.0/service-info.yaml#/components/schemas/Service'
- type: object
properties:
+ workflow_type:
+ type: object
+ additionalProperties:
+ $ref: '#/components/schemas/WorkflowType'
workflow_type_versions:
type: object
additionalProperties:
@@ -618,6 +952,10 @@ components:
items:
type: string
description: The filesystem protocols supported by this service, currently these may include common protocols using the terms 'http', 'https', 'sftp', 's3', 'gs', 'file', or 'synapse', but others are possible and the terms beyond these core protocols are currently not fixed. This section reports those protocols (either common or not) supported by this WES service.
+ workflow_engine:
+ type: object
+ additionalProperties:
+ $ref: '#/components/schemas/WorkflowEngine'
workflow_engine_versions:
type: object
additionalProperties:
@@ -639,7 +977,7 @@ components:
type: object
additionalProperties:
type: string
- description: A message containing useful information about the running service, including supported versions and default settings.
+ description: Tags containing useful information about the WES service.
required:
- workflow_type_versions
- supported_wes_versions
@@ -671,7 +1009,7 @@ components:
- CANCELING
- PREEMPTED
type: string
- description: >
+ description: |
State can take any of the following values:
+ UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing, for example, so that a missing field does not accidentally imply that the state is QUEUED.
@@ -731,6 +1069,11 @@ components:
required:
- tags
description: Small description of a workflow run
+ PassportRunRequest:
+ title: PassportRunRequest
+ allOf:
+ - $ref: '#/components/schemas/PassportRequestNotRequired'
+ - $ref: '#/components/schemas/RunRequest'
RunRequest:
title: RunRequest
type: object
@@ -742,25 +1085,122 @@ components:
workflow_params:
type: object
description: >-
- REQUIRED
+ OPTIONAL
+
+ The workflow run parameterizations (JSON encoded), including input and output file locations.
+ Either `workflow_params` or `workflow_unified_params` must be provided, `workflow_unified_params` takes precedence.
+ workflow_unified_params:
+ type: object
+ description: >-
+ OPTIONAL
- The workflow run parameterizations (JSON encoded), including input and output file locations
+ Unified parameter format that can be converted to workflow-language-specific format.
+ If provided, takes precedence over workflow_params. WES implementations should
+ convert these to the appropriate native format for the specified workflow_type.
+ properties:
+ version:
+ type: string
+ description: Version of the unified parameter format
+ default: "1.0"
+ parameters:
+ type: object
+ additionalProperties:
+ type: object
+ properties:
+ type:
+ type: string
+ enum: ["String", "Integer", "Float", "Boolean", "File", "Directory", "Array", "Object"]
+ description: Parameter type
+ value:
+ description: Parameter value (type depends on 'type' field)
+ element_type:
+ type: string
+ description: For Array types, specifies the type of array elements
+ file_metadata:
+ type: object
+ description: Optional metadata for File and Directory types
+ properties:
+ size:
+ type: integer
+ description: File size in bytes
+ format: int64
+ checksum:
+ type: string
+ description: File checksum in format 'algorithm:hash' (e.g., 'sha256:abc123...')
+ secondary_files:
+ type: array
+ items:
+ type: string
+ description: Related files such as indexes or companion files
+ format:
+ type: string
+ description: File format or MIME type
+ last_modified:
+ type: string
+ description: Last modification time in ISO 8601 format
+ credential_id:
+ type: string
+ description: Reference to a credential ID defined in the 'credentials' section of the RunRequest. This credential will be used to authenticate and authorize access to this File or Directory resource.
+ description:
+ type: string
+ description: Human-readable parameter description
+ optional:
+ type: boolean
+ default: false
+ description: Whether this parameter is optional
+ default:
+ description: Default value if parameter not provided (type depends on 'type' field)
+ constraints:
+ type: object
+ description: Validation constraints for the parameter value
+ properties:
+ min:
+ description: Minimum value (for numeric types)
+ max:
+ description: Maximum value (for numeric types)
+ min_length:
+ type: integer
+ description: Minimum length (for String types)
+ max_length:
+ type: integer
+ description: Maximum length (for String types)
+ pattern:
+ type: string
+ description: Regular expression pattern (for String types)
+ enum:
+ type: array
+ items:
+ description: Allowed value (type matches parameter type)
+ description: List of allowed values
+ min_items:
+ type: integer
+ description: Minimum number of items (for Array types)
+ max_items:
+ type: integer
+ description: Maximum number of items (for Array types)
+ required:
+ - type
+ - value
workflow_type:
type: string
description: >-
REQUIRED
- The workflow descriptor type, must be "CWL" or "WDL" currently (or another alternative supported by this WES instance)
+ Workflow descriptor type, must be "CWL", "WDL", "Nextflow", or "Snakemake" currently (or another alternative supported by this WES instance, see service-info for supported types)
workflow_type_version:
type: string
description: >-
REQUIRED
- The workflow descriptor type version, must be one supported by this WES instance
+ The workflow descriptor type version, must be one supported by this WES instance (see service-info for supported versions)
tags:
type: object
additionalProperties:
type: string
+ description: >-
+ OPTIONAL
+
+ Arbitrary key-value tags to associate with the workflow run for organization, tracking, or metadata purposes. Examples include experiment names, user identifiers, sample IDs, or project codes.
workflow_engine_parameters:
type: object
additionalProperties:
@@ -768,19 +1208,50 @@ components:
workflow_engine:
type: string
description: >-
- The workflow engine, must be one supported by this WES instance. Required if workflow_engine_version is provided.
+ OPTIONAL
+
+ The workflow engine, must be one supported by this WES instance (see service-info for supported engines). Required if workflow_engine_version is provided.
workflow_engine_version:
type: string
description: >-
- The workflow engine version, must be one supported by this WES instance.
- If workflow_engine is provided, but workflow_engine_version is not, servers can make no assumptions with regard to the engine version the WES instance uses to process the request if
- that WES instance supports multiple versions of the requested engine.
+ OPTIONAL
+
+ The workflow engine version, must be one supported by this WES instance (see service-info for supported engine versions). If workflow_engine is provided, but workflow_engine_version is not, servers can make no assumptions with regard to the engine version the WES instance uses to process the request if that WES instance supports multiple versions of the requested engine.
workflow_url:
type: string
description: >-
REQUIRED
- The workflow CWL or WDL document. When `workflow_attachments` is used to attach files, the `workflow_url` may be a relative path to one of the attachments.
+ The primary workflow document. When `workflow_attachments` is used to attach files, the `workflow_url` may be a relative path to one of the attachments that is the primary workflow to be executed.
+ additional_workflow_urls:
+ type: array
+ items:
+ type: object
+ properties:
+ url:
+ type: string
+ description: URL to the workflow file (absolute URL or relative to uploaded attachments)
+ filename:
+ type: string
+ description: Target filename, possibly including relative path, where this file should be placed e.g. 'workflows/helper.wdl'. Subdirectories are allowed but parent directory references ('..') are prohibited for security purposes.
+ required:
+ - url
+ - filename
+ description: >-
+ OPTIONAL
+
+ Additional workflow files required for execution (e.g., imported workflows, subworkflows, or dependencies). Each entry specifies both the source URL and target file path for precise file placement.
+ credentials:
+ type: object
+ description: >-
+ OPTIONAL
+
+ Named credentials that can be referenced by input parameters that require authentication to access File or Directory resources. Each credential is identified by a unique key and can be referenced multiple times by different parameters to avoid duplicating large authentication tokens.
+ additionalProperties:
+ oneOf:
+ - $ref: '#/components/schemas/PassportCredential'
+ - $ref: '#/components/schemas/BearerTokenCredential'
+ - $ref: '#/components/schemas/ApiKeyCredential'
description: >-
To execute a workflow, send a run request including all the details needed to begin downloading
@@ -820,7 +1291,27 @@ components:
specification (2.0.0)
outputs:
type: object
- description: The outputs from the workflow run.
+ description: >-
+ The outputs from the workflow run (legacy format).
+ For outputs that require authentication to access (such as restricted files or directories),
+ use the 'output_credentials' section of this response to obtain the necessary authentication
+ credentials. The mapping between specific output files and credentials is implementation-specific
+ for this legacy format - use 'structured_outputs' for explicit credential references.
+ structured_outputs:
+ $ref: '#/components/schemas/WorkflowOutputs'
+ description: Structured workflow outputs with rich metadata and type safety
+ output_credentials:
+ type: object
+ description: >-
+ Named credentials required to access workflow output files and directories.
+ Each credential is identified by a unique key and can be referenced by multiple
+ outputs via their 'credential_id' field. These credentials allow clients to
+ authenticate and authorize access to restricted output resources.
+ additionalProperties:
+ oneOf:
+ - $ref: '#/components/schemas/PassportCredential'
+ - $ref: '#/components/schemas/BearerTokenCredential'
+ - $ref: '#/components/schemas/ApiKeyCredential'
Log:
title: Log
type: object
@@ -878,6 +1369,16 @@ components:
type: string
description: The stringified version of the default parameter. e.g. "2.45".
description: A message that allows one to describe default parameters for a workflow engine.
+ WorkflowType:
+ title: WorkflowType
+ type: object
+ properties:
+ workflow_type:
+ type: array
+ items:
+ type: string
+ description: an array of one or more acceptable types for the `workflow_type`, must be "CWL", "WDL", "Nextflow", or "Snakemake" currently (or another alternative supported by this WES instance, see service-info)
+ description: Available workflow types supported by a given instance of the service.
WorkflowTypeVersion:
title: WorkflowTypeVersion
type: object
@@ -886,8 +1387,8 @@ components:
type: array
items:
type: string
- description: an array of one or more acceptable types for the `workflow_type`
- description: Available workflow types supported by a given instance of the service.
+ description: an array of one or more acceptable type and versions for the `workflow_type`. Use the convention `_` to encode this array for clarity. For example, a WES service supporting CWL 1.0 and WDL 1.1 would encode this as `["CWL_1.0", "WDL_1.1"]`.
+ description: Available workflow type versions supported by a given instance of the service.
TaskListResponse:
title: TaskListResponse
type: object
@@ -942,8 +1443,18 @@ components:
type: array
items:
type: string
- description: An array of one or more acceptable engines versions for the `workflow_engine`
+ description: An array of one or more acceptable engines versions for the `workflow_engine`. Since a server may support multiple engines and version, the recommendation is to encode this array as `_` for clarity.
description: Available workflow engine versions supported by a given instance of the service.
+ WorkflowEngine:
+ title: WorkflowEngine
+ type: object
+ properties:
+ workflow_engine:
+ type: array
+ items:
+ type: string
+ description: An array of one or more acceptable workflow engines. Since a server may support multiple engines and version, the recommendation is to encode the workflow_engine_version array as `_` where `workflow_engine` values match this array for clarity.
+ description: Available workflow engines supported by a given instance of the service.
RunListResponse:
title: RunListResponse
type: object
@@ -975,8 +1486,188 @@ components:
description: The integer representing the HTTP status code (e.g. 200, 404).
format: int32
description: An object that can optionally include information about the error.
-
-
+ WorkflowOutputs:
+ title: WorkflowOutputs
+ type: object
+ description: Structured workflow outputs with rich metadata and provenance information
+ properties:
+ version:
+ type: string
+ description: Version of the structured outputs format
+ default: "1.0"
+ outputs:
+ type: object
+ description: Named workflow outputs with structured metadata
+ additionalProperties:
+ $ref: '#/components/schemas/OutputObject'
+ OutputObject:
+ title: OutputObject
+ type: object
+ description: A structured output object with metadata and provenance information
+ properties:
+ class:
+ type: string
+ enum: ["File", "Directory", "Array", "String", "Integer", "Float", "Boolean"]
+ description: Type of the output object
+ value:
+ description: Output value (type depends on class field)
+ location:
+ type: string
+ description: Absolute path or URL to the output file/directory (for File/Directory class)
+ basename:
+ type: string
+ description: Filename without directory path (for File/Directory class)
+ size:
+ type: integer
+ format: int64
+ description: Size in bytes (for File/Directory class)
+ checksum:
+ type: string
+ description: File integrity hash in format 'algorithm:hash' (e.g., 'sha256:abc123...')
+ format:
+ type: string
+ description: MIME type or format identifier (e.g., EDAM ontology reference)
+ items:
+ type: array
+ items:
+ $ref: '#/components/schemas/OutputObject'
+ description: Array elements (for Array class)
+ metadata:
+ type: object
+ description: Additional metadata about the output
+ properties:
+ created:
+ type: string
+ description: Creation timestamp in ISO 8601 format
+ source_task:
+ type: string
+ description: Task/step that generated this output
+ task_id:
+ type: string
+ description: Unique identifier of the generating task
+ command:
+ type: array
+ items:
+ type: string
+ description: Command line that generated this output
+ description:
+ type: string
+ description: Human-readable description of the output
+ secondary_files:
+ type: array
+ items:
+ $ref: '#/components/schemas/OutputObject'
+ description: Associated files (e.g., index files, companion files)
+ contents:
+ type: string
+ description: File contents for small files (≤64 KiB)
+ credential_id:
+ type: string
+ description: Reference to a credential ID defined in the 'output_credentials' section of the RunLog response. This credential is required to authenticate and authorize access to this File or Directory output resource.
+ required:
+ - class
+ - value
+ PassportRequest:
+ title: PassportRequest
+ allOf:
+ - $ref: '#/components/schemas/PassportRequestNotRequired'
+ required:
+ - passport
+ PassportRequestNotRequired:
+ title: PassportRequestNotRequired
+ type: object
+ description: Request object for GA4GH passport-based authentication
+ properties:
+ passport:
+ type: array
+ items:
+ type: string
+ format: jwt
+ description: Array of GA4GH passport JWTs for authentication and authorization
+ minItems: 1
+ RunsListRequest:
+ title: RunsListRequest
+ type: object
+ description: Request object for listing runs with GA4GH passport authentication
+ allOf:
+ - $ref: '#/components/schemas/PassportRequest'
+ - type: object
+ properties:
+ page_size:
+ type: integer
+ format: int64
+ description: OPTIONAL The preferred number of workflow runs to return in a page.
+ page_token:
+ type: string
+ description: OPTIONAL Token to use to indicate where to start getting results.
+ TasksListRequest:
+ title: TasksListRequest
+ type: object
+ description: Request object for listing tasks with GA4GH passport authentication
+ allOf:
+ - $ref: '#/components/schemas/PassportRequest'
+ - type: object
+ properties:
+ page_size:
+ type: integer
+ format: int64
+ description: OPTIONAL The preferred number of task logs to return in a page.
+ page_token:
+ type: string
+ description: OPTIONAL Token to use to indicate where to start getting results.
+ PassportCredential:
+ title: PassportCredential
+ type: object
+ description: GA4GH passport-based credential for accessing restricted resources
+ properties:
+ type:
+ type: string
+ enum: ["passport"]
+ description: Credential type identifier
+ passport:
+ type: array
+ items:
+ type: string
+ format: jwt
+ description: Array of GA4GH passport JWTs for authentication and authorization
+ minItems: 1
+ required:
+ - type
+ - passport
+ BearerTokenCredential:
+ title: BearerTokenCredential
+ type: object
+ description: Bearer token credential for accessing resources
+ properties:
+ type:
+ type: string
+ enum: ["bearer_token"]
+ description: Credential type identifier
+ token:
+ type: string
+ description: Bearer token for authentication
+ required:
+ - type
+ - token
+ ApiKeyCredential:
+ title: ApiKeyCredential
+ type: object
+ description: API key credential for accessing resources
+ properties:
+ type:
+ type: string
+ enum: ["api_key"]
+ description: Credential type identifier
+ key:
+ type: string
+ description: API key for authentication
+ header_name:
+ type: string
+ description: Header name for the API key (defaults to X-API-Key if not specified)
+ default: "X-API-Key"
+ required:
+ - type
+ - key