This is version 1.3.0 of the Workflow Description Language (WDL) specification. It describes WDL version 1.3. It introduces a number of new features (denoted by the ✨ symbol) and clarifications to the 1.2.* version of the specification. For an execution engine to be considered compliant with WDL 1.3, you must pass 100% of the compliance tests using spectool.

Deprecations

Aspects of the specification that will be removed in the next major WDL version are denoted by the 🗑 symbol.

Revisions

Revisions to this specification are made periodically in order to correct errors, clarify language, or add additional examples. Revisions are released as "patches" to the specification, i.e., the third number in the specification version is incremented. No functionality is added or removed after the initial revision of the specification is ratified.

• 1.3.0: 2026-01-12

Table of Contents

• Workflow Description Language (WDL)
  • Revisions
  • Table of Contents
  • Introduction
    • An Example WDL Workflow
    • Executing a WDL Workflow
    • Advanced WDL Features
• WDL Language Specification
  • Global Grammar Rules
    • Whitespace
    • Comments
    • Reserved Keywords
    • Literals
    • Types
      • Primitive Types
        • Strings
          • Multi-line Strings
        • Files and Directories
          • Path Canonicalization and Validation
          • Relative and Absolute Paths
      • Optional Types and None
      • Compound Types
        • Array[X]
        • Pair[X, Y]
        • Map[P, Y]
        • 🗑 Object
        • Custom Types (Structs)
        • Enumeration Types (Enums)
      • Type Name References
      • Hidden and Scoped Types
        • Union (Hidden Type)
        • hints, input, and output (Scoped Types)
        • task (Hidden Scoped Type)
        • ✨ task.previous (Hidden Scoped Type)
      • Type Conversion
        • Primitive Conversion to String
        • Type Coercion
          • Order of Precedence
          • Coercion of Optional Types
          • Struct/Object Coercion from Map
          • Struct-to-Struct Coercion
          • 🗑 Limited Exceptions
    • Declarations
    • Expressions
      • Built-in Operators
        • Unary Operators
        • Binary Operators on Primitive Types
        • Equality of Compound Types
        • Equality and Inequality Comparison of Optional Types
      • Operator Precedence Table
      • Member Access
      • Ternary operator (if-then-else)
      • Function Calls
      • Expression Placeholders and String Interpolation
        • Expression Placeholder Coercion
        • Concatenation of Optional Values
      • 🗑 Expression Placeholder Options
        • sep
        • true and false
        • default
    • Static Analysis and Dynamic Evaluation
  • WDL Documents
  • Versioning
  • Struct Definition
  • Enum Definition
    • Enum Usage
    • Enum Serialization and Deserialization
      • JSON Input and Output for Enums
      • Command Section Serialization of Enums
  • Import Statements
    • Import URIs
    • Importing and Aliasing Structs
    • Importing and Aliasing Enums
  • Task Definition
    • Task Inputs
      • Task Input Localization
        • Special Case: Versioning Filesystem
      • Input Type Constraints
        • Optional inputs with defaults
    • Private Declarations
    • Environment Variables
      • String Escaping and Injection Prevention
    • Command Section
      • Expression Placeholders
      • Stripping Leading Whitespace
    • Task Outputs
      • File, Directory, and Optional Outputs
    • Evaluation of Task Declarations
    • Requirements Section
      • Units of Storage
      • Requirements attributes
        • container
        • cpu
        • memory
        • Hardware Accelerators (gpu and fpga)
        • disks
        • max_retries
        • return_codes
    • Hints Section
      • Hints-scoped types
      • Reserved Task Hints
        • max_cpu
        • max_memory
        • disks
        • gpu and fpga
        • short_task
        • localization_optional
        • inputs
        • outputs
      • Compute Environments
      • Conventions and Best Practices
    • 🗑 Runtime Section
    • Metadata Sections
      • Meta Values
      • Task Metadata Section
      • Parameter Metadata Section
    • Runtime Access to Requirements, Hints, and Metadata
      • Output-Only Task Members
  • Workflow Definition
    • Workflow Elements
    • Evaluation of Workflow Elements
    • Fully Qualified Names & Namespaced Identifiers
    • Workflow Inputs
    • Workflow Outputs
    • Workflow Hints
      • Reserved Workflow Hints
        • allow_nested_inputs
    • Call Statement
      • Computing Call Inputs
    • Scatter Statement
    • Conditional Statement
• Standard Library
  • Numeric Functions
    • floor
    • ceil
    • round
    • min
    • max
  • String Functions
    • find
    • matches
    • sub
    • ✨ split
  • File Functions
    • basename
    • join_paths
    • glob
      • Non-standard Bash
    • size
    • stdout
    • stderr
    • read_string
    • read_int
    • read_float
    • read_boolean
    • read_lines
    • write_lines
    • read_tsv
    • write_tsv
    • read_map
    • write_map
    • read_json
    • write_json
    • read_object
    • read_objects
    • write_object
    • write_objects
  • String Array Functions
    • prefix
    • suffix
    • quote
    • squote
    • sep
  • Generic Array Functions
    • range
    • transpose
    • cross
    • zip
    • unzip
    • contains
    • chunk
    • flatten
    • select_first
    • select_all
  • Map Functions
    • as_pairs
    • as_map
    • keys
    • contains_key
    • values
    • collect_by_key
  • ✨ Enum Functions
    • ✨ value
  • Other Functions
    • defined
    • length
• Input and Output Formats
  • JSON Input Format
    • File/Directory Inputs
    • Optional Inputs
    • Specifying / Overriding Requirements and Hints
  • JSON Output Format
    • File/Directory Outputs
  • Extended File/Directory Input/Output Format
  • JSON Serialization of WDL Types
    • Primitive Types
    • Array
    • Struct and Object
    • Pair
      • Pair to Array
      • Pair to Struct
    • Map
      • Map to Struct
      • Map to Array
• Appendix A: WDL Value Serialization and Deserialization
  • Primitive Values
  • Compound Values
    • Array
      • Array serialization by delimitation
      • Array serialization/deserialization using write_lines()/read_lines()
      • Array serialization/deserialization using write_json()/read_json()
    • Pair
      • Homogeneous Pair serialization/deserialization as Array
      • Pair serialization/deserialization using read_json/write_json
    • Map
      • Map serialization by delimitation
      • Map serialization/deserialization using write_map()/read_map()
      • Map serialization/deserialization using write_json()/read_json()
    • Struct and Object serialization/deserialization
• Appendix B: WDL Namespaces and Scopes
  • Namespaces
  • Scopes
    • Global Scope
    • Task Scope
    • Workflow Scope
    • Cyclic References
    • Namespaces without Scope
  • Evaluation Order
• Appendix C: Example Data

Introduction

Workflow Description Language (WDL) is an open, standardized, human readable and writable language for expressing tasks and workflows. WDL is designed to be a general-purpose workflow language, but it is most widely used in the field of bioinformatics. There is a large community of WDL users who share their workflows and tasks on sites such as Dockstore.

This document provides a detailed technical specification for WDL. Users who are new to WDL may appreciate a more gentle introduction, such as the learn-wdl repository.

Here is provided a short example of WDL, after which are several sections that provide the necessary details both for WDL users and for implementers of WDL execution engines:

• Language Specification: a description of the WDL grammar and all the parts of the WDL document.
• Standard Library: a catalog of the functions available to be called from within a WDL document.
• Input and Output Formats: a description of the standard input and output formats that must be supported by all WDL implementations.
• Appendices: Sections with more detailed information about various parts of the specification.

An Example WDL Workflow

Below is the code for the "Hello World" workflow in WDL. This is just meant to give a flavor of WDL syntax and capabilities - all WDL elements are described in detail in the Language Specification.

version 1.3

task hello_task {
  input {
    File infile
    String pattern
  }

  command <<<
    grep -E '~{pattern}' '~{infile}'
  >>>

  requirements {
    container: "ubuntu:latest"
  }

  output {
    Array[String] matches = read_lines(stdout())
  }
}

workflow hello {
  input {
    File infile
    String pattern
  }

  call hello_task {
    infile, pattern
  }

  output {
    Array[String] matches = hello_task.matches
  }
}

{
  "hello.infile": "data/greetings.txt",
  "hello.pattern": "hello.*"
}

{
  "hello.matches": ["hello world", "hello nurse"]
}

Note: you can click the arrow next to the name of any example to expand it and see supplementary information, such as example inputs and outputs.

This WDL document describes a task, called hello_task, and a workflow, called hello.

• A task encapsulates a Bash script and a UNIX environment and presents them as a reusable function.
• A workflow encapsulates a (directed, acyclic) graph of task calls that transforms input data to the desired outputs.

Both workflows and tasks can accept input parameters and produce outputs. For example, workflow hello has two input parameters, File infile and String pattern, and one output parameter, Array[String] matches. This simple workflow calls task hello_task, passing through the workflow inputs to the task inputs, and using the results of call hello_task as the workflow output.

Executing a WDL Workflow

To execute this workflow, a WDL execution engine must be used (sometimes called the "WDL runtime" or "WDL implementation"). Some popular WDL execution engines are listed in the README.

Along with the WDL file, the user must provide the execution engine with values for the two input parameters. While implementations may provide their own mechanisms for launching workflows, all implementations minimally accept inputs as JSON format, which requires that the input arguments be fully qualified according to the namespacing rules described in the Fully Qualified Names & Namespaced Identifiers section. For example:

Running the hello workflow with these inputs would yield the following command line from the call to hello_task:

grep -E 'hello.*' 'greetings.txt'

Advanced WDL Features

WDL also provides features for implementing more complex workflows. For example, hello_task introduced in the previous example can be called in parallel across many different input files using the well-known scatter-gather pattern:

version 1.3

import "hello.wdl"

workflow hello_parallel {
  input {
    Array[File] files
    String pattern
  }
  
  scatter (path in files) {
    call hello.hello_task {
      infile = path,
      pattern = pattern
    }
  }

  output {
    # WDL implicitly implements the 'gather' step, so the output of 
    # a scatter is always an array with the elements in the same 
    # order as the input array. Since hello_task.matches is an array,
    # all the results will be gathered into an array-of-arrays.
    Array[Array[String]] all_matches = hello_task.matches
  }
}

{
  "hello_parallel.pattern": "^[a-z_]+$",
  "hello_parallel.files": ["data/greetings.txt", "data/hello.txt"]
}

{
  "hello_parallel.all_matches": [["hi_world"], ["hello"]]
}

