Common Workflow Language (CWL) Workflow Description, v1.2 &sect;

The unique identifier for this object.

Only useful for $graph at Process level. Should not be exposed to users in graphical or terminal user interfaces.

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

requirements

optional

Declares requirements that apply to either the runtime environment or the workflow engine that must be met in order to execute this process. If an implementation cannot satisfy all requirements, or a requirement is listed which is not recognized by the implementation, it is a fatal error and the implementation must not attempt to run the process, unless overridden at user option.

hints

optional

Declares hints applying to either the runtime environment or the workflow engine that may be helpful in executing this process. It is not an error if an implementation cannot satisfy all hints, however the implementation may report a warning.

cwlVersion

optional

CWLVersion

CWL document version. Always required at the document root. Not required for a Process embedded inside another Process.

intent

optional

array<string>

An identifier for the type of computational operation, of this Process. Especially useful for Operation, but can also be used for CommandLineTool, Workflow, or ExpressionTool.

If provided, then this must be an IRI of a concept node that represents the type of operation, preferably defined within an ontology.

For example, in the domain of bioinformatics, one can use an IRI from the EDAM Ontology's Operation concept nodes, like Alignment, or Clustering; or a more specific Operation concept like Split read mapping.

4.1 WorkflowInputParameter §

Fields

field

required

type

description

type

required

Specify valid types of data that may be assigned to this parameter.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

Provides a pattern or expression specifying files or directories that should be included alongside the primary file. Secondary files may be required or optional. When not explicitly specified, secondary files specified for inputs are required and outputs are optional. An implementation must include matching Files and Directories in the secondaryFiles property of the primary file. These Files and Directories must be transferred and staged alongside the primary file. An implementation may fail workflow execution if a required secondary file does not exist.

If the value is an expression, the value of self in the expression must be the primary input or output File object to which this binding applies. The basename, nameroot and nameext fields must be present in self. For CommandLineTool outputs the path field must also be present. The expression must return a filename string relative to the path to the primary File, a File or Directory object with either path or location and basename fields set, or an array consisting of strings or File or Directory objects. It is legal to reference an unchanged File or Directory object taken from input as a secondaryFile. The expression may return "null" in which case there is no secondaryFile from that expression.

To work on non-filename-preserving storage systems, portable tool descriptions should avoid constructing new values from location, but should construct relative references using basename or nameroot instead.

If a value in secondaryFiles is a string that is not an expression, it specifies that the following pattern should be applied to the path of the primary file to yield a filename relative to the primary File:

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

A value of true indicates that the file is read or written sequentially without seeking. An implementation may use this flag to indicate whether it is valid to stream file contents using a named pipe. Default: false.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

id

optional

The unique identifier for this object.

format

optional

string | array<string> | Expression

Only valid when type: File or is an array of items: File.

This must be one or more IRIs of concept nodes that represents file formats which are allowed as input to this parameter, preferably defined within an ontology. If no ontology is available, file formats may be tested by exact match.

loadContents

optional

Only valid when type: File or is an array of items: File.

If true, the file (or each file in the array) must be a UTF-8 text file 64 KiB or smaller, and the implementation must read the entire contents of the file (or file array) and place it in the contents field of the File object for use by expressions. If the size of the file is greater than 64 KiB, the implementation must raise a fatal error.

loadListing

optional

Only valid when type: Directory or is an array of items: Directory.

Specify the desired behavior for loading the listing field of a Directory object for use by expressions.

The order of precedence for loadListing is:

loadListing on an individual parameter
Inherited from LoadListingRequirement
By default: no_listing

default

optional

File | Directory | Any

The default value to use for this parameter if the parameter is missing from the input object, or if the value of the parameter in the input object is null. Default values are applied before evaluating expressions (e.g. dependent valueFrom fields).

inputBinding

optional

InputBinding

Deprecated. Preserved for v1.0 backwards compatibility. Will be removed in CWL v2.0. Use WorkflowInputParameter.loadContents instead.

4.1.1 SecondaryFileSchema §

Secondary files are specified using the following micro-DSL for secondary files:

If the value is a string, it is transformed to an object with two fields pattern and required
By default, the value of required is null (this indicates default behavior, which may be based on the context)
If the value ends with a question mark ? the question mark is stripped off and the value of the field required is set to False
The remaining value is assigned to the field pattern

For implementation details and examples, please see this section in the Schema Salad specification.

Fields

field

required

type

description

pattern

required

Provides a pattern or expression specifying files or directories that should be included alongside the primary file.

If the value is an expression, the value of self in the expression must be the primary input or output File object to which this binding applies. The basename, nameroot and nameext fields must be present in self. For CommandLineTool inputs the location field must also be present. For CommandLineTool outputs the path field must also be present. If secondary files were included on an input File object as part of the Process invocation, they must also be present in secondaryFiles on self.

The expression must return either: a filename string relative to the path to the primary File, a File or Directory object (class: File or class: Directory) with either location (for inputs) or path (for outputs) and basename fields set, or an array consisting of strings or File or Directory objects as previously described.

It is legal to use location from a File or Directory object passed in as input, including location from secondary files on self. If an expression returns a File object with the same location but a different basename as a secondary file that was passed in, the expression result takes precedence. Setting the basename with an expression this way affects the path where the secondary file will be staged to in the CommandLineTool.

The expression may return "null" in which case there is no secondary file from that expression.

To work on non-filename-preserving storage systems, portable tool descriptions should treat location as an opaque identifier and avoid constructing new values from location, but should construct relative references using basename or nameroot instead, or propagate location from defined inputs.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

required

optional

boolean | Expression

An implementation must not fail workflow execution if required is set to false and the expected secondary file does not exist. Default value for required field is true for secondary files on input and false for secondary files on output.

4.1.2 Expression §

'Expression' is not a real type. It indicates that a field must allow runtime parameter references. If InlineJavascriptRequirement is declared and supported by the platform, the field must also allow Javascript expressions.

Symbols

symbol	description
`ExpressionPlaceholder`

4.1.3 LoadListingEnum §

Specify the desired behavior for loading the listing field of a Directory object for use by expressions.

Symbols

