WDL Specification v1.2.1

This is a patch release to the WDL 1.2 specification.

What's Changed

• Clarified that task.return_code is only available in the output section, where it has type Int rather than Int? (#742).
• Updates the compliance suite to use spectool (#752).
• Formalize replacement string syntax for sub() function to specify backreference support (\1 through \9) (#749).
• Clarify File and Directory path canonicalization, validation, and equality semantics. Clarify when Files and Directorys must exist (at declaration evaluation time, not access time). Add Directory comparison operators to binary operators table (#748).
• Clarify that File values cannot refer to directories and Directory values cannot refer to files; attempting to assign the wrong type of path is an error (#748).
• Update join_paths function: change return type from File to String (since the result can be either a file or directory path), and change first argument from File to Directory for the first two overloads (#748).
• Fix change_extension_task.wdl example to use string interpolation when passing File to sub() function (#747).
• Clarified that when a Directory is converted to a String, the resulting string does not have a trailing slash (#745).
• Clarified symlink handling behavior in the glob function (#744).
• Clarified the restriction on multi-level optionals in the "Optional Types" section (#743).
• Clarified that relative paths in File and Directory declarations are resolved relative to the WDL document's parent directory outside the output section, and relative to the task's execution directory inside the output section. Also clarified that optional files evaluate to None in both contexts if the path does not exist (#735).
• Clarify that disks mount points are ephemeral and should not already exist.
• Deprecate the use of relative path literals in input and private variable declarations.
• Include fixes to examples introduced in v1.1.3.
• Include fixes to examples that don't compile in wdl-tests (#707, #708, #701, #738, #731, #740, #739). Thanks to @adamnovak and @claymcleod!
• Add in CI/CD for MiniWDL, Sprocket, Toil, and Cromwell for spec compliance.
• Remove Advanced Task Examples to clearly distinguish what testing is in scope (#730).

Full Changelog: v1.2.0...v1.2.1

WDL Specification v1.1.3

What's Changed

• Updates the compliance suite to use spectool (#753).
• Fix issues with examples (#653, #654, #661, #662, #663, #664, #665, #666, #668, #671). Thanks to @stxue1!
• Clarify that a file is not required to exist or be accessible until and unless it is accessed.
• Fix unit test for round() to properly test for round-half-up behavior as described.
• Fix issues with examples (#707, #708, #701). PR 706 by @vsmalladi
• Add in CI/CD for Miniwdl, Sprocket, Toil and Cromwell for spec compliance.
• Remove Advanced Task Examples to clearly distinguish what testing is in scope.

Full Changelog: v1.1.2...v1.1.3

WDL v1.3.0

This release includes a number of backwards compatible fixes and improvements to the WDL specification.

Some highlights include:

• else if/else clauses for conditionals.
  • This allows you to more concisely and elegantly express conditional clauses.
• Enumeration types (enum) for defining closed sets of named choices.
  • This prevents silent failures from typos by catching invalid values at validation time rather than runtime.
• The split() standard library function.
  • This eliminates the need for shell workarounds when parsing delimited strings.
• Access to task.previous for runtime access to the previous attempt's computed requirements.
  • This enables dynamic resource allocation patterns like doubling memory on retry.
• Relaxed version imports allowing any WDL v1.x document to import v1.x or lower.
  • This enables better package management and dependency handling across the ecosystem.

See the blog post for an overview or the CHANGELOG.md for more details on what's changed.

WDL v1.2.0

Overview

This release includes a new minor version of the WDL language, v1.2. This also introduces a new version of the specification, in this case, v1.2.0. Minor version releases include new, backwards compatible changes, such new types, new execution concepts, or the ability to better and more scalably run existing workflows.

What's New

Files and Directories

• Added Directory type (#641).
• Added JSON extended file/directory input/output format (#643).
• Input files and directories should be treated as read-only (#642).
• Local paths are always used when evaluating input/private/command expressions.
• Clarified the meaning of a remote parent folder for the purposes of localization.

Requirements and Hints

• The requirements and hints sections (#540 and #541, respectively) replace the runtime section.
• Adds the workflow hints section (#543).
• fpga requirement and reserved hint for requesting FPGA resources.
• disks and gpu reserved hints for requesting specific resources.
• Implicit task variable that provides access the actual values of requirements, meta, and parameter_meta at runtime.

Struct Improvements

• Structs can now have meta and parameter_meta sections.
• Relaxed the requirements on coercing object/map to struct - extra keys are allowed and ignored. Note that this may constitute a breaking change if you rely on a task to fail when coercing an object/map with extra keys.
• Allow conversion between Struct types when certain criteria are met.

Standard Library Functions

New

• contains_key: whether a Map or Object contain a specific member (#603).
• values: get the values from a Map.
• find: search for a regular expression in a string.
• matches: whether a string match a regular expression.
• chunk: split an array into sub-arrays.
• join_paths: join two or more paths.
• contains: whether an array contains a specified value.

Improved

• Generalized size function to take any compound value.
• Added optional default parameter to select_first.
• Generalized length function to also accept Map, Object, and String arguments.
• Added the Array[String] keys(Struct|Object) function variant for getting the member names for a struct or object.
• Added parameters to read_tsv that enable it to read field names from a header row or an Array[String] and return an Array[Object] (#627).

Other

• Exponentiation operator (**).
• Multi-line strings (#602).
• Clarify that accessing a non-existent member of an object, struct, or call is an error.
• Inputs with defaults are implicitly optional (#464 by @mlin).
• input: is optional in call bodies (#524 by @mlin).
• The concept of "scoped types", to support the use of object-like values within the hints section while still keeping the Object type as deprecated.

What's Deprecated

• runtime section (use requirements and hints instead).
• Specifying allowNestedInputs in the workflow meta section (put it in workflow hints instead).
• The previously allowed behavior implied by setting allowNestedInputs: true where required task/subworkflow inputs could be left unsatisfied. Now all inputs either need to have a default value or have their value specified in the call inputs. Only optional task/subworkflow inputs that are not explicitly set in the call inputs may have their value set at runtime if the allow_nested_inputs hint is true.

New Contributors

• @wleepang made their first contribution in #604
• @markjschreiber made their first contribution in #605

Full Changelog: v1.1.0...v1.2.0

WDL Specification v1.1.2

What's Changed

• State that Union is also the type of some runtime attributes.
• Remove some syntax sections that were missed in 1.1.1.
• Clarify short-circuiting of boolean expressions (#199).
• Added requirement for tests to the RFC.
• Clarifies number of sections allowed within task and workflow blocks (#598 by @claymcleod).
• Clarified that read_bool is case-insensitive, and added an example.

Full Changelog: https://github.com/openwdl/wdl/compare/v1.1.1..v1.1.2

WDL Specification v1.1.1

This is a patch release to the WDL 1.1 specification - there are no new features or changes to functionality.

In addition, we are changing to a separate-branch-per-version model for the GitHub repository. The branch for WDL 1.1 will become the repository's default branch.

Changes

• Introduce the concept of "hidden types"; declare that None is of the hidden type Union.
• Add clarifications to several sections.
• Fix lots of typos.
• Organize the standard library hierarchically.
• Convert most code examples to test cases.

Details can be found in the pull request.

Legacy WDL

This is a pseudo-release tag that marks the location of themain branch within the specification repository prior to the release of WDL v1.1.1. Going forward, each version of the specification will have its own branch, and the default branch on GitHub will be set to the branch for the current version.