WDL Language Specification

Global Grammar Rules

WDL files are encoded in UTF-8, with no byte order mark (BOM).

Whitespace

Whitespace may be used anywhere in a WDL document. Whitespace has no meaning in WDL, and is effectively ignored.

The following characters are treated as whitespace:

Comments

Comments can be used to provide helpful information such as workflow usage, requirements, copyright, etc. A comment is prepended by # and can be placed at the start of a line or at the end of any line of WDL code. Any text following the # will be completely ignored by the execution engine, with one exception: within the command section, ALL text will be included in the evaluated script - even lines prepended by #.

There is no special syntax for multi-line comments - simply use a # at the start of each line.

# Comments are allowed before version
version 1.3

# This is how you
# write a long
# multiline
# comment

task task_with_comments {
  input {
    Int number  # This comment comes after a variable declaration
  }

  # This comment will not be included within the command
  command <<<
    # This comment WILL be included within the command after it has been parsed
    echo ~{number * 2}
  >>>

  output {
    Int result = read_int(stdout())
  }
    
  requirements {
    container: "ubuntu:latest"
  }
}

workflow workflow_with_comments {
  input {
    Int number
  }

  # You can have comments anywhere in the workflow
  call task_with_comments { number }
  
  output { # You can also put comments after braces
    Int result = task_with_comments.result
  }
}

{
  "workflow_with_comments.number": 1
}

{
  "workflow_with_comments.result": 2
}

Reserved Keywords

The following (case-sensitive) language keywords are reserved and cannot be used to name declarations, calls, tasks, workflows, import namespaces, struct types, or aliases.

Array
Boolean
Directory
File
Float
Int
Map
None
Object
Pair
String
alias
as
call
command
else
enum
false
hints
if
in
import
input
left
meta
object
output
parameter_meta
right
requirements
runtime
scatter
struct
task
then
true
version
workflow

Literals

Task and workflow inputs may be passed in from an external source, or they may be specified in the WDL document itself using literal values. Input, output, and other declaration values may also be constructed at runtime using expressions that consist of literals, identifiers (references to declarations or call outputs), built-in operators, and standard library functions.

Types

A declaration is a name that the user reserves in a given scope to hold a value of a certain type. In WDL all declarations (including inputs and outputs) must be typed. This means that the information about the type of data that may be held by each declarations must be specified explicitly.

In WDL all types represent immutable values. For example, a File represents a logical "snapshot" of the file at the time when the value was created. It is impossible for a task to change an upstream value that has been provided as an input - even if it modifies its local copy, the original value is unaffected.

Primitive Types

The following primitive types exist in WDL:

• A Boolean represents a value of true or false.
• An Int represents a signed 64-bit integer (in the range [-$2^{63}$, $2^{63}$)).
• A Float represents a finite 64-bit IEEE-754 floating point number.
• A String represents a unicode character string following the format described below.
• A File represents a file (or file-like object).
• A Directory represents a (possibly nested) directory of files (as of version 1.2).

version 1.3

task write_file_task {
  command <<<
  mkdir -p testdir
  printf "hello" > testdir/hello.txt
  >>>

  output {
    File x = "testdir/hello.txt"
    Directory d = "testdir"
  }
}

workflow primitive_literals {
  call write_file_task

  output {
    Boolean b = true 
    Int i = 0
    Float f = 27.3
    String s = "hello, world"
    File x = write_file_task.x
    Directory d = write_file_task.d
  }  
}

{}

{
  "primitive_literals.b": true,
  "primitive_literals.i": 0,
  "primitive_literals.f": 27.3,
  "primitive_literals.s": "hello, world",
  "primitive_literals.x": "hello.txt",
  "primitive_literals.d": "testdir"
}

Strings

A string literal may contain any unicode characters between single or double-quotes, with the exception of a few special characters that must be escaped:

Strings can also contain the following types of escape sequences:

• An octal escape code starts with \, followed by 3 digits of value 0 through 7 inclusive.
• A hexadecimal escape code starts with \x, followed by 2 hexadecimal digits 0-9a-fA-F.
• A unicode code point starts with \u followed by 4 hexadecimal characters or \U followed by 8 hexadecimal characters 0-9a-fA-F.

Multi-line Strings

Strings that begin with <<< and end with >>> may span multiple lines.

version 1.3

workflow multiline_strings1 {
  output {
    String s = <<<
      This is a
      multi-line string!
    >>>
  }
}

{}

{
  "multiline_strings1.s": "This is a\nmulti-line string!"
}

In multi-line strings, leading whitespace is removed according to the following rules. In the context of multi-line strings, whitespace refers to space (\x20) and tab characters only and is treated differently from newline characters.

1. Remove all line continuations and subsequent white space.
   • A line continuation is a backslash (\) immediately preceding the newline. A line continuation indicates that two consecutive lines are actually the same line (e.g. when breaking a long line for better readability).
   • If a line ends in multiple \ then standard character escaping applies. Each pair of consecutive backslashes (\\) is an escaped backslash. So a line is continued only if it ends in an odd number of backslashes.
   • Removing a line continuation means removing the last \ character, the immediately following newline, and all the whitespace preceeding the next non-whitespace character or end of line (whichever comes first).
2. Remove all whitespace following the opening <<<, up to and including a newline (if any).
3. Remove all whitespace preceeding the closing >>>, up to and including a newline (if any).
4. Use all remaining non-blank lines to determine the common leading whitespace.
   • A blank line contains zero or more whitespace characters followed by a newline.
   • Common leading whitespace is the minimum number of whitespace characters occuring before the first non-whitespace character in a non-blank line.
   • Each whitespace character is counted once regardless of whether it is a space or tab (so care should be taken when mixing whitespace characters).
5. Remove common leading whitespace from each line.

version 1.3

workflow multiline_strings2 {
  output {
    # all of these strings evaluate to "hello  world"
    String hw0 = "hello  world"
    String hw1 = <<<hello  world>>>
    String hw2 = <<<   hello  world   >>>
    String hw3 = <<<   
        hello  world>>>
    String hw4 = <<<   
        hello  world
        >>>
    String hw5 = <<<   
        hello  world
    >>>
    # The line continuation causes the newline and all whitespace preceding 'world' to be 
    # removed - to put two spaces between 'hello' and world' we need to put them before 
    # the line continuation.
    String hw6 = <<<
        hello  \
            world
    >>>

    # This string is not equivalent - the first line ends in two backslashes, which is an 
    # escaped backslash, not a line continuation. So this string evaluates to 
    # "hello \\\n  world".
    String not_equivalent = <<<
    hello \\
      world
    >>>
  }
}

{}

{
  "multiline_strings2.hw0": "hello  world",
  "multiline_strings2.hw1": "hello  world",
  "multiline_strings2.hw2": "hello  world",
  "multiline_strings2.hw3": "hello  world",
  "multiline_strings2.hw4": "hello  world",
  "multiline_strings2.hw5": "hello  world",
  "multiline_strings2.hw6": "hello  world",
  "multiline_strings2.not_equivalent": "hello \\\n  world"
}

Common leading whitespace is also removed from blank lines that contain whitespace characters; newlines are not removed from blank lines. This means blank lines may be used to ensure that a multi-line string begins/ends with a newline.

version 1.3

workflow multiline_strings3 {
  output {
    # These strings are all equivalent. In strings B, C, and D, the middle lines are blank and 
    # so do not count towards the common leading whitespace determination.

    String multi_line_A = "\nthis is a\n\n  multi-line string\n"
    
    # This string's common leading whitespace is 0.
    String multi_line_B = <<<

    this is a
    
      multi-line string
    
    >>>

    # This string's common leading whitespace is 2. The middle blank line contains two spaces
    # that are also removed.
    String multi_line_C = <<<
    
      this is a
      
        multi-line string

    >>>
    
    # This string's common leading whitespace is 8.
    String multi_line_D = <<<

            this is a
    
              multi-line string

    >>>
  }
}

{}

{
  "multiline_strings3.multi_line_A": "\nthis is a\n\n  multi-line string\n",
  "multiline_strings3.multi_line_B": "\nthis is a\n\n  multi-line string\n",
  "multiline_strings3.multi_line_C": "\nthis is a\n\n  multi-line string\n",
  "multiline_strings3.multi_line_D": "\nthis is a\n\n  multi-line string\n"
}

Single- and double-quotes do not need to be escaped within a multi-line string.

version 1.3

workflow multiline_strings4 {
  output {
    String multi_line_with_quotes = <<<
      multi-line string \
      with 'single' and "double" quotes
    >>>
  }
}

{}

{
  "multiline_strings4.multi_line_with_quotes": "multi-line string with 'single' and \"double\" quotes"
}

Files and Directories

A File or Directory declaration may have have a string value indicating a relative or absolute path on the local file system.

Path Canonicalization and Validation

When a File or Directory value is created, the following operations are performed:

• Path Canonicalization. Intermediate path components are normalized (resolving . for current directory and .. for parent directory segments), symbolic links are resolved to their final targets, and relative paths are converted to their absolute path form. For Directory values, trailing directory separators are removed.
• Path Validation. The path must exist at value creation time. If the path does not exist, an error occurs immediately. The file/directory must accessible for reading (i.e., assigned the appropriate permissions). Additionally, a File value cannot refer to a directory; if the path refers to a directory, an error occurs. Similarly, a Directory value cannot refer to a file; if the path refers to a file, an error occurs.

Value creation occurs when the value is materialized as a File/Directory within the execution engine, including

• When a File or Directory declaration is evaluated
• When a String is coerced to a File or Directory type

After canonicalization, two File or Directory values that refer to the same underlying resource are considered equal for all comparison operations, even if they were initialized from different string representations.

task literals_paths {
  input {
    File f1 = "/foo/bar.txt"
    File? f2
  }

  # If baz.txt does not exist, this is an error.
  File f3 = "baz.txt"

  # If qux.txt does not exist, this is set to `None`.
  File? f4 = "qux.txt"

  command <<<
    # If the user does not overide the value of `f1`, and /foo/bar.txt
    # does not exist, an error will occur when the `File` value is created.
    cat "~{f1}"

    # If the user does not specify the value of `f2` it's value is `None`,
    # which results in the empty-string when interpolated. `-f ""` is
    # always false.
    if [ -f "~{f2}" ]; then
      echo "~{f2}"
    fi
}

Within a WDL file, the execution engine is only required to support literal values for files and directories that are paths local to the execution environment.