symbol	description
`no_listing`	Do not load the directory listing.
`shallow_listing`	Only load the top level listing, do not recurse into subdirectories.
`deep_listing`	Load the directory listing and recursively load all subdirectories as well.

4.1.4 File §

Represents a file (or group of files when secondaryFiles is provided) that will be accessible by tools using standard POSIX file system call API such as open(2) and read(2).

Files are represented as objects with class of File. File objects have a number of properties that provide metadata about the file.

The location property of a File is a IRI that uniquely identifies the file. Implementations must support the file:// IRI scheme and may support other schemes such as http:// and https://. The value of location may also be a relative reference, in which case it must be resolved relative to the IRI of the document it appears in. Alternately to location, implementations must also accept the path property on File, which must be a filesystem path available on the same host as the CWL runner (for inputs) or the runtime environment of a command line tool execution (for command line tool outputs).

If no location or path is specified, a file object must specify contents with the UTF-8 text content of the file. This is a "file literal". File literals do not correspond to external resources, but are created on disk with contents with when needed for executing a tool. Where appropriate, expressions can return file literals to define new files on a runtime. The maximum size of contents is 64 kilobytes.

The basename property defines the filename on disk where the file is staged. This may differ from the resource name. If not provided, basename must be computed from the last path part of location and made available to expressions.

The secondaryFiles property is a list of File or Directory objects that must be staged in the same directory as the primary file. It is an error for file names to be duplicated in secondaryFiles.

The size property is the size in bytes of the File. It must be computed from the resource and made available to expressions. The checksum field contains a cryptographic hash of the file content for use it verifying file contents. Implementations may, at user option, enable or disable computation of the checksum field for performance or other reasons. However, the ability to compute output checksums is required to pass the CWL conformance test suite.

When executing a CommandLineTool, the files and secondary files may be staged to an arbitrary directory, but must use the value of basename for the filename. The path property must be file path in the context of the tool execution runtime (local to the compute node, or within the executing container). All computed properties should be available to expressions. File literals also must be staged and path must be set.

When collecting CommandLineTool outputs, glob matching returns file paths (with the path property) and the derived properties. This can all be modified by outputEval. Alternately, if the file cwl.output.json is present in the output, outputBinding is ignored.

File objects in the output must provide either a location IRI or a path property in the context of the tool execution runtime (local to the compute node, or within the executing container).

When evaluating an ExpressionTool, file objects must be referenced via location (the expression tool does not have access to files on disk so path is meaningless) or as file literals. It is legal to return a file object with an existing location but a different basename. The loadContents field of ExpressionTool inputs behaves the same as on CommandLineTool inputs, however it is not meaningful on the outputs.

An ExpressionTool may forward file references from input to output by using the same value for location.

Fields

field

required

type

description

class

required

constant value File

Must be File to indicate this object describes a file.

location

optional

An IRI that identifies the file resource. This may be a relative reference, in which case it must be resolved using the base IRI of the document. The location may refer to a local or remote resource; the implementation must use the IRI to retrieve file content. If an implementation is unable to retrieve the file content stored at a remote resource (due to unsupported protocol, access denied, or other issue) it must signal an error.

If the location field is not provided, the contents field must be provided. The implementation must assign a unique identifier for the location field.

If the path field is provided but the location field is not, an implementation may assign the value of the path field to location, then follow the rules above.

path

optional

The local host path where the File is available when a CommandLineTool is executed. This field must be set by the implementation. The final path component must match the value of basename. This field must not be used in any other context. The command line tool being executed must be able to access the file at path using the POSIX open(2) syscall.

As a special case, if the path field is provided but the location field is not, an implementation may assign the value of the path field to location, and remove the path field.

