.dockstore.yml for Workflows Templates (version 1.2)

Several templates and examples are provided here for you to reference for your own .dockstore.yml files. The last example provides a complete explanation of the possible fields and values you can use.

Simple generic template for a workflow

version: 1.2
workflows:
  - subclass: <CWL | WDL | NFL | GALAXY>
    primaryDescriptorPath: <String>
    testParameterFiles: <String Array>
    authors:
      - name: <String>
        email: <String>

Always use absolute paths to specify the primary descriptor and test parameter files.

Filled-out example of a single workflow without a name

In this example, the workflow author is identified with an orcid. When an orcid is specified, there is no need to specify an author’s name and email as that information will be pulled from the orcid. There are also three test parameter files given for the workflow.

version: 1.2
workflows:
  - subclass: WDL
    primaryDescriptorPath: /assoc-aggregate/assoc-aggregate.wdl
    testParameterFiles:
      - /assoc-aggregate/assoc-aggregate-terra-allele.json
      - /assoc-aggregate/assoc-aggregate-terra-position.json
      - /assoc-aggregate/assoc-aggregate-terra-weights.json
    authors:
      - orcid: 0000-0003-4896-1858

Filled-out example of a single workflow with a name

This example is identical to the one above, but the workflow in question now is identified with the name field, a user-defined string that can contain letters, numbers, internal hyphens, and internal underscores, but no spaces or other characters. See here for more information on naming workflows.

version: 1.2
workflows:
  - subclass: WDL
    primaryDescriptorPath: /assoc-aggregate/assoc-aggregate.wdl
    testParameterFiles:
      - /assoc-aggregate/assoc-aggregate-terra-allele.json
      - /assoc-aggregate/assoc-aggregate-terra-position.json
      - /assoc-aggregate/assoc-aggregate-terra-weights.json
    authors:
      - orcid: 0000-0003-4896-1858
    name: assoc-aggregate-wdl

Filled-out example of multiple workflows in the same repository

First, you will notice that we swapped the order of the name and author fields for association-aggregate-wdl compared to the examples above, to demonstrate that the order is arbitrary. Next, we added a new section for pc-air-wdl, which has a different author and its own test parameter files and descriptor file.

This .dockstore.yml will result in the creation of two entries on Dockstore – one for association-aggregate-wdl, and one for pc-air-wdl.

version: 1.2
workflows:
  - subclass: WDL
    primaryDescriptorPath: /assoc-aggregate/assoc-aggregate.wdl
    testParameterFiles:
      - /assoc-aggregate/assoc-aggregate-terra-allele.json
      - /assoc-aggregate/assoc-aggregate-terra-position.json
      - /assoc-aggregate/assoc-aggregate-terra-weights.json
    name: assoc-aggregate-wdl
    authors:
      - orcid: 0000-0003-4896-1858
  - subclass: WDL
    primaryDescriptorPath: /pc-air/pc-air.wdl
    testParameterFiles:
      - /pc-air/pc-air-local.json
      - /pc-air/pc-air-terra.json
    name: pc-air-wdl
    authors:
      - orcid: 0000-0001-9163-2756

Full template with explanation of all available fields

# The first line refers to the version 1.2 of the .dockstore.yml schema
version: 1.2

# An array of workflows. Each element corresponds to a workflow on Dockstore.
workflows:

  # The optional workflow name for a workflow, which may only consist of alphanumerics
  # and internal underscores and hyphens, but no spaces or other characters. Names may not exceed 256 characters.
  # If using a .dockstore.yml with multiple workflows, this field is required
  # to uniquely identify workflows in the repository.
  #
  # It should be noted that having the name come first is an arbitrary decision.
  # You could use subclass instead, for instance. Provided arrays are not broken
  # up, the order of fields within a .dockstore.yml is not important.
  - name: <String>

    # The descriptor language used for the workflow. CWL, WDL, NFL (Nextflow), or GALAXY.
    # This cannot be changed once the workflow is registered.
    subclass: <CWL | WDL | NFL | GALAXY>

    # Workflow-wide setting that will affect ALL branches/tags; only set this as needed in a main branch.
    # Set to true to publish an unpublished workflow, or false to unpublish a published workflow.
    # Omitting the publish setting leaves the publish-state unchanged (recommended for all non-primary branches).
    publish: <Boolean>

    # The absolute path to the primary descriptor file in the Git repository.
    # - For CWL, the primary descriptor is a .cwl file.
    # - For WDL, the primary descriptor is a .wdl file.
    # - For Galaxy, the primary descriptor is a .ga file.
    # - Nextflow differs from these as the primary descriptor is a nextflow.config file.
    primaryDescriptorPath: <String>

    # An optional array of absolute paths to test parameter files in the Git repository.
    # For example...
    # testParameterFiles:
    #   - /null-model/null-model.json
    #   - /null-model/null-model-binary.json
    testParameterFiles: <String Array>

    # An optional array of authorship information.
    # Note that if orcid is present, then all other fields will be ignored, as information will be taken from orcid.
    # If orcid is not present, make sure to at a minimum include the name field for each author.
    authors:
      - name: <String>
        orcid: <String>
        email: <String>
        role: <String>
        affiliation: <String>

    # A boolean that will change the default version to be displayed on Dockstore. Default: False.
    # A value of true will automatically display the latest tag updated as default.
    # A value of false will retain the default version that has been specified via the Dockstore UI.
    latestTagAsDefault: <Boolean>

    # The optional filters section allow specifying sets of Git branches and tags to include for the workflow.
    # If no filters are given, all branches and tags are included.
    # Branches and tags are arrays of pattern-strings.
    # Pattern-strings use Unix-style Glob syntax by default (Ex: `develop`, `myworkflow/**`)
    # https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)
    # or RegEx when the string is surrounded by / (Ex: `/develop/`, `/myworkflow\/.*/`).
    filters:
      branches: <String Array>
      tags: <String Array>

See Also