During task execution, the following additional constraints apply:

• To write to a file, the path's parent directory must be accessible for writing.
• To write to a directory, it must exist and be accessible for writing.

An execution engine may support other ways to specify File and Directory inputs (e.g., as URIs), but prior to task execution it must localize inputs so that the runtime value of a File/Directory variable is a local path. Remote files must be treated as read-only. For remote files, localization occurs as part of value creation—the remote file must be accessible and valid when the File or Directory value is evaluated, at which point it is localized and the resulting local path is validated according to the rules above.

Relative and Absolute Paths

The interpretation of relative paths (paths that do not start with /) depends on the context in which they appear:

• Outside the output section (e.g., in input or private declarations), relative paths are interpreted relative to the parent directory of the WDL document itself on the host filesystem, similar to how import paths are resolved.
• Inside the output section, relative paths are interpreted relative to the task's execution directory. This is where task commands create their output files. See Task Outputs for details.

In both contexts, if an optional File? or Directory? declaration refers to a path that does not exist, the value is set to None.

Absolute paths (paths starting with /) refer to specific locations on the host filesystem when used outside the output section. Within the output section, absolute paths may be interpreted in a container-dependent way—see Task Outputs for details.

version 1.3

task relative_paths_context {
  # This relative path is resolved relative to the WDL document's parent directory.
  File input_file = "data/hello.txt"

  command <<<
    cat ~{input_file} > output.txt
  >>>

  output {
    # This relative path is resolved relative to the execution directory.
    File result = "output.txt"
    String content = read_string(result)
  }
}

{}

{
  "relative_paths_context.result": "hello.txt"
  "relative_paths_context.content": "hello"
}

{
  "exclude_outputs": ["result"]
}

In this example,

• The input_file input uses a relative path that refers to a file co-located with the WDL document on the host filesystem.
• The result output uses a relative path that refers to a file created by the command in the execution directory.

Optional Types and None

A type may have a ? postfix quantifier, which means that its value is allowed to be undefined without causing an error. A declaration with an optional type can only be used in calls or functions that accept optional values.

Multi-level optionals are not allowed. A value cannot have multiple levels of optionality, for example, Int?? is not a valid type. However, nested optionals within compound types are allowed, such as Array[String?]?, where each ? applies to a different structural level of the type.

WDL has a special value None whose meaning is "an undefined value". The None value has the (hidden) type Union, meaning None can be assigned to an optional declaration of any type.

An optional declaration has a default initialization of None, which indicates that it is undefined. An optional declaration may be initialized to any literal or expression of the correct type, including the special None value.

version 1.3

workflow optionals {
  input {
    Int certainly_five = 5      # an non-optional declaration
    Int? maybe_five_and_is = 5  # a defined optional declaration

    # the following are equivalent undefined optional declarations
    String? maybe_five_but_is_not
    String? also_maybe_five_but_is_not = None
  }

  output {
    Boolean test_defined = defined(maybe_five_but_is_not) # Evaluates to false
    Boolean test_defined2 = defined(maybe_five_and_is)    # Evaluates to true
    Boolean test_is_none = maybe_five_but_is_not == None  # Evaluates to true
    Boolean test_not_none = maybe_five_but_is_not != None # Evaluates to false
    Boolean test_non_equal = maybe_five_but_is_not == also_maybe_five_but_is_not
  }
}

{}

{
  "optionals.test_defined": false,
  "optionals.test_defined2": true,
  "optionals.test_is_none": true,
  "optionals.test_not_none": false,
  "optionals.test_non_equal": true
}

For more details, see the sections on Input Type Constraints and Optional Inputs with Defaults.

Compound Types

A compound type is one that contains nested types, i.e. it is parameterized by other types. The following compound types can be constructed. In the examples below P represents any of the primitive types above, and X and Y represent any valid type (including nested compound types).

Array[X]

An Array represents an ordered list of elements that are all of the same type. An array is insertion ordered, meaning the order in which elements are added to the Array is preserved.

An array value can be initialized with an array literal - a comma-separated list of values in brackets ([]). A specific zero-based index of an Array can be accessed by placing the index in brackets after the declaration name. Accessing a non-existent index of an Array results in an error.

version 1.3

workflow array_access {
  input {
    Array[String] strings
    Int index
  }

  output {
    String s = strings[index]
  }
}

{
  "array_access.strings": ["hello", "world"],
  "array_access.index": 0
}

{
  "array_access.s": "hello"
}

version 1.3

workflow empty_array_fail {
  Array[Int] empty = []
  
  output {
    # this causes an error - trying to access a non-existent array element
    Int i = empty[0]
  }
}

{}

{}

{
  "fail": true
}

An Array may have an empty value (i.e. an array of length zero), unless it is declared using +, the non-empty postfix quantifier, which represents a constraint that the Array value must contain one-or-more elements. For example, the following task operates on an Array of Strings and it requires at least one string to function:

version 1.3

task sum {
  input {
    Array[String]+ ints
  }
  
  command <<<
  printf "~{sep(" ", ints)}" | awk '{tot=0; for(i=1;i<=NF;i++) tot+=$i; print tot}'
  >>>
  
  output {
    Int total = read_int(stdout())
  }
}

{
  "sum.ints": ["0", "1", "2"]
}

{
  "sum.total": 3
}

Recall that a type may have an optional postfix quantifier (?), which means that its value may be undefined. The + and ? postfix quantifiers can be combined to declare an Array that is either undefined or non-empty, i.e. it can have any value except the empty array.

Attempting to assign an empty array literal to a non-empty Array declaration results in an error. Otherwise, the non-empty assertion is only checked at runtime: binding an empty array to an Array[T]+ input or function argument is a runtime error.

version 1.3

workflow non_empty_optional {
  output {
    # array that must contain at least one Float
    Array[Float]+ nonempty1 = [0.0]
    # array that must contain at least one Int? (which may have an undefined value)
    Array[Int?]+ nonempty2 = [None, 1]
    # array that can be undefined or must contain at least one Int
    Array[Int]+? nonempty3 = None
    Array[Int]+? nonempty4 = [0]
  }
}

{}

{
  "non_empty_optional.nonempty1": [0.0],
  "non_empty_optional.nonempty2": [null, 1],
  "non_empty_optional.nonempty3": null,
  "non_empty_optional.nonempty4": [0]
}

version 1.3

workflow non_empty_optional_fail {
  # these both cause an error - can't assign empty array value to non-empty Array type
  Array[Boolean]+ nonempty3 = []
  Array[Int]+? nonempty6 = [] 
}

{}

{}

{
  "fail": true
}

For more details see the section on Input Type Constraints.

Pair[X, Y]

A Pair represents two associated values, which may be of different types. In other programming languages, a Pair might be called a "two-tuple".

A Pair can be initialized with a pair literal - a comma-separated pair of values in parentheses (()). The components of a Pair value are accessed using its left and right accessors.

version 1.3

workflow test_pairs {
  Pair[Int, Array[String]] data = (5, ["hello", "goodbye"])

  output {
    Int five = data.left  # evaluates to 5
    String hello = data.right[0]  # evaluates to "hello"
  }
}

{}

{
  "test_pairs.five": 5,
  "test_pairs.hello": "hello"
}

Map[P, Y]

A Map represents an associative array of key-value pairs. All of the keys must be of the same (primitive) type, and all of the values must be of the same type, but keys and values can be different types.

A Map can be initialized with a map literal - a comma-separated list of key-value pairs in braces ({}), where key-value pairs are delimited by :. The value of a specific key can be accessed by placing the key in brackets after the declaration name. Accessing a non-existent key of a Map results in an error.

version 1.3

workflow test_map {
  Map[Int, Int] int_to_int = {1: 10, 2: 11}
  Map[String, Int] string_to_int = { "a": 1, "b": 2 }
  Map[File, Array[Int]] file_to_ints = {
    "data/cities.txt": [0, 1, 2],
    "data/hello.txt": [9, 8, 7]
  }

  output {
    Int ten = int_to_int[1]  # evaluates to 10
    Int b = string_to_int["b"]  # evaluates to 2
    Array[Int] ints = file_to_ints["data/cities.txt"]  # evaluates to [0, 1, 2]
  }
}

{}

{
  "test_map.ten": 10,
  "test_map.b": 2,
  "test_map.ints": [0, 1, 2]
}

version 1.3

workflow test_map_fail {
  Map[String, Int] string_to_int = { "a": 1, "b": 2 }
  Int c = string_to_int["c"]  # error - "c" is not a key in the map
}

{}

{}

{
  "fail": true
}

A Map is insertion-ordered, meaning the order in which elements are added to the Map is preserved, for example when converting a Map to an array of Pairs.

version 1.3

workflow test_map_ordering {
  # declaration using a map literal
  Map[Int, Int] int_to_int = { 2: 5, 1: 10 }

  scatter (ints in as_pairs(int_to_int)) {
    Array[Int] i = [ints.left, ints.right]
  }

  output {
    # evaluates to [[2, 5], [1, 10]]
    Array[Array[Int]] ints = i
  }
}

{}

{
  "test_map_ordering.ints": [[2, 5], [1, 10]]
}

🗑 Object

An Object is an unordered associative array of name-value pairs, where values may be of any type and are not defined explicitly.

An Object can be initialized using an object literal value, which begins with the object keyword followed by a comma-separated list of name-value pairs in braces ({}), where name-value pairs are delimited by :. The member names in an object literal are not quoted. The value of a specific member of an Object value can be accessed by placing a . followed by the member name after the identifier.

version 1.3

workflow test_object {
  output {
    Object obj = object {
      a: 10,
      b: "hello"
    }
    Int i = obj.a
  }
}

{}

{
  "test_object.obj": {
    "a": 10,
    "b": "hello"
  },
  "test_object.i": 10
}

Due to the lack of explicitness in the typing of Object being at odds with the goal of being able to know the type information of all WDL declarations, the use of the Object type and the object literal syntax have been deprecated. In WDL 2.0, Object will become a hidden type that may only be instantiated by the execution engine. Object declarations can be replaced with use of structs.

Custom Types (Structs)

WDL provides the ability to define custom compound types called structs. Struct types are defined at the top-level of the WDL document and are usable like any other type. A struct is defined using the struct keyword, followed by a unique name, followed by member declarations within braces. A struct definition contains any number of declarations of any types, including other Structs.