If the path contains POSIX shell metacharacters (|,&, ;, <, >, (,), $,`, \, ", ', <space>, <tab>, and <newline>) or characters not allowed for Internationalized Domain Names for Applications then implementations may terminate the process with a permanentFailure.

basename

optional

The base name of the file, that is, the name of the file without any leading directory path. The base name must not contain a slash /.

If not provided, the implementation must set this field based on the location field by taking the final path component after parsing location as an IRI. If basename is provided, it is not required to match the value from location.

When this file is made available to a CommandLineTool, it must be named with basename, i.e. the final component of the path field must match basename.

dirname

optional

The name of the directory containing file, that is, the path leading up to the final slash in the path such that dirname + '/' + basename == path.

The implementation must set this field based on the value of path prior to evaluating parameter references or expressions in a CommandLineTool document. This field must not be used in any other context.

nameroot

optional

The basename root such that nameroot + nameext == basename, and nameext is empty or begins with a period and contains at most one period. For the purposes of path splitting leading periods on the basename are ignored; a basename of .cshrc will have a nameroot of .cshrc.

The implementation must set this field automatically based on the value of basename prior to evaluating parameter references or expressions.

nameext

optional

The basename extension such that nameroot + nameext == basename, and nameext is empty or begins with a period and contains at most one period. Leading periods on the basename are ignored; a basename of .cshrc will have an empty nameext.

The implementation must set this field automatically based on the value of basename prior to evaluating parameter references or expressions.

checksum

optional

Optional hash code for validating file integrity. Currently, must be in the form "sha1$ + hexadecimal string" using the SHA-1 algorithm.

size

optional

int | long

Optional file size (in bytes)

secondaryFiles

optional

array<File | Directory>

A list of additional files or directories that are associated with the primary file and must be transferred alongside the primary file. Examples include indexes of the primary file, or external references which must be included when loading primary document. A file object listed in secondaryFiles may itself include secondaryFiles for which the same rules apply.

format

optional

The format of the file: this must be an IRI of a concept node that represents the file format, preferably defined within an ontology. If no ontology is available, file formats may be tested by exact match.

Reasoning about format compatibility must be done by checking that an input file format is the same, owl:equivalentClass or rdfs:subClassOf the format required by the input parameter. owl:equivalentClass is transitive with rdfs:subClassOf, e.g. if <B> owl:equivalentClass <C> and <B> owl:subclassOf <A> then infer <C> owl:subclassOf <A>.

File format ontologies may be provided in the "$schemas" metadata at the root of the document. If no ontologies are specified in $schemas, the runtime may perform exact file format matches.

contents

optional

File contents literal.

If neither location nor path is provided, contents must be non-null. The implementation must assign a unique identifier for the location field. When the file is staged as input to CommandLineTool, the value of contents must be written to a file.

If contents is set as a result of a Javascript expression, an entry in InitialWorkDirRequirement, or read in from cwl.output.json, there is no specified upper limit on the size of contents. Implementations may have practical limits on the size of contents based on memory and storage available to the workflow runner or other factors.

If the loadContents field of an InputParameter or OutputParameter is true, and the input or output File object location is valid, the file must be a UTF-8 text file 64 KiB or smaller, and the implementation must read the entire contents of the file and place it in the contents field. If the size of the file is greater than 64 KiB, the implementation must raise a fatal error.

4.1.4.1 Directory §

Represents a directory to present to a command line tool.

Directories are represented as objects with class of Directory. Directory objects have a number of properties that provide metadata about the directory.

The location property of a Directory is a IRI that uniquely identifies the directory. Implementations must support the file:// IRI scheme and may support other schemes such as http://. Alternately to location, implementations must also accept the path property on Directory, which must be a filesystem path available on the same host as the CWL runner (for inputs) or the runtime environment of a command line tool execution (for command line tool outputs).

A Directory object may have a listing field. This is a list of File and Directory objects that are contained in the Directory. For each entry in listing, the basename property defines the name of the File or Subdirectory when staged to disk. If listing is not provided, the implementation must have some way of fetching the Directory listing at runtime based on the location field.

If a Directory does not have location, it is a Directory literal. A Directory literal must provide listing. Directory literals must be created on disk at runtime as needed.

The resources in a Directory literal do not need to have any implied relationship in their location. For example, a Directory listing may contain two files located on different hosts. It is the responsibility of the runtime to ensure that those files are staged to disk appropriately. Secondary files associated with files in listing must also be staged to the same Directory.

When executing a CommandLineTool, Directories must be recursively staged first and have local values of path assigned.

Directory objects in CommandLineTool output must provide either a location IRI or a path property in the context of the tool execution runtime (local to the compute node, or within the executing container).

An ExpressionTool may forward file references from input to output by using the same value for location.

Name conflicts (the same basename appearing multiple times in listing or in any entry in secondaryFiles in the listing) is a fatal error.

Fields

field

required

type

description

class

required

constant value Directory

Must be Directory to indicate this object describes a Directory.

location

optional

An IRI that identifies the directory resource. This may be a relative reference, in which case it must be resolved using the base IRI of the document. The location may refer to a local or remote resource. If the listing field is not set, the implementation must use the location IRI to retrieve directory listing. If an implementation is unable to retrieve the directory listing stored at a remote resource (due to unsupported protocol, access denied, or other issue) it must signal an error.

If the location field is not provided, the listing field must be provided. The implementation must assign a unique identifier for the location field.

If the path field is provided but the location field is not, an implementation may assign the value of the path field to location, then follow the rules above.

path

optional

The local path where the Directory is made available prior to executing a CommandLineTool. This must be set by the implementation. This field must not be used in any other context. The command line tool being executed must be able to access the directory at path using the POSIX opendir(2) syscall.

basename

optional

The base name of the directory, that is, the name of the file without any leading directory path. The base name must not contain a slash /.

When this file is made available to a CommandLineTool, it must be named with basename, i.e. the final component of the path field must match basename.

listing

optional

array<File | Directory>

List of files or subdirectories contained in this directory. The name of each file or subdirectory is determined by the basename field of each File or Directory object. It is an error if a File shares a basename with any other entry in listing. If two or more Directory object share the same basename, this must be treated as equivalent to a single subdirectory with the listings recursively merged.

4.1.5 Any §

The Any type validates for any non-null value.

Symbols

symbol	description
`Any`

4.1.6 CWLType §

Extends primitive types with the concept of a file and directory as a builtin type.

Symbols

symbol	description
`null`	no value
`boolean`	a binary value
`int`	32-bit signed integer
`long`	64-bit signed integer
`float`	single precision (32-bit) IEEE 754 floating-point number
`double`	double precision (64-bit) IEEE 754 floating-point number
`string`	Unicode character sequence
`null`	no value
`boolean`	a binary value
`int`	32-bit signed integer
`long`	64-bit signed integer
`float`	single precision (32-bit) IEEE 754 floating-point number
`double`	double precision (64-bit) IEEE 754 floating-point number
`string`	Unicode character sequence
`File`	A File object
`Directory`	A Directory object

4.1.7 InputRecordSchema §

Fields

field

required

type

description

type

required

constant value record

Must be record

fields

optional

array<InputRecordField> |
map<name, type | InputRecordField>

Defines the fields of the record.

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

name

optional

The identifier for this type

4.1.8 InputRecordField §

Fields

field

required

type

description

name

required

The name of the field

type

required

The field type

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

format

optional

string | array<string> | Expression

Only valid when type: File or is an array of items: File.

loadContents

optional

Only valid when type: File or is an array of items: File.

loadListing

optional

Only valid when type: Directory or is an array of items: Directory.

Specify the desired behavior for loading the listing field of a Directory object for use by expressions.

The order of precedence for loadListing is:

loadListing on an individual parameter
Inherited from LoadListingRequirement
By default: no_listing

4.1.8.1 InputEnumSchema §

Fields

field

required

type

description

symbols

required

array<string>

Defines the set of valid symbols.

type

required

constant value enum

Must be enum

name

optional

The identifier for this type

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

4.1.8.2 InputArraySchema §

Fields

field

required

type

description

items

required

Defines the type of the array elements.

type

required

constant value array

Must be array

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

name

optional

The identifier for this type

4.1.9 InputBinding §

Fields

field

required

type

description

loadContents

optional

Use of loadContents in InputBinding is deprecated. Preserved for v1.0 backwards compatibility. Will be removed in CWL v2.0. Use InputParameter.loadContents instead.

4.2 WorkflowOutputParameter §

Describe an output parameter of a workflow. The parameter must be connected to one or more parameters defined in the workflow that will provide the value of the output parameter. It is legal to connect a WorkflowInputParameter to a WorkflowOutputParameter.

See WorkflowStepInput for discussion of linkMerge and pickValue.

Fields

field

required

type

description

type

required

Specify valid types of data that may be assigned to this parameter.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

id

optional

The unique identifier for this object.

format

optional

Only valid when type: File or is an array of items: File.

This is the file format that will be assigned to the output File object.

outputSource

optional

string | array<string>

Specifies one or more names of an output from a workflow step (in the form step_name/output_name with a / separator`), or a workflow input name, that supply their value(s) to the output parameter. the output parameter. It is valid to reference workflow level inputs here.