A declaration with a custom type can be initialized with a struct literal, which begins with the Struct type name followed by a comma-separated list of name-value pairs in braces ({}), where name-value pairs are delimited by :. The member names in a struct literal are not quoted. A struct literal must provide values for all of the struct's non-optional members, and may provide values for any of the optional members. The members of a struct literal are validated against the struct's definition at the time of creation. Members do not need to be in any specific order. Once a struct literal is created, it is immutable like any other WDL value.

The value of a specific member of a struct value can be accessed by placing a . followed by the member name after the identifier.

version 1.3

struct BankAccount {
  String account_number
  Int routing_number
  Float balance
  Array[Int]+ pin_digits
  String? username
}

struct Person {
  String name
  BankAccount? account
}

workflow test_struct {
  output {
    Person john = Person {
      name: "John",
      # it's okay to leave out username since it's optional
      account: BankAccount {
        account_number: "123456",
        routing_number: 300211325,
        balance: 3.50,
        pin_digits: [1, 2, 3, 4]
      }
    }
    Boolean has_account = defined(john.account)
  }
}

{}

{
  "test_struct.john": {
    "name": "John",
    "account": {
      "account_number": "123456",
      "routing_number": 300211325,
      "balance": 3.5,
      "pin_digits": [1, 2, 3, 4],
      "username": null
    }
  },
  "test_struct.has_account": true
}

version 1.3

# importing a WDL automatically imports all its structs into
# the current namespace
import "test_struct.wdl"

workflow incomplete_struct {
  output {
    # error! missing required account_number
    Person fail1 = Person {
      "name": "Sam",
      "account": BankAccount {
        routing_number: 611325474,
        balance: 9.99,
        pin_digits: [5, 5, 5, 5]
      }
    }
    # error! pin_digits is empty
    Person fail2 = Person {
      "name": "Bugs",
      "account": BankAccount {
        account_number: "FATCAT42",
        routing_number: 880521345,
        balance: 50.01,
        pin_digits: []
      }
    }
  }
}

{}

{}

{
  "fail": true
}

🗑 It is also possible to assign an Object or Map[String, X] value to a Struct declaration. In the either case:

• The value of each Object/Map member must be coercible to the declared type of the struct member.
• The Object/Map must at least contain values for all of the struct's non-optional members.
• Any Object/Map member that does not correspond to a member of the struct is ignored.

Note that the ability to assign values to Struct declarations other than struct literals is deprecated and will be removed in WDL 2.0.

Enumeration Types (Enums)

An enumeration (or "enum") is a closed set of enumerated values (known as "choices") that are considered semantically valid in a specific context. An enum is defined at the top-level of the WDL document and can be used as a declaration type anywhere in the document.

An enum is defined using the enum keyword, followed by a globally unique name, followed by a comma-delimited list of identifiers—optionally tagged with values—in braces. When referring to a choice within an enum, for example, when assigning to an enum declaration, the <name>.<choice> syntax should be used.

enum FileKind {
  FASTQ,
  BAM
}

task process_file {
  input {
    File infile
    FileKind kind = FileKind.FASTQ
  }
  
  command <<<
  echo "Processing ~{kind} file"
  ...
  >>>
}
workflow process_files {
  input {
    Array[File] files
    FileKind kind
  }

  scatter (file in files) {
    call process_file {
      input:
        infile = file,
        kind = kind
    }
  }
}

As an example, consider a workflow that processes different types of NGS files and has a file_kind input parameter that is expected to be either "FASTQ" or "BAM". Using String as the type of file_kind is not ideal - if the user specifies an invalid value, the error will not be caught until runtime, perhaps after the workflow has already run for several hours. Alternatively, using an enum type for file_kind restricts the allowed values such that the execution engine can validate the input prior to executing the workflow.

Enums are valued, meaning that each choice within an enum has an associated value. Enum values can be of any WDL type, including primitive types (String, Int, Float, Boolean), compound types (Array, Map, Pair, Object), and user-defined types (Struct). To assign a type to the values therein, enums can either be explicitly or implicitly typed.

• Explicitly typed enums take an explicit type assignment within square brackets after the enum's identifier that declares the type of the value. Explicitly typed enums may include values that coerce to the declared type.
• Implicitly typed enums are enums where the values can be unambiguously resolved to a single type following WDL's type coercion rules. If the values do not coerce to a single common type, an error is thrown. Enums that are implicitly typed and for which no values are assigned are assumed to be String valued with values matching the choice names.

If any non-String values are provided for an enum's choices, then all choices must have explicit values. In the case where all values are String (or the enum is implicitly typed as String), choices without explicit values are automatically assigned a value equal to the choice name.

Enum values must be literal expressions only. This includes string literals (which may contain escape sequences like "\t"), numeric literals, boolean literals, collection literals (Array, Map, Pair), object literals, and struct literals. String interpolation, variable references, and computed expressions are not allowed in enum values, as enums are global declarations that must be evaluable at parse time.

# An explicitly typed enum that is `String`-valued.
enum FruitColors[String] {
  Banana = "yellow",
  Orange = "orange",
  Apple = "red",
}

# An explicitly typed enum that is `Float`-valued. Because the enum is
# explicitly typed, the `ThreePointOh` choice can be coerced to a `Float`,
# which is a valid enumeration definition.
enum FavoriteFloat[Float] {
  ThreePointOh = 3,
  FourPointOh = 4.0
}

# An implicitly typed enum where the inner type is unambiguously resolved to
# `Float`. Following WDL's type coercion rules, `Int` values coerce to `Float`.
enum FavoriteNumber {
  ThreePointOh = 3,
  FourPointOh = 4.0
}

# ERROR: the inner type of this enum cannot be unambiguously resolved, as
# `Int` and `String` do not coerce to a common type.
enum InvalidEnum {
  Number = 42,
  Text = "hello"
}

# ERROR: cannot use computed expressions in enum values
enum Bad1 {
  Two = 1 + 1
}

# ERROR: cannot use string interpolation in enum values
enum Bad2 {
  Greeting = "Hello ~{world}"
}

# ERROR: cannot use function calls in enum values
enum Bad3 {
  Three = length([1, 2, 3])
}

# An implicitly typed enum that is `String`-valued.
enum Whitespace {
  Tab = "\t",
  Space = " "
}

# An implicitly typed enum that is implied to be `String`-valued with the
# values "FASTQ" and "BAM" respectively.
enum FileKind {
  FASTQ,
  BAM
}

# An explicitly typed enum with `Array[String]` values. This allows for
# defining sets of related string constants as enum choices.
enum Contigs[Array[String]] {
  Canonical = ["chr1", "chr2", "chr3", "chr4", "chr5"],
  All = ["chr1", "chr2", "chr3", "chr4", "chr5", "chrM", "chrX", "chrY"]
}

# An implicitly typed enum with `Map[String, Int]` values.
enum DefaultConfig {
  Fast = { "threads": 4, "memory_gb": 8 },
  Standard = { "threads": 8, "memory_gb": 16 },
  HighMem = { "threads": 16, "memory_gb": 64 }
}

Type Name References

A type name reference represents a reference to a custom type by name. When a custom type name appears in an expression context (rather than in a type declaration position), it evaluates to a type name reference. At the time of writing, type name references are only meaningful for enums.

Type name references are evaluated as part of normal expression evaluation, so any expression that evaluates to a type name reference can be used wherever a type name reference is expected. Type name references are primarily used with enums to access enum choices using the member access operator (.). For example, in the expression Color.Red, the identifier Color evaluates to a type name reference to the Color enum type, which can then be accessed to retrieve the Red choice. Since type name references participate in expression evaluation, expressions like (Color).Red are also valid.

There is no postulated use case for struct type name references. Member access on a struct type name reference produces an error. Type name references cannot be coerced to any other type.

enum Priority {
  Low,
  Medium,
  High
}

workflow example {
  Priority p1 = Priority.Low     # Priority is a type name reference
  Priority p2 = (Priority).High  # Expression evaluates to type name reference
}

Hidden and Scoped Types

A hidden type is one that may only be instantiated by the execution engine, and cannot be used in a declaration within a WDL file.

A scoped type is one that can only be defined by the execution engine within a specific scope. A scoped type may also be hidden.

The following sections enumerate the hidden and scoped types that are available in the current version of WDL. In WDL 2.0, Object will also become a hidden type.

Union (Hidden Type)

Union is a hidden type that is used for a value that may have any one of several concrete types. A Union value must always be coerced to a concrete type. The Union type is used in the following contexts:

• It is the type of the special None value.
• It is the return type of some standard library functions, such as read_json.
• It is the type of some requirements and reserved hints attributes.

hints, input, and output (Scoped Types)

The hints section has three scoped types that may be instantiated by the user within that scope.

task (Hidden Scoped Type)

The task type is a hidden type that is available in both pre-evaluation contexts (requirements, hints, and the deprecated runtime sections) with a limited set of members, and in post-evaluation contexts (command and output sections) with the full set of members.

✨ task.previous (Hidden Scoped Type)

The task.previous type is a hidden type that contains the previously computed requirements from the last task attempt. It is scoped to within the task variable and contains the following optional members:

• memory: An Int? with the allocated memory in bytes from the previous attempt.
• cpu: A Float? with the allocated number of CPUs from the previous attempt.
• container: A String? with the URI of the container used in the previous attempt.
• gpu: An Array[String]? with the GPU specifications from the previous attempt.
• fpga: An Array[String]? with the FPGA specifications from the previous attempt.
• disks: A Map[String, Int]? with the disk mount points and allocated space from the previous attempt.
• max_retries: An Int? with the maximum number of retry attempts from the previous attempt.

All fields are None on the first try.

Type Conversion

WDL has some limited facilities for converting a value of one type to another type. Some of these are explicitly provided by standard library functions, while others are implicit. When converting between types, it is best to be explicit whenever possible, even if an implicit conversion is allowed.

The execution engine is also responsible for converting (or "serializing") input values when constructing commands, as well as "deserializing" command outputs. For more information, see the Command Section and the more extensive Appendix on WDL Value Serialization and Deserialization.

Note that type conversion is non-destructive - the converted value can be considered to be a new value that copies whatever properties of the original value are supported by the target type. If the original value was assigned to a variable, then that variable remains unchanged after the type conversion. For example:

String path = "/path/to/file"
File file = path
String new_path = "~{path}_2"  # can still use `path` here

Primitive Conversion to String

Primitive types can always be converted to String using string interpolation. See Expression Placeholder Coercion for details.

version 1.3

workflow primitive_to_string {
  input {
    Int i = 5
  }

  output {
    String istring = "~{i}"
  }
}

{
  "primitive_to_string.i": 3
}

{
  "primitive_to_string.istring": "3"
}

Type Coercion

There are some pairs of WDL types for which there is an obvious, unambiguous conversion from one to the other. In these cases, WDL provides an automatic conversion (called "coercion") from one type to the other, such that a value of one type typically can be used anywhere the other type is expected.

For example, file paths are always represented as strings, making the conversion from String to File obvious and unambiguous.

version 1.3

workflow string_to_file {
  input {
    File infile
  }

  String path1 = "~{infile}"

  # valid - String coerces unambiguously to File
  File path2 = path1

  output {
    Boolean paths_equal = path2 == infile
  }
}

{
  "string_to_file.infile": "data/hello.txt"
}

{
  "string_to_file.paths_equal": true
}

Attempting to use a declaration that is both of the wrong type and for which there is no coercion to the correct type results in an error.

version 1.3

workflow coercion_fail {
  Array[String] strings = ["/foo/bar"]
  Boolean is_true1 = contains(strings, "/foo/bar")
  
  File foobar = "/foo/bar"
  # returns `true` - string interpolation creates a string from `foobar`
  Boolean is_true2 = contains(strings, "~{foobar}")
  # error - `foobar` is not of type `String` and is not coercible to `String`
  contains(strings, foobar)
}

{}

{}

{
  "fail": true
}

The table below lists all globally valid coercions. The "target" type is the type being coerced to (this is often called the "left-hand side" or "LHS" of the coercion) and the "source" type is the type being coerced from (the "right-hand side" or "RHS").

The read_lines function presents a special case in which the Array[String] value it returns may be immediately coerced into other Array[P] values, where P is a primitive type. See Appendix A for details and best practices.

Order of Precedence

During string interpolation, there are some operators for which it is possible to coerce the same arguments in multiple different ways. For such operators, it is necessary to define the order of precedence so that a single function prototype can be selected from among the available options for any given set of arguments.

The + operator is overloaded for both numeric addition and String concatenation. This can lead to the following kinds of situations:

String s = "1.0"
Float f = 2.0
String x = "~{s + f}"

There are two possible ways to evaluate the s + f expression:

1. Coerce s to Float and perform floating point addition, then coerce to String with the result being x = "3.0".
2. Coerce f to String and perform string concatenation with result being x = "1.02.0".

Similarly, the equality/inequality operators can be applied to any primitive values.

When applying +, =, or != to primitive operands (X, Y), the order of precedence is:

1. (Int, Int) or (Float, Float): perform numeric addition/comparison
2. (Int, Float): coerce Int to Float, then perform numeric addition/comparison
3. (String, String): perform string concatenation/comparison
4. (String, Y): coerce Y to String, then perform string concatenation/comparison
5. Others: coerce X and Y to String, then perform string concatenation/comparison

Examples:

# Evaluates to `"3.0"`: `1` is coerced to Float (`1.0`), then numeric addition
# is performed, and the result is converted to a string
String s1 = "~{1 + 2.0}"
# Evaluates to `"3.01"`: `1` is coerced to String, then concatenated with the 
# value of `s1`
String s2 = "~{s1 + 1}"
# Evaluates to `true`: `1` is coerced to Float (`1.0`), then numeric comparison 
# is performed
Boolean b1 = 1 == 1.0
# Evaluates to `true`: `true` is coerced to String, then string comparison is 
# performed
Boolean b2 = true == "true"
# Evaluates to `false`: `1` and `true` are both coerced to String, then string 
# comparison is performed
Boolean b3 = 1 == true

Coercion of Optional Types

A non-optional type T can always be coerced to an optional type T?, but the reverse is not true - coercion from T? to T is not allowed because the latter cannot accept None.

This constraint propagates into compound types. For example, an Array[T?] can contain both optional and non-optional elements. This facilitates the common idiom select_first([expr, default]), where expr is of type T? and default is of type T, for converting an optional type to a non-optional type. However, an Array[T?] could not be passed to the sep function, which requires an Array[T].

There are two exceptions where coercion from T? to T is allowed:

• String concatenation in expression placeholders
• Equality and inequality comparisons

Struct/Object Coercion from Map

Structs and Objects can be coerced from map literals, but beware the difference between Map keys (expressions) and Struct/Object member names.

version 1.3

struct Words {
  Int a
  Int b
  Int c
}

workflow map_to_struct {
  String a = "beware"
  String b = "key"
  String c = "lookup"

  output {
    # What are the keys to this Struct?
    Words literal_syntax = Words {
      a: 10,
      b: 11,
      c: 12
    }

    # What are the keys to this Struct?
    Words map_coercion = {
      "a": 10,
      "b": 11,
      "c": 12
    }
  }
}

{}

{
  "map_to_struct.literal_syntax": {
    "a": 10,
    "b": 11,
    "c": 12
  },
  "map_to_struct.map_coercion": {
    "a": 10,
    "b": 11,
    "c": 12
  }
}