linkMerge

optional

LinkMergeMethod

The method to use to merge multiple sources into a single array. If not specified, the default method is "merge_nested".

pickValue

optional

PickValueMethod

The method to use to choose non-null elements among multiple sources.

4.2.1 LinkMergeMethod §

The input link merge method, described in WorkflowStepInput.

Symbols

symbol	description
`merge_nested`
`merge_flattened`

4.2.2 PickValueMethod §

Picking non-null values among inbound data links, described in WorkflowStepInput.

Symbols

symbol	description
`first_non_null`
`the_only_non_null`
`all_non_null`

4.2.3 OutputRecordSchema §

Fields

field

required

type

description

type

required

constant value record

Must be record

fields

optional

array<OutputRecordField> |
map<name, type | OutputRecordField>

Defines the fields of the record.

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

name

optional

The identifier for this type

4.2.4 OutputRecordField §

Fields

field

required

type

description

name

required

The name of the field

type

required

The field type

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

format

optional

Only valid when type: File or is an array of items: File.

This is the file format that will be assigned to the output File object.

4.2.4.1 OutputEnumSchema §

Fields

field

required

type

description

symbols

required

array<string>

Defines the set of valid symbols.

type

required

constant value enum

Must be enum

name

optional

The identifier for this type

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

4.2.4.2 OutputArraySchema §

Fields

field

required

type

description

items

required

Defines the type of the array elements.

type

required

constant value array

Must be array

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

name

optional

The identifier for this type

4.3 WorkflowStep §

A workflow step is an executable element of a workflow. It specifies the underlying process implementation (such as CommandLineTool or another Workflow) in the run field and connects the input and output parameters of the underlying process to workflow parameters.

Scatter/gather §

To use scatter/gather, ScatterFeatureRequirement must be specified in the workflow or workflow step requirements.

A "scatter" operation specifies that the associated workflow step or subworkflow should execute separately over a list of input elements. Each job making up a scatter operation is independent and may be executed concurrently.

The scatter field specifies one or more input parameters which will be scattered. An input parameter may be listed more than once. The declared type of each input parameter implicitly becomes an array of items of the input parameter type. If a parameter is listed more than once, it becomes a nested array. As a result, upstream parameters which are connected to scattered parameters must be arrays.

All output parameter types are also implicitly wrapped in arrays. Each job in the scatter results in an entry in the output array.

If any scattered parameter runtime value is an empty array, all outputs are set to empty arrays and no work is done for the step, according to applicable scattering rules.

If scatter declares more than one input parameter, scatterMethod describes how to decompose the input into a discrete set of jobs.

dotproduct specifies that each of the input arrays are aligned and one element taken from each array to construct each job. It is an error if all input arrays are not the same length.
nested_crossproduct specifies the Cartesian product of the inputs, producing a job for every combination of the scattered inputs. The output must be nested arrays for each level of scattering, in the order that the input arrays are listed in the scatter field.
flat_crossproduct specifies the Cartesian product of the inputs, producing a job for every combination of the scattered inputs. The output arrays must be flattened to a single level, but otherwise listed in the order that the input arrays are listed in the scatter field.

Conditional execution (Optional) §

Conditional execution makes execution of a step conditional on an expression. A step that is not executed is "skipped". A skipped step produces null for all output parameters.

The condition is evaluated after scatter, using the input object of each individual scatter job. This means over a set of scatter jobs, some may be executed and some may be skipped. When the results are gathered, skipped steps must be null in the output arrays.

The when field controls conditional execution. This is an expression that must be evaluated with inputs bound to the step input object (or individual scatter job), and returns a boolean value. It is an error if this expression returns a value other than true or false.

Conditionals in CWL are an optional feature and are not required to be implemented by all consumers of CWL documents. An implementation that does not support conditionals must return a fatal error when attempting to execute a workflow that uses conditional constructs the implementation does not support.

Subworkflows §

To specify a nested workflow as part of a workflow step, SubworkflowFeatureRequirement must be specified in the workflow or workflow step requirements.

It is a fatal error if a workflow directly or indirectly invokes itself as a subworkflow (recursive workflows are not allowed).

Fields

field

required

type

description

in

required

array<WorkflowStepInput> |
map<id, source | WorkflowStepInput>

Defines the input parameters of the workflow step. The process is ready to run when all required input parameters are associated with concrete values. Input parameters include a schema for each parameter which is used to validate the input object. It may also be used build a user interface for constructing the input object.

out

required

array<string | WorkflowStepOutput>

Defines the parameters representing the output of the process. May be used to generate and/or validate the output object.

run

required

string | CommandLineTool | ExpressionTool | Workflow | Operation

Specifies the process to run. If run is a string, it must be an absolute IRI or a relative path from the primary document.

id

optional

The unique identifier for this object.

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

requirements

optional

Declares requirements that apply to either the runtime environment or the workflow engine that must be met in order to execute this workflow step. If an implementation cannot satisfy all requirements, or a requirement is listed which is not recognized by the implementation, it is a fatal error and the implementation must not attempt to run the process, unless overridden at user option.

hints

optional

array<Any> | map<class, Any>

Declares hints applying to either the runtime environment or the workflow engine that may be helpful in executing this workflow step. It is not an error if an implementation cannot satisfy all hints, however the implementation may report a warning.

when

optional

Expression

If defined, only run the step when the expression evaluates to true. If false the step is skipped. A skipped step produces a null on each output.

scatter

optional

string | array<string>

scatterMethod

optional

ScatterMethod

Required if scatter is an array of more than one element.

4.3.1 WorkflowStepInput §

The input of a workflow step connects an upstream parameter (from the workflow inputs, or the outputs of other workflows steps) with the input parameters of the process specified by the run field. Only input parameters declared by the target process will be passed through at runtime to the process though additional parameters may be specified (for use within valueFrom expressions for instance) - unconnected or unused parameters do not represent an error condition.

Input object §

A WorkflowStepInput object must contain an id field in the form #fieldname or #prefix/fieldname. When the id field contains a slash / the field name consists of the characters following the final slash (the prefix portion may contain one or more slashes to indicate scope). This defines a field of the workflow step input object with the value of the source parameter(s).

Merging multiple inbound data links §

To merge multiple inbound data links, MultipleInputFeatureRequirement must be specified in the workflow or workflow step requirements.

If the sink parameter is an array, or named in a workflow scatter operation, there may be multiple inbound data links listed in the source field. The values from the input links are merged depending on the method specified in the linkMerge field. If both linkMerge and pickValue are null or not specified, and there is more than one element in the source array, the default method is "merge_nested".

If both linkMerge and pickValue are null or not specified, and there is only a single element in the source, then the input parameter takes the scalar value from the single input link (it is not wrapped in a single-list).

merge_nested

The input must be an array consisting of exactly one entry for each input link. If "merge_nested" is specified with a single link, the value from the link must be wrapped in a single-item list.
merge_flattened
1. The source and sink parameters must be compatible types, or the source type must be compatible with single element from the "items" type of the destination array parameter.
2. Source parameters which are arrays are concatenated. Source parameters which are single element types are appended as single elements.

Picking non-null values among inbound data links §

If present, pickValue specifies how to pick non-null values among inbound data links.

pickValue is evaluated

Once all source values from upstream step or parameters are available.
After linkMerge.
Before scatter or valueFrom.

This is specifically intended to be useful in combination with conditional execution, where several upstream steps may be connected to a single input (source is a list), and skipped steps produce null values.

Static type checkers should check for type consistency after inferring what the type will be after pickValue is applied, just as they do currently for linkMerge.

first_non_null

For the first level of a list input, pick the first non-null element. The result is a scalar. It is an error if there is no non-null element. Examples:
- [null, x, null, y] -> x
- [null, [null], null, y] -> [null]
- [null, null, null] -> Runtime Error
Intended use case: If-else pattern where the value comes either from a conditional step or from a default or fallback value. The conditional step(s) should be placed first in the list.
the_only_non_null

For the first level of a list input, pick the single non-null element. The result is a scalar. It is an error if there is more than one non-null element. Examples:
- [null, x, null] -> x
- [null, x, null, y] -> Runtime Error
- [null, [null], null] -> [null]
- [null, null, null] -> Runtime Error
Intended use case: Switch type patterns where developer considers more than one active code path as a workflow error (possibly indicating an error in writing when condition expressions).
all_non_null

For the first level of a list input, pick all non-null values. The result is a list, which may be empty. Examples:
- [null, x, null] -> [x]
- [x, null, y] -> [x, y]
- [null, [x], [null]] -> [[x], [null]]
- [null, null, null] -> []
Intended use case: It is valid to have more than one source, but sources are conditional, so null sources (from skipped steps) should be filtered out.

Fields

field

required

type

description

id

optional

The unique identifier for this object.

source

optional

string | array<string>

Specifies one or more workflow parameters that will provide input to the underlying step parameter.

linkMerge

optional

LinkMergeMethod

The method to use to merge multiple inbound links into a single array. If not specified, the default method is "merge_nested".

pickValue

optional

PickValueMethod

The method to use to choose non-null elements among multiple sources.

loadContents

optional

Only valid when type: File or is an array of items: File.

loadListing

optional

Only valid when type: Directory or is an array of items: Directory.

Specify the desired behavior for loading the listing field of a Directory object for use by expressions.

The order of precedence for loadListing is:

loadListing on an individual parameter
Inherited from LoadListingRequirement
By default: no_listing

label

optional

A short, human-readable label of this object.

default

optional

File | Directory | Any

The default value for this parameter to use if either there is no source field, or the value produced by the source is null. The default must be applied prior to scattering or evaluating valueFrom.

valueFrom

optional

To use valueFrom, StepInputExpressionRequirement must be specified in the workflow or workflow step requirements.

If valueFrom is a constant string value, use this as the value for this input parameter.

If valueFrom is a parameter reference or expression, it must be evaluated to yield the actual value to be assigned to the input field.

The self value in the parameter reference or expression must be

null if there is no source field
the value of the parameter(s) specified in the source field when this workflow input parameter is not specified in this workflow step's scatter field.
an element of the parameter specified in the source field when this workflow input parameter is specified in this workflow step's scatter field.

The value of inputs in the parameter reference or expression must be the input object to the workflow step after assigning the source values, applying default, and then scattering. The order of evaluating valueFrom among step input parameters is undefined and the result of evaluating valueFrom on a parameter must not be visible to evaluation of valueFrom on other parameters.

4.3.2 WorkflowStepOutput §

Associate an output parameter of the underlying process with a workflow parameter. The workflow parameter (given in the id field) be may be used as a source to connect with input parameters of other workflow steps, or with an output parameter of the process.

A unique identifier for this workflow output parameter. This is the identifier to use in the source field of WorkflowStepInput to connect the output value to downstream parameters.

Fields

field

required

type

description

id

optional

The unique identifier for this object.

4.3.3 ScatterMethod §

The scatter method, as described in workflow step scatter.

Symbols

symbol	description
`dotproduct`
`nested_crossproduct`
`flat_crossproduct`

4.3.4 InlineJavascriptRequirement §

Indicates that the workflow platform must support inline Javascript expressions. If this requirement is not present, the workflow platform must not perform expression interpolation.

Fields

field

required

type

description

class

required

constant value InlineJavascriptRequirement

Always 'InlineJavascriptRequirement'

expressionLib

optional

array<string>

Additional code fragments that will also be inserted before executing the expression code. Allows for function definitions that may be called from CWL expressions.

4.3.5 SchemaDefRequirement §