• If a Struct (or Object) declaration is initialized using the struct-literal (or object-literal) syntax Words literal_syntax = Words { a: ... then the keys will be "a", "b" and "c".
• If a Struct (or Object) declaration is initialized using the map-literal syntax Words map_coercion = { a: ... then the keys are expressions, and thus a will be a variable reference to the previously defined String a = "beware".

Struct-to-Struct Coercion

Two Struct types are considered compatible when the following are true:

1. They have the same number of members.
2. Their members' names are identical.
3. The type of each member in the source struct is coercible to the type of the member with the same name in the target struct.

version 1.3

struct A {
  String s
}

struct B {
  A a_struct
  Int i
}

struct C {
  String s
}

struct D {
  C a_struct
  Int i
}

workflow struct_to_struct {
  B my_b = B {
    a_struct: A { s: 'hello' },
    i: 10
  }
  # We can coerce `my_b` from type `B` to type `D` because `B` and `D`
  # have members with the same names and compatible types. Type `A` can
  # be coerced to type `C` because they also have members with the same
  # names and compatible types.
  
  output {
    D my_d = my_b
  }
}

{}

{
  "struct_to_struct.my_d": {
    "a_struct": { 
      "s": "hello"
    },
    "i": 10
  }
}

🗑 Limited Exceptions

Implementers may choose to allow limited exceptions to the above rules, with the understanding that workflows depending on these exceptions may not be portable. These exceptions are provided for backward-compatibility, are considered deprecated, and will be removed in a future version of WDL.

• Float to Int, when the coercion can be performed with no loss of precision, e.g. 1.0 -> 1.
• String to Int/Float, when the coercion can be performed with no loss of precision.
• X? may be coerced to X, and an error is raised if the value is undefined.
• Array[X] to Array[X]+, when the array is non-empty (an error is raised otherwise).
• Map[W, X] to Array[Pair[Y, Z]], in the case where W is coercible to Y and X is coercible to Z.
• Array[Pair[W, X]] to Map[Y, Z], in the case where W is coercible to Y and X is coercible to Z.
• Map to Object, in the case of Map[String, X].
• Map to struct, in the case of Map[String, X] where all members of the struct have type X.
• Object to Map[String, X], in the case where all object values are of (or are coercible to) the same type.

Declarations

A declaration reserves a name that can be referenced anywhere in the scope where it is declared. A declaration has a type, a name, and an optional initialization. Each declaration must be unique within its scope, may not collide with a reserved WDL keyword (e.g., workflow, or input), and may not have the same name as a visible struct or enum type.

A task or workflow may declare input parameters within its input section and output parameters within its output section. If a non-optional input declaration does not have an initialization, it is considered a "required" parameter, and its value must be provided by the user before the workflow or task may be run. Declarations may also appear in the body of a task or workflow. All non-input declarations must be initialized.

version 1.3

workflow declarations {
  input {
    # these "unbound" declarations are only allowed in the input section
    File? x  # optional - defaults to None
    Map[String, String] m  # required
    # this is a "bound" declaration
    String y = "abc"  
  }

  Int i = 1 + 2  # Private declarations must be bound

  output {
    Float pi = i + .14  # output declarations must also be bound
  }
}

{
  "declarations.m": {"a": "b"}
}

{
  "declarations.pi": 3.14
}

A declaration may be initialized with an expression, which includes the ability to refer to elements that are outputs of tasks.

version 1.3

task greet {
  input {
    String name
  }
  
  command <<<
    printf "Hello ~{name}"
  >>>

  output {
    String greeting = read_string(stdout())
  }
}

task count_lines {
  input {
    Array[String] array
  }

  command <<<
    wc -l < ~{write_lines(array)}
  >>>
  
  output {
    Int line_count = read_int(stdout())
  }
}

workflow task_outputs {
  call greet as x {
    name="John"
  }
  
  call greet as y {
    name="Sarah"
  }

  Array[String] greetings = [x.greeting, y.greeting]
  call count_lines {
    array=greetings
  }

  output {
    Int num_greetings = count_lines.line_count
  }
}

{}

{
  "task_outputs.num_greetings": 2
}

In this example, greetings is undefined until both call greet as x and call greet as y have successfully completed, at which point it is assigned the result of evaluating its expression. If either of the two tasks fail, the workflow would also fail and greetings would never be initialized.

It must be possible to organize all of the statements within a scope into a directed acyclic graph (DAG); thus, circular references between declarations are not allowed. The following example would result in an error due to the presence of a circular reference.

version 1.3

workflow circular {
  Int i = j + 1
  Int j = i - 2
}

{}

{}

{
  "fail": true
}

Expressions

An expression is a compound statement that consists of literal values, identifiers (references to declarations or call outputs), built-in operators (e.g., + or >=), and calls to standard library functions.

A "literal" expression is one that consists only of a literal value. For example, "foo" is a literal String expression and [1, 2, 3] is a literal Array[Int] expression.

A "simple" expression is one that can be evaluated unambiguously without any knowledge of the runtime context. Literal expressions, operations on literals (e.g., 1 + 2), and function calls with literal arguments (excluding any functions that read or create Files) are all simple expressions. A simple expression cannot refer to any declarations (i.e., it cannot contain identifiers). An execution engine may choose to replace a simple expression with its literal value during static analysis.

version 1.3

task expressions {
  input {
    Int x
  }

  command <<<
  printf "hello" > hello.txt
  >>>

  output {
    # simple expressions
    Float f = 1 + 2.2
    Boolean b = if 1 > 2 then true else false
    Map[String, Int] m = as_map(zip(["a", "b", "c"], [1, 2, 3]))

    # non-simple expressions
    Int i = x + 3  # requires knowing the value of x
    # requires reading a file that might only exist at runtime
    String s = read_string("hello.txt")
  }
}

{
  "expressions.x": 5
}

{
  "expressions.f": 3.2,
  "expressions.b": false,
  "expressions.m": {
    "a": 1,
    "b": 2,
    "c": 3
  },
  "expressions.i": 8,
  "expressions.s": "hello"
}

Built-in Operators

WDL provides the standard unary and binary mathematical and logical operators. The following tables list the valid operand and result type combinations for each operator. Using an operator with unsupported types results in an error.

In operations on mismatched numeric types (e.g., Int + Float), the Int is first is coerced to Float, and the result type is Float. This may result in loss of precision, for example if the Int is too large to be represented exactly by a Float. A Float can be converted to Int with the ceil, round, or floor functions.

Unary Operators

Binary Operators on Primitive Types

Boolean operator evaluation is minimal (or "short-circuiting"), meaning that:

1. For A && B, if A evalutes to false then B is not evaluated
2. For A || B, if A evaluates to true then B is not evaluated.

WDL Strings are compared by the unicode values of their corresponding characters. Character a is less than character b if it has a lower unicode value.

File and Directory values are canonicalized when the value is created. Two File or Directory values that refer to the same underlying resource are considered equal, even if they were initialized from different string representations. For example, /home/user/file.txt and /home/user/../user/file.txt refer to the same file and compare as equal. Similarly, for Directory values, trailing slashes are ignored when determining equality (e.g., /home/user/dir and /home/user/dir/ are equal). Equality relationships between File and Directory values are preserved throughout workflow execution, including before and after task input localization.

When comparing a File or Directory to a String, the String is first coerced to File or Directory (and thus canonicalized) before the comparison is performed.

version 1.3

task check_equality {
  input {
    File file_a
    File file_b
    Directory dir_a
    Directory dir_b
  }

  command <<<
  # The execution engine localizes equal files once
  # so file_a and file_b will have the same path
  if [ "~{file_a}" = "~{file_b}" ]; then
    echo "true" > files_equal.txt
  else
    echo "false" > files_equal.txt
  fi

  if [ "~{dir_a}" = "~{dir_b}" ]; then
    echo "true" > dirs_equal.txt
  else
    echo "false" > dirs_equal.txt
  fi
  >>>

  output {
    Boolean task_files_equal = read_boolean("files_equal.txt")
    Boolean task_dirs_equal = read_boolean("dirs_equal.txt")
  }
}

workflow file_directory_equality {
  input {
    File file_a
    File file_b
    Directory dir_a
    Directory dir_b
  }

  # After canonicalization, these compare as equal
  Boolean files_eq = file_a == file_b
  Boolean dirs_eq = dir_a == dir_b

  call check_equality {
    file_a = file_a,
    file_b = file_b,
    dir_a = dir_a,
    dir_b = dir_b
  }

  output {
    Boolean workflow_files_equal = files_eq
    Boolean workflow_dirs_equal = dirs_eq
    Boolean task_files_equal = check_equality.task_files_equal
    Boolean task_dirs_equal = check_equality.task_dirs_equal
  }
}

{
  "file_directory_equality.file_a": "data/hello.txt",
  "file_directory_equality.file_b": "data/../data/hello.txt",
  "file_directory_equality.dir_a": "data/testdir/",
  "file_directory_equality.dir_b": "data/testdir"
}

{
  "file_directory_equality.workflow_files_equal": true,
  "file_directory_equality.workflow_dirs_equal": true,
  "file_directory_equality.task_files_equal": true,
  "file_directory_equality.task_dirs_equal": true
}

In this example, file_a and file_b use different string representations (tests/data/hello.txt vs tests/data/../data/hello.txt) but both canonicalize to the same path and compare as equal at workflow scope. When passed to the task, the execution engine localizes the file once, and both file_a and file_b in the task reference the same localized path. Similarly, dir_a includes a trailing slash while dir_b does not, but they canonicalize to the same directory and are localized once.

Except for String + File, all concatenations between String and non-String types are deprecated and will be removed in WDL 2.0. The same effect can be achieved using string interpolation.

Equality of Compound Types

In general, two compound values are equal if-and-only-if all of the following are true:

1. They are of the same type.
2. They are the same length.
3. All of their contained elements are equal.

Since Arrays and Maps are ordered, the order of their elements are also compared. For example:

version 1.3

workflow array_map_equality {
  output {
    # arrays and maps with the same elements in the same order are equal
    Boolean is_true1 = [1, 2, 3] == [1, 2, 3]
    Boolean is_true2 = {"a": 1, "b": 2} == {"a": 1, "b": 2}

    # arrays and maps with the same elements in different orders are not equal
    Boolean is_false1 = [1, 2, 3] == [2, 1, 3]
    Boolean is_false2 = {"a": 1, "b": 2} == {"b": 2, "a": 1}
  }
}

{}

{
  "array_map_equality.is_true1": true,
  "array_map_equality.is_true2": true,
  "array_map_equality.is_false1": false,
  "array_map_equality.is_false2": false
}

Type coercion can be employed to compare values of different but compatible types.

version 1.3

workflow compare_coerced {
  Array[Int] i = [1, 2, 3]
  Array[Float] f1 = i
  Array[Float] f2 = [1.0, 2.0, 3.0]

  output {
    # Ints are automatically coerced to Floats for comparison
    Boolean is_true = f1 == f2
  }
}

{}

{
  "compare_coerced.is_true": true
}

Equality and Inequality Comparison of Optional Types

The equality and inequality operators are exceptions to the general rules on coercion of optional types. Either or both operands of an equality or inequality comparison can be optional, considering that None is equal to itself but no other value.

version 1.3

workflow compare_optionals {
  Int i = 1
  Int? j = 1
  Int? k = None

  output {
    # equal values of the same type are equal even if one is optional
    Boolean is_true1 = i == j
    # k is undefined (None), and so is only equal to None
    Boolean is_true2 = k == None
    # these comparisons are valid and evaluate to false
    Boolean is_false1 = i == k
    Boolean is_false2 = j == k
  }
}

{}

{
  "compare_optionals.is_true1": true,
  "compare_optionals.is_true2": true,
  "compare_optionals.is_false1": false,
  "compare_optionals.is_false2": false
}

Operator Precedence Table

Member Access

The syntax x.y refers to member access. The left-hand side x is evaluated as an expression and must be one of the following:

• A Struct or Object value, where y is a member name
• A call in a workflow, where y is an output name (a call can be thought of as a struct where the members are the outputs of the called task)
• A type name reference to an enum, where y is a choice name

version 1.3

struct MyType {
  String s
}

task foo {
  command <<<
  printf "bar"
  >>>

  output {
    String bar = read_string(stdout())
  }
}

workflow member_access {
  # task foo has an output y
  call foo
  MyType my = MyType { s: "hello" }

  output {
    String bar = foo.bar
    String hello = my.s
  }
}

{}

{
  "member_access.bar": "bar",
  "member_access.hello": "hello"
}

Access to elements of compound members can be chained into a single expression.

version 1.3

struct Experiment {
  String id
  Array[String] variables
  Map[String, String] data
}

workflow nested_access {
  input {
    Array[Experiment]+ my_experiments
  }

  Experiment first_experiment = my_experiments[0]
  
  output {
    # these are equivalent
    String first_var = first_experiment.variables[0]
    String first_var_from_first_experiment = my_experiments[0].variables[0]

    # these are equivalent
    String subject_name = first_experiment.data["name"]
    String subject_name_from_first_experiment = my_experiments[0].data["name"]
  }
}

{
  "nested_access.my_experiments": [
    {
      "id": "mouse_size",
      "variables": ["name", "height"],
      "data": {
        "name": "Pinky",
        "height": "7"
      }
    },
    {
      "id": "pig_weight",
      "variables": ["name", "weight"],
      "data": {
        "name": "Porky",
        "weight": "1000"
      }
    }
  ]
}

{
  "nested_access.first_var": "name",
  "nested_access.first_var_from_first_experiment": "name",
  "nested_access.subject_name": "Pinky",
  "nested_access.subject_name_from_first_experiment": "Pinky"
}

Attempting to access a non-existent member of an object, struct, or call results in an error.

version 1.3

import "member_access.wdl"

workflow illegal_access {
  input {
    MyStruct my
  }

  Int i = my.x  # error: field 'x' does not exist in MyStruct
  
  call foo

  output {
    String baz = foo.baz  # error: 'baz' is not an output field of task 'foo'    
  }
}

{}

{}

{
  "fail": true
}

Ternary operator (if-then-else)

This operator takes three arguments: a condition expression, an if-true expression, and an if-false expression. The condition is always evaluated. If the condition is true then the if-true value is evaluated and returned. If the condition is false, the if-false expression is evaluated and returned. The if-true and if-false expressions must return values of the same type, such that the value of the if-then-else is the same regardless of which side is evaluated.

version 1.3

task mem {
  input {
    Array[String] array
  }

  Int array_length = length(array)
  # choose how much memory to use for a task
  String memory = if array_length > 100 then "2GB" else "1GB"

  command <<<
  >>>

  requirements {
    memory: memory
  }
}

workflow ternary {
  input {
    Boolean morning
  }

  call mem { array = ["x", "y", "z"] }

  output {
    # Choose whether to say "good morning" or "good afternoon"
    String greeting = "good ~{if morning then "morning" else "afternoon"}"
  }
}

{
  "ternary.morning": true
}

{
  "ternary.greeting": "good morning"
}

Function Calls

WDL provides a standard library of functions. These functions can be called using the syntax func(p1, p2, ...), where func is the function name and p1 and p2 are parameters to the function.

Expression Placeholders and String Interpolation

Any WDL string expression may contain one or more "placeholders" of the form ~{*expression*}, each of which contains a single expression. Placeholders of the form ${*expression*} may also be used interchangably, but their use is discouraged for reasons discussed in the command section and may be deprecated in a future version of the specification.

When a string expression is evaluated, its placeholders are evaluated first, and their values are then substituted for the placeholders in the containing string.

version 1.3

workflow placeholders {
  input {
    Int i = 3
    String start
    String end
    String instr
  }

  output {
    String s = "~{1 + i}"
    String cmd = "grep '~{start}...~{end}' ~{instr}"
  }
}

{
  "placeholders.start": "h",
  "placeholders.end": "o",
  "placeholders.instr": "hello"
}

{
  "placeholders.cmd": "grep 'h...o' hello",
  "placeholders.s": "4"
}

In the above example, command would be parsed and evaluated as:

1. grep ': literal string
2. ~{start}: identifier expression, replaced with the value of start
3. ...: literal string
4. ~{end}: identifier expression, replaced with the value of end
5. ' : literal string
6. ~{input}: identifier expression, replaced with the value of input
7. Final string value created by concatenating 1-6

Placeholders may contain other placeholders to any level of nesting, and placeholders are evaluated recursively in a depth-first manner. Placeholder expressions are anonymous, i.e., they have no name and thus cannot be referenced by other expressions, but they can reference declarations and call outputs.

version 1.3

workflow nested_placeholders {
  input {
    Int i
    Boolean b
  }

  output {
    String s = "~{if b then '~{1 + i}' else '0'}"
  }
}

{
  "nested_placeholders.i": 3,
  "nested_placeholders.b": true
}

{
  "nested_placeholders.s": "4"
}

Placeholders are evaluated in multi-line strings exactly the same as in regular strings. Common leading whitespace is stripped from a multi-line string before placeholder expressions are evaluated.

version 1.3

workflow multiline_string_placeholders {
    String spaces = "  "
    String name = "Henry"
    String company = "Acme"

  output {
    # This string evaluates to: "  Hello Henry,\n  Welcome to Acme!"
    # The string still has spaces because the placeholders are evaluated after removing the 
    # common leading whitespace.
    String multi_line = <<<
      ~{spaces}Hello ~{name},
      ~{spaces}Welcome to ~{company}!
    >>>
  }
}

{}

{
  "multiline_string_placeholders.multi_line": "  Hello Henry,\n  Welcome to Acme!"
}

Expression Placeholder Coercion

The result of evaluating an expression in a placeholder must ultimately be converted to a string in order to take the place of the placeholder in the command script. This is immediately possible for WDL primitive types due to automatic conversions ("coercions") that occur only within the context of string interpolation:

• String is substituted directly.
• File is substituted as if it were a String.
• Directory is substituted as if it were a String. The resulting string does not have a trailing slash.
• Int is formatted without leading zeros (unless the value is 0), and with a leading - if the value is negative.
• Float is printed in the style [-]ddd.dddddd, with 6 digits after the decimal point.
• Boolean is converted to the "stringified" version of its literal value, i.e., true or false.

Compound types cannot be implicitly converted to Strings. To convert an Array to a String, use the sep function: ~{sep(",", str_array)}. See the guide on WDL value serialization for more details and examples.

If an expression within a placeholder evaluates to None, and either causes the entire placeholder to evaluate to None or causes an error, then the placeholder is replaced by the empty string.

version 1.3

workflow placeholder_coercion {
  input {
    File x
  }
  String x_as_str = x
  Int? i = None

  output {
    Boolean is_true1 = "~{"abc"}" == "abc"
    Boolean is_true2 = "~{x}" == x_as_str
    Boolean is_true3 = "~{5}" == "5"
    Boolean is_true4 = "~{3.141}" == "3.141000"
    Boolean is_true5 = "~{3.141 * 1E-10}" == "0.000000"
    Boolean is_true6 = "~{3.141 * 1E10}" == "31410000000.000000"
    Boolean is_true7 = "~{i}" == ""
  }
}

{
  "placeholder_coercion.x": "data/hello.txt"
}

{
  "placeholder_coercion.is_true1": true,
  "placeholder_coercion.is_true2": true,
  "placeholder_coercion.is_true3": true,
  "placeholder_coercion.is_true4": true,
  "placeholder_coercion.is_true5": true,
  "placeholder_coercion.is_true6": true,
  "placeholder_coercion.is_true7": true
}

version 1.3

workflow placeholder_none {
  output {
    String? foo = None
    # The expression in this string results in an error (calling `select_first` on an array 
    # containing no non-`None` values) and so the placeholder evaluates to the empty string and 
    # `s` evalutes to: "Foo is "
    String s = "Foo is ~{select_first([foo])}"
  }
}

{}

{
  "placeholder_none.foo": null,
  "placeholder_none.s": "Foo is "
}

Concatenation of Optional Values

Within expression placeholders the string concatenation operator (+) gains the ability to operate on optional values. When applied to two non-optional operands, the result is a non-optional String. However, if either operand has an optional type, then the concatenation has type String?, and the runtime result is None if either operand is None (which is then replaced with the empty string).

version 1.3

workflow concat_optional {
  input {
    String salutation = "hello"
    String? name1
    String? name2 = "Fred"
  }

  output {
    # since name1 is undefined, the evaluation of the expression in the placeholder fails, and the
    # value of greeting1 = "nice to meet you!"
    String greeting1 = "~{salutation + ' ' + name1 + ' '}nice to meet you!"

    # since name2 is defined, the evaluation of the expression in the placeholder succeeds, and the
    # value of greeting2 = "hello Fred, nice to meet you!"
    String greeting2 = "~{salutation + ' ' + name2 + ', '}nice to meet you!"
  }
}

{}

{
  "concat_optional.greeting1": "nice to meet you!",
  "concat_optional.greeting2": "hello Fred, nice to meet you!"
}

Among other uses, concatenation of optionals can be used to facilitate the formulation of command-line flags.

version 1.3

task flags {
  input {
    File infile
    String pattern
    Int? max_matches
  }

  command <<<
    # If `max_matches` is `None`, the command
    # grep -m ~{max_matches} ~{pattern} ~{infile}
    # would evaluate to
    # 'grep -m <pattern> <infile>', which would be an error.

    # Instead, make both the flag and the value conditional on `max_matches`
    # being defined.
    grep ~{"-m " + max_matches} ~{pattern} ~{infile} | wc -l
  >>>

  output {
    Int num_matches = read_int(stdout())
  }
}

{
  "flags.infile": "data/greetings.txt",
  "flags.pattern": "world"
}

{
  "flags.num_matches": 2
}

🗑 Expression Placeholder Options

Expression placeholder options are option="value" pairs that precede the expression within an expression placeholder and customize the interpolation of the WDL value into the containing string expression.

There are three options available. An expression placeholder may have at most one option.

• sep: convert an array to a string using a delimiter; e.g., ~{sep=", " array_value}.
• true and false: substitute a value depending on whether a boolean expression is true or false; e.g., ~{true="--yes" false="--no" boolean_value}.
• default: substitute a default value for an undefined expression; e.g., ~{default="foo" optional_value}.

Expression placeholder options are deprecated and will be removed in WDL 2.0. In the sections below, each type of placeholder option is described in more detail, including how to replicate its behavior using future-proof syntax.

sep

sep is interpreted as the separator string used to join together the elements of an array. sep is only valid if the expression evaluates to an Array.

For example, given a declaration Array[Int] numbers = [1, 2, 3], the expression "python script.py ~{sep=',' numbers}" yields the value: python script.py 1,2,3.

Alternatively, if the command were "python script.py ~{sep=' ' numbers}" it would evaluate to: python script.py 1 2 3.

Requirements:

• sep MUST accept only a string as its value
• sep is only allowed if the type of the expression is Array[P]

The sep option can be replaced with a call to the sep function:

version 1.3

workflow sep_option_to_function {
  input {
    Array[String] str_array
    Array[Int] int_array
  }
  
  output {
    Boolean is_true1 = "~{sep(' ', str_array)}" == "~{sep=' ' str_array}"
    Boolean is_true2 = "~{sep(',', quote(int_array))}" == "~{sep=',' quote(int_array)}"
  }
}

{
  "sep_option_to_function.str_array": ["A", "B", "C"],
  "sep_option_to_function.int_array": [1, 2, 3]
}

{
  "sep_option_to_function.is_true1": true,
  "sep_option_to_function.is_true2": true
}

{
  "tags": ["deprecated"]
}

true and false

true and false convert an expression that evaluates to a Boolean into a string literal when the result is true or false, respectively.

For example, "~{true='--enable-foo' false='--disable-foo' allow_foo}" evaluates the expression allow_foo as an identifier and, depending on its value, replaces the entire expression placeholder with either --enable-foo or --disable-foo.

Both true and false cases are required. If one case should insert no value then an empty string literal is used, e.g. "~{true='--enable-foo' false='' allow_foo}".

Requirements:

• true and false values MUST be string literals.
• true and false are only allowed if the type of the expression is Boolean
• Both true and false cases are required.

The true and false options can be replaced with the use of an if-then-else expression:

version 1.3

task true_false_ternary {
  input {
    String message
    Boolean newline
  }

  command <<<
    # these two commands have the same result
    printf "~{message}~{true="\n" false="" newline}" > result1
    printf "~{message}~{if newline then "\n" else ""}" > result2
  >>>

  output {
    Boolean is_true = read_string("result1") == read_string("result2")
  }
}

{
  "true_false_ternary.message": "hello world",
  "true_false_ternary.newline": false
}

{
  "true_false_ternary.is_true": true
}

{
  "tags": ["deprecated"]
}

default

The default option specifies a value to substitute for an optional-typed expression with an undefined value.

Requirements:

• The type of the default value must match the type of the expression
• The type of the expression must be optional, i.e., it must have a ? postfix quantifier

The default option can be replaced in several ways - most commonly with an if-then-else expression or with a call to the select_first function.

version 1.3

task default_option {
  input {
    String? s
  }

  command <<<
    printf ~{default="foobar" s} > result1
    printf ~{if defined(s) then "~{select_first([s])}" else "foobar"} > result2
    printf ~{select_first([s, "foobar"])} > result3
  >>>
  
  output {
    Boolean is_true1 = read_string("result1") == read_string("result2")
    Boolean is_true2 = read_string("result1") == read_string("result3")
  }
}

{}

{
  "default_option.is_true1": true,
  "default_option.is_true2": true
}

Static Analysis and Dynamic Evaluation

As with any strongly typed programming language, WDL is processed in two distinct phases by the implementation: static analysis and dynamic evaluation.

• Static analysis is the process of parsing the WDL document and performing type inference - that is, making sure the WDL is syntactically correct, and that there is compatibility between the expected and actual types of all declarations, expressions, and calls.
• Dynamic evaluation is the process of evaluating all WDL expressions and calls at runtime, when all of the user-specified inputs are available.

An implementation should raise an error as early as possible when processing a WDL document. For example, in the following task the sub function is being called with an Int argument rather than a String. This function call cannot be evaluated successfully, so the implementation should raise an error during static analysis, rather than waiting until runtime.

task bad_sub {
  Int i = 111222333
  String s = sub(i, "2", "4")
}

On the other hand, in the following example all of the types are compatible, but if the hello.txt file does not exist when the File value is created (when evaluating the declaration File f = "hello.txt"), then an error will be raised.

task missing_file {
  File f = "hello.txt"

  command <<<
  printf "~{sep(","), read_lines(f)}"
  >>>
}

WDL Documents

A WDL document is a file that contains valid WDL definitions.

A WDL document must contain:

• A version statement on the first non-comment line of the file.
• At least one struct definition, task definition, workflow definition.

A WDL document may contain any combination of the following:

• Any number of import statements.
• Any number of struct definitions.
• Any number of task definitions.
• A maximum of one workflow definition.

To execute a WDL workflow, the user must provide the execution engine with the location of a "primary" WDL file (which may import additional files as needed) and any input values needed to satisfy all required task and workflow input parameters, using a standard input JSON file or some other execution engine-specific mechanism.

If a workflow appears in the primary WDL file, it is called the "top-level" workflow, and any workflows it calls via imports are "subworkflows". Typically, it is an error for the primary WDL file to not contain a workflow; however, an execution engine may choose to support executing individual tasks.

Versioning

There are multiple versions of the WDL specification. Every WDL document must include a version statement to specify which version (major and minor) of the specification it adheres to. From draft-3 forward, the first non-comment statement of all WDL files must be a version statement. For example:

version 1.3

or

#Licence header

version 1.3

A WDL file that does not have a version statement must be treated as draft-2.

Because patches to the WDL specification do not change any functionality, all revisions that carry the same major and minor version numbers are considered equivalent. For example, version 1.3 is used for a WDL document that adheres to the 1.3.x specification, regardless of the value of x.

Struct Definition

A Struct type is a user-defined data type. Structs enable the creation of compound data types that bundle together related attributes in a more natural way than is possible using the general-purpose compound types like Pair or Map. Once defined, a Struct type can be used as the type of a declaration like any other data type.

Struct definitions are top-level WDL elements, meaning they exist at the same level as import, task, and workflow definitions. A struct cannot be defined within a task or workflow body.

A struct is defined using the struct keyword, followed by a name that is unique within the WDL document, and a body containing the member declarations. A struct member may be of any type, including compound types and even other Struct types. A struct member may be optional. Declarations in a struct body differ from those in a task or workflow in that struct members cannot have default initializers.

A struct definition may include a meta section with metadata about the struct, and a parameter_meta section with metadata about any of the struct's members. These sections have identical sematics to task and workflow meta and parameter_meta sections. Any key in the parameter_meta section must correspond to a member of the struct.

version 1.3

struct Name {
  String first
  String last
}

struct Income {
  Float amount
  String period
  String? currency
}

struct Person {
  Name name
  Int age
  Income? income
  Map[String, File] assay_data
  
  meta {
    description: "Encapsulates data about a person"
  }

  parameter_meta {
    name: "The person's name"
    age: "The person's age"
    income: "How much the person makes (optional)"
    assay_data: "Mapping of assay name to the file that contains the assay data"
  }
}

task greet_person {
  input {
    Person person
  }

  Array[Pair[String, File]] assay_array = as_pairs(person.assay_data)

  command <<<
  printf "Hello ~{person.name.first}! You have ~{length(assay_array)} test result(s) available.\n"

  if ~{defined(person.income)}; then
    if [ "$(printf "%.0f" ~{select_first([person.income]).amount})" -gt 1000 ]; then
      currency="~{select_first([select_first([person.income]).currency, "USD"])}"
      printf "Please transfer $currency 500 to continue"
    fi
  fi
  >>>

  output {
    String message = read_string(stdout())
  }
}

{
  "greet_person.person": {
    "name": {
      "first": "Richard",
      "last": "Rich"
    },
    "age": 14,
    "income": {
      "amount": 1000000,
      "period": "annually"
    },
    "assay_data": {
      "wealthitis": "data/hello.txt"
    }
  }
}

{
  "greet_person.message": "Hello Richard! You have 1 test result(s) available.\nPlease transfer USD 500 to continue"
}

An invalid struct:

struct Invalid {
  String myString = "Cannot do this"
  Int myInt
}

Enum Definition

An enum is an enumerated type. Enums enable the creation of types that represent closed sets of alternatives (called "choices") that are semantically valid in a specific context. Once defined, an enum type can be used as the type of a declaration like any other type. However, new choices of an enum cannot be created. Instead, a declaration having an enum type must be assigned one of the choices created as part of the enum's definition.

An enum definition is a top-level WDL element, meaning it is defined at the same level as tasks, workflows, and structs, and it cannot be defined within a task or workflow body. An enum is defined using the enum keyword, followed by a name that is unique within the WDL document, and a body containing a comma-delimited list of choices in braces ({}). Choice names within an enum must be unique, and enum names must not conflict with struct names or other enum names.

enum Color {
  Red,
  Blue,
  Green
}

An enum can be thought of as a closed type with a fixed set of instances. The enum keyword creates both a type (that can be used in declarations) and a global namespace containing the enum's choices. For example, Color.Red refers to a specific instance of the Color enum type.

Unlike structs, it is not possible to create new instances of an enum outside of the enum's definition. An enum value can only be one of the choices defined in the enum's declaration.

Enum Usage

An enum's choices are accessed using a . to separate the choice name from the enum's identifier.

A declaration with an enum type can only be initialized by referencing a choice directly or by assigning it to the value of another declaration of the same enum type.

Two enum values can be tested for equality (i.e., using == or !=). To be equal, two enum values must be the same choice of the same enum type. For example, Color.Red == Color.Red evaluates to true, while Color.Red == Color.Blue evaluates to false. A comparison of two enum values of different enum types is considered a type mismatch error. Enum values are not ordered, so they cannot be compared with ordinal operators (i.e., using >, >=, <, <=).

When an enum value is serialized using string interpolation, it is serialized to its choice name. To extract the inner value of an enum choice, use the value() standard library function.

An enum cannot be coerced to or from any other type. However, an enum value can be serialized to/deserialized from JSON and can be used in command sections.

version 1.3

enum Pet {
  Cat,
  Mouse,
  Bird
}

enum ComputerDevice {
  Mouse,
  Keyboard,
  Monitor
}

task compare_enum_types {
  input {
    Pet? pet
  }

  Pet my_pet = select_first([pet, Pet.Mouse])

  command <<<
    echo "I have a pet ~{my_pet}"
  >>>

  output {
    Boolean different_types = Pet.Mouse != ComputerDevice.Mouse
  }
}

Enum Serialization and Deserialization

Enum values are serialized and deserialized differently depending on the context.

JSON Input and Output for Enums

When an enum value appears in JSON input or output files, it is represented by its choice name (not its inner value). The choice name is specified as a string without the enum type prefix.

For example, given this enum:

enum Color {
  Red = "#FF0000",
  Green = "#00FF00",
  Blue = "#0000FF"
}

workflow example {
  input {
    Color favorite_color
  }

  output {
    Color result = favorite_color
  }
}

Input JSON uses the choice name:

{
  "example.favorite_color": "Red"
}

Output JSON also uses the choice name:

{
  "example.result": "Red"
}

The execution engine validates that the provided string matches one of the enum's choice names. If an invalid choice name is provided, the execution engine must raise an error during input validation.

Command Section Serialization of Enums

When an enum value is used in a command section with string interpolation, it is serialized to its choice name (not the inner value). To access the inner value, use the value() function.

For example:

enum VerbosityFlag {
  Quiet = "",
  Info = "-v",
  Debug = "-vv",
  Trace = "-vvv"
}

task run_tool {
  input {
    VerbosityFlag verbosity = VerbosityFlag.Info
  }

  command <<<
  echo "Using verbosity level: ~{verbosity}"
  my_tool ~{value(verbosity)} input.txt
  >>>
}

When verbosity is VerbosityFlag.Info, the command becomes:

Using verbosity level: Info
my_tool -v input.txt

This demonstrates that ~{verbosity} produces the choice name "Info", while ~{value(verbosity)} produces the inner value "-v".

Import Statements

Although a WDL workflow and the task(s) it calls may be defined completely within a single WDL document, splitting it into multiple documents can be beneficial in terms of modularity and code resuse. Furthermore, complex workflows that consist of multiple subworkflows must be defined in multiple documents because each document is only allowed to contain at most one workflow.

The import statement is the basis for modularity in WDL. A WDL document may have any number of import statements, each of which references another WDL document and allows access to that document's top-level members (tasks, workflows, and structs).

The import statement specifies a WDL document source as a string literal, which is interpreted as a URI. The execution engine is responsible for resolving each import URI and retrieving the contents of the WDL document. The contents of the document in each URI must be a WDL document with the same major version and a minor version less than or equal to the minor version of the importing document.

Each imported WDL document must be assigned a unique namespace that is used to refer to its members. By default, the namespace of an imported WDL document is the filename of the imported WDL, minus the .wdl extension. A namespace can be assigned explicitly using the as <identifier> syntax. The tasks and workflows imported from a WDL file are only accessible through the assigned namespace - see Fully Qualified Names & Namespaced Identifiers for details.

import "http://example.com/lib/analysis_tasks" as analysis
import "http://example.com/lib/stdlib.wdl"

workflow wf {
  input {
    File bam_file
  }

  # file_size is from "http://example.com/lib/stdlib"
  call stdlib.file_size {
    file=bam_file
  }
  
  call analysis.my_analysis_task {
    size=file_size.bytes, file=bam_file
  }
}

Import URIs

A document is imported using it's URI, which uniquely describes its local or network-accessible location. The execution engine must at least support the following protocols for import URIs:

• http://
• https://
• 🗑 file:// - Using the file:// protocol for local imports can be problematic. Its use is deprecated and will be removed in WDL 2.0.

In the event that there is no protocol specified, the import is resolved relative to the location of the current document. In the primary WDL document, a protocol-less import is relative to the folder that contains the primary WDL file. If a protocol-less import starts with / it is interpreted as relative to the root of the file system that contains the primary WDL file.

Some examples of correct import resolution:

Importing and Aliasing Structs