This field consists of an array of type definitions which must be used when interpreting the inputs and outputs fields. When a type field contains a IRI, the implementation must check if the type is defined in schemaDefs and use that definition. If the type is not found in schemaDefs, it is an error. The entries in schemaDefs must be processed in the order listed such that later schema definitions may refer to earlier schema definitions.

Type definitions are allowed for enum and record types only.
Type definitions may be shared by defining them in a file and then $include-ing them in the types field.
A file can contain a list of type definitions

Fields

field

required

type

description

class

required

constant value SchemaDefRequirement

Always 'SchemaDefRequirement'

types

required

array<CommandInputRecordSchema | CommandInputEnumSchema | CommandInputArraySchema>

The list of type definitions.

4.3.5.1 CommandInputRecordSchema §

Fields

field

required

type

description

type

required

constant value record

Must be record

fields

optional

array<CommandInputRecordField> |
map<name, type | CommandInputRecordField>

Defines the fields of the record.

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

name

optional

The identifier for this type

inputBinding

optional

Describes how to turn this object into command line arguments.

4.3.5.1.1 CommandInputRecordField §

Fields

field

required

type

description

name

required

The name of the field

type

required

The field type

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

format

optional

string | array<string> | Expression

Only valid when type: File or is an array of items: File.

loadContents

optional

Only valid when type: File or is an array of items: File.

loadListing

optional

Only valid when type: Directory or is an array of items: Directory.

Specify the desired behavior for loading the listing field of a Directory object for use by expressions.

The order of precedence for loadListing is:

loadListing on an individual parameter
Inherited from LoadListingRequirement
By default: no_listing

inputBinding

optional

Describes how to turn this object into command line arguments.

4.3.5.1.1.1 CommandInputEnumSchema §

Fields

field

required

type

description

symbols

required

array<string>

Defines the set of valid symbols.

type

required

constant value enum

Must be enum

name

optional

The identifier for this type

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

inputBinding

optional

Describes how to turn this object into command line arguments.

4.3.5.1.1.2 CommandLineBinding §

When listed under inputBinding in the input schema, the term "value" refers to the corresponding value in the input object. For binding objects listed in CommandLineTool.arguments, the term "value" refers to the effective value after evaluating valueFrom.

The binding behavior when building the command line depends on the data type of the value. If there is a mismatch between the type described by the input schema and the effective value, such as resulting from an expression evaluation, an implementation must use the data type of the effective value.

string: Add prefix and the string to the command line.
number: Add prefix and decimal representation to command line.
boolean: If true, add prefix to the command line. If false, add nothing.
File: Add prefix and the value of File.path to the command line.
Directory: Add prefix and the value of Directory.path to the command line.
array: If itemSeparator is specified, add prefix and the join the array into a single string with itemSeparator separating the items. Otherwise, first add prefix, then recursively process individual elements. If the array is empty, it does not add anything to command line.
object: Add prefix only, and recursively add object fields for which inputBinding is specified.
null: Add nothing.

Fields

field

required

type

description

loadContents

optional

Use of loadContents in InputBinding is deprecated. Preserved for v1.0 backwards compatibility. Will be removed in CWL v2.0. Use InputParameter.loadContents instead.

position

optional

int | Expression

The sorting key. Default position is 0. If a CWL Parameter Reference or CWL Expression is used and if the inputBinding is associated with an input parameter, then the value of self will be the value of the input parameter. Input parameter defaults (as specified by the InputParameter.default field) must be applied before evaluating the expression. Expressions must return a single value of type int or a null.

prefix

optional

Command line prefix to add before the value.

separate

optional

If true (default), then the prefix and value must be added as separate command line arguments; if false, prefix and value must be concatenated into a single command line argument.

itemSeparator

optional

Join the array elements into a single string with the elements separated by itemSeparator.

valueFrom

optional

If valueFrom is a constant string value, use this as the value and apply the binding rules above.

If valueFrom is an expression, evaluate the expression to yield the actual value to use to build the command line and apply the binding rules above. If the inputBinding is associated with an input parameter, the value of self in the expression will be the value of the input parameter. Input parameter defaults (as specified by the InputParameter.default field) must be applied before evaluating the expression.

If the value of the associated input parameter is null, valueFrom is not evaluated and nothing is added to the command line.

When a binding is part of the CommandLineTool.arguments field, the valueFrom field is required.

shellQuote

optional

If ShellCommandRequirement is in the requirements for the current command, this controls whether the value is quoted on the command line (default is true). Use shellQuote: false to inject metacharacters for operations such as pipes.

If shellQuote is true or not provided, the implementation must not permit interpretation of any shell metacharacters or directives.

4.3.5.1.1.3 CommandInputArraySchema §

Fields

field

required

type

description

items

required

Defines the type of the array elements.

type

required

constant value array

Must be array

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

name

optional

The identifier for this type

inputBinding

optional

Describes how to turn this object into command line arguments.

4.3.6 LoadListingRequirement §

Specify the desired behavior for loading the listing field of a Directory object for use by expressions.

Fields

field

required

type

description

class

required

constant value LoadListingRequirement

Always 'LoadListingRequirement'

loadListing

optional

4.3.7 SoftwareRequirement §

A list of software packages that should be configured in the environment of the defined process.

Fields

field

required

type

description

class

required

constant value SoftwareRequirement

Always 'SoftwareRequirement'

packages

required

array<SoftwarePackage> |
map<package, specs | SoftwarePackage>

The list of software to be configured.

4.3.8 SoftwarePackage §

Fields

field

required

type

description

package

required

The name of the software to be made available. If the name is common, inconsistent, or otherwise ambiguous it should be combined with one or more identifiers in the specs field.

version

optional

array<string>

The (optional) versions of the software that are known to be compatible.

specs

optional

array<string>

One or more IRIs identifying resources for installing or enabling the software named in the package field. Implementations may provide resolvers which map these software identifier IRIs to some configuration action; or they can use only the name from the package field on a best effort basis.

For example, the IRI https://packages.debian.org/bowtie could be resolved with apt-get install bowtie. The IRI https://anaconda.org/bioconda/bowtie could be resolved with conda install -c bioconda bowtie.

IRIs can also be system independent and used to map to a specific software installation or selection mechanism. Using RRID as an example: https://identifiers.org/rrid/RRID:SCR_005476 could be fulfilled using the above-mentioned Debian or bioconda package, a local installation managed by Environment Modules, or any other mechanism the platform chooses. IRIs can also be from identifier sources that are discipline specific yet still system independent. As an example, the equivalent ELIXIR Tools and Data Service Registry IRI to the previous RRID example is https://bio.tools/tool/bowtie2/version/2.2.8. If supported by a given registry, implementations are encouraged to query these system independent software identifier IRIs directly for links to packaging systems.

A site specific IRI can be listed as well. For example, an academic computing cluster using Environment Modules could list the IRI https://hpc.example.edu/modules/bowtie-tbb/1.22 to indicate that module load bowtie-tbb/1.1.2 should be executed to make available bowtie version 1.1.2 compiled with the TBB library prior to running the accompanying Workflow or CommandLineTool. Note that the example IRI is specific to a particular institution and computing environment as the Environment Modules system does not have a common namespace or standardized naming convention.

This last example is the least portable and should only be used if mechanisms based off of the package field or more generic IRIs are unavailable or unsuitable. While harmless to other sites, site specific software IRIs should be left out of shared CWL descriptions to avoid clutter.

4.3.9 InitialWorkDirRequirement §

Define a list of files and subdirectories that must be staged by the workflow platform prior to executing the command line tool. Normally files are staged within the designated output directory. However, when running inside containers, files may be staged at arbitrary locations, see discussion for Dirent.entryname. Together with DockerRequirement.dockerOutputDirectory it is possible to control the locations of both input and output files when running in containers.

Fields

field

required

type

description

class

required

constant value InitialWorkDirRequirement

InitialWorkDirRequirement

listing

required

The list of files or subdirectories that must be staged prior to executing the command line tool.

Return type of each expression must validate as ["null", File, Directory, Dirent, {type: array, items: [File, Directory]}].

Each File or Directory that is returned by an Expression must be added to the designated output directory prior to executing the tool.

Each Dirent record that is listed or returned by an expression specifies a file to be created or staged in the designated output directory prior to executing the tool.

Expressions may return null, in which case they have no effect.

Files or Directories which are listed in the input parameters and appear in the InitialWorkDirRequirement listing must have their path set to their staged location. If the same File or Directory appears more than once in the InitialWorkDirRequirement listing, the implementation must choose exactly one value for path; how this value is chosen is undefined.

4.3.9.1 Dirent §

Define a file or subdirectory that must be staged to a particular place prior to executing the command line tool. May be the result of executing an expression, such as building a configuration file from a template.

Usually files are staged within the designated output directory. However, under certain circumstances, files may be staged at arbitrary locations, see discussion for entryname.

Fields

field

required

type

description

entry

required

If the value is a string literal or an expression which evaluates to a string, a new text file must be created with the string as the file contents.

If the value is an expression that evaluates to a File or Directory object, or an array of File or Directory objects, this indicates the referenced file or directory should be added to the designated output directory prior to executing the tool.

If the value is an expression that evaluates to null, nothing is added to the designated output directory, the entry has no effect.

If the value is an expression that evaluates to some other array, number, or object not consisting of File or Directory objects, a new file must be created with the value serialized to JSON text as the file contents. The JSON serialization behavior should match the behavior of string interpolation of Parameter references.

entryname

optional

The "target" name of the file or subdirectory. If entry is a File or Directory, the entryname field overrides the value of basename of the File or Directory object.

Required when entry evaluates to file contents only
Optional when entry evaluates to a File or Directory object with a basename
Invalid when entry evaluates to an array of File or Directory objects.

If entryname is a relative path, it specifies a name within the designated output directory. A relative path starting with ../ or that resolves to location above the designated output directory is an error.

If entryname is an absolute path (starts with a slash /) it is an error unless the following conditions are met:

DockerRequirement is present in requirements
The program is will run inside a software container where, from the perspective of the program, the root filesystem is not shared with any other user or running program.

In this case, and the above conditions are met, then entryname may specify the absolute path within the container where the file or directory must be placed.

writable

optional

If true, the File or Directory (or array of Files or Directories) declared in entry must be writable by the tool.

Changes to the file or directory must be isolated and not visible by any other CommandLineTool process. This may be implemented by making a copy of the original file or directory.

Disruptive changes to the referenced file or directory must not be allowed unless InplaceUpdateRequirement.inplaceUpdate is true.

Default false (files and directories read-only by default).

A directory marked as writable: true implies that all files and subdirectories are recursively writable as well.

If writable is false, the file may be made available using a bind mount or file system link to avoid unnecessary copying of the input file. Command line tools may receive an error on attempting to rename or delete files or directories that are not explicitly marked as writable.

4.3.10 WorkReuse §

For implementations that support reusing output from past work (on the assumption that same code and same input produce same results), control whether to enable or disable the reuse behavior for a particular tool or step (to accommodate situations where that assumption is incorrect). A reused step is not executed but instead returns the same output as the original execution.

If WorkReuse is not specified, correct tools should assume it is enabled by default.

Fields

field

required

type

description

class

required

constant value WorkReuse

Always 'WorkReuse'

enableReuse

required

boolean | Expression

4.3.11 NetworkAccess §

Indicate whether a process requires outgoing IPv4/IPv6 network access. Choice of IPv4 or IPv6 is implementation and site specific, correct tools must support both.

If networkAccess is false or not specified, tools must not assume network access, except for localhost (the loopback device).

If networkAccess is true, the tool must be able to make outgoing connections to network resources. Resources may be on a private subnet or the public Internet. However, implementations and sites may apply their own security policies to restrict what is accessible by the tool.

Enabling network access does not imply a publicly routable IP address or the ability to accept inbound connections.

Fields

field

required

type

description

class

required

constant value NetworkAccess

Always 'NetworkAccess'

networkAccess

required

boolean | Expression

4.3.12 InplaceUpdateRequirement §

If inplaceUpdate is true, then an implementation supporting this feature may permit tools to directly update files with writable: true in InitialWorkDirRequirement. That is, as an optimization, files may be destructively modified in place as opposed to copied and updated.

An implementation must ensure that only one workflow step may access a writable file at a time. It is an error if a file which is writable by one workflow step file is accessed (for reading or writing) by any other workflow step running independently. However, a file which has been updated in a previous completed step may be used as input to multiple steps, provided it is read-only in every step.

Workflow steps which modify a file must produce the modified file as output. Downstream steps which further process the file must use the output of previous steps, and not refer to a common input (this is necessary for both ordering and correctness).

Workflow authors should provide this in the hints section. The intent of this feature is that workflows produce the same results whether or not InplaceUpdateRequirement is supported by the implementation, and this feature is primarily available as an optimization for particular environments.

Users and implementers should be aware that workflows that destructively modify inputs may not be repeatable or reproducible. In particular, enabling this feature implies that WorkReuse should not be enabled.

Fields

field

required

type

description

class

required

constant value InplaceUpdateRequirement

Always 'InplaceUpdateRequirement'

inplaceUpdate

required

4.3.13 ToolTimeLimit §

Set an upper limit on the execution time of a CommandLineTool. A CommandLineTool whose execution duration exceeds the time limit may be preemptively terminated and considered failed. May also be used by batch systems to make scheduling decisions. The execution duration excludes external operations, such as staging of files, pulling a docker image etc, and only counts wall-time for the execution of the command line itself.

Fields

field

required

type

description

field

required

type

description

inputs

required

array<WorkflowInputParameter> |
map<id, type | WorkflowInputParameter>

outputs

required

array<ExpressionToolOutputParameter> |
map<id, type | ExpressionToolOutputParameter>

Defines the parameters representing the output of the process. May be used to generate and/or validate the output object.

class

required

constant value ExpressionTool

expression

required

Expression

The expression to execute. The expression must return a plain Javascript object which matches the output parameters of the ExpressionTool.

id

optional

The unique identifier for this object.

Only useful for $graph at Process level. Should not be exposed to users in graphical or terminal user interfaces.

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

requirements

optional

hints

optional

cwlVersion

optional

CWLVersion

CWL document version. Always required at the document root. Not required for a Process embedded inside another Process.

intent

optional

array<string>

An identifier for the type of computational operation, of this Process. Especially useful for Operation, but can also be used for CommandLineTool, Workflow, or ExpressionTool.

If provided, then this must be an IRI of a concept node that represents the type of operation, preferably defined within an ontology.

4.3.18.1 ExpressionToolOutputParameter §

Fields

field

required

type

description

type

required

Specify valid types of data that may be assigned to this parameter. Note that this field just acts as a hint, as the outputs of an ExpressionTool process are always considered valid.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

id

optional

The unique identifier for this object.

format

optional

Only valid when type: File or is an array of items: File.

This is the file format that will be assigned to the output File object.

4.3.18.2 CWLVersion §

Version symbols for published CWL document versions.

Symbols

symbol	description
`draft-2`
`draft-3.dev1`
`draft-3.dev2`
`draft-3.dev3`
`draft-3.dev4`
`draft-3.dev5`
`draft-3`
`draft-4.dev1`
`draft-4.dev2`
`draft-4.dev3`
`v1.0.dev4`
`v1.0`
`v1.1.0-dev1`
`v1.1`
`v1.2.0-dev1`
`v1.2.0-dev2`
`v1.2.0-dev3`
`v1.2.0-dev4`
`v1.2.0-dev5`
`v1.2`

4.3.19 Operation §

This record describes an abstract operation. It is a potential step of a workflow that has not yet been bound to a concrete implementation. It specifies an input and output signature, but does not provide enough information to be executed. An implementation (or other tooling) may provide a means of binding an Operation to a concrete process (such as Workflow, CommandLineTool, or ExpressionTool) with a compatible signature.

Fields

field

required

type

description

inputs

required

array<OperationInputParameter> |
map<id, type | OperationInputParameter>

outputs

required

array<OperationOutputParameter> |
map<id, type | OperationOutputParameter>

Defines the parameters representing the output of the process. May be used to generate and/or validate the output object.

class

required

constant value Operation

id

optional

The unique identifier for this object.

Only useful for $graph at Process level. Should not be exposed to users in graphical or terminal user interfaces.

label

optional

A short, human-readable label of this object.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

requirements

optional

hints

optional

cwlVersion

optional

CWLVersion

CWL document version. Always required at the document root. Not required for a Process embedded inside another Process.

intent

optional

array<string>

An identifier for the type of computational operation, of this Process. Especially useful for Operation, but can also be used for CommandLineTool, Workflow, or ExpressionTool.

If provided, then this must be an IRI of a concept node that represents the type of operation, preferably defined within an ontology.

4.3.19.1 OperationInputParameter §

Describe an input parameter of an operation.

Fields

field

required

type

description

type

required

Specify valid types of data that may be assigned to this parameter.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

id

optional

The unique identifier for this object.

format

optional

string | array<string> | Expression

Only valid when type: File or is an array of items: File.

loadContents

optional

Only valid when type: File or is an array of items: File.

loadListing

optional

Only valid when type: Directory or is an array of items: Directory.

Specify the desired behavior for loading the listing field of a Directory object for use by expressions.

The order of precedence for loadListing is:

loadListing on an individual parameter
Inherited from LoadListingRequirement
By default: no_listing

default

optional

File | Directory | Any

4.3.19.2 OperationOutputParameter §

Describe an output parameter of an operation.

Fields

field

required

type

description

type

required

Specify valid types of data that may be assigned to this parameter.

label

optional

A short, human-readable label of this object.

secondaryFiles

optional

Only valid when type: File or is an array of items: File.

If string ends with ? character, remove the last ? and mark the resulting secondary file as optional.
If string begins with one or more caret ^ characters, for each caret, remove the last file extension from the path (the last period . and all following characters). If there are no file extensions, the path is unchanged.
Append the remainder of the string to the end of the file path.

streamable

optional

Only valid when type: File or is an array of items: File.

doc

optional

string | array<string>

A documentation string for this object, or an array of strings which should be concatenated.

id

optional

The unique identifier for this object.

format

optional