.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>
    readMePath: <String>
    authors:
      - name: <String>
        email: <String>

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

Filled-out example of a single workflow without a name

In this example, the workflow author is identified with an ORCID iD. When an ORCID iD is specified, there is no need to specify an author’s name and email as that information will be pulled from the ORCID API. There are also three test parameter files given for the workflow. Since no readMePath is specified, Dockstore will show the top-level readme (if one is present), eg, /readme.md

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 assoc-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. We have also added the optional readMePath value to these workflows so that each entry gets its own workflow-specific readme.

This .dockstore.yml will result in the creation of two entries on Dockstore – one for assoc-aggregate-wdl, and one for pc-air-wdl. assoc-aggregate-wdl’s entry will show the readme located at /assoc-aggreate/readme.md, while pc-air-wdl’s entry will show the readme located at /pc-air/README.md. Although readMePath is optional, if we did not add it to these entries, both entries would instead show the same top-level readme.md (or README.md) of the git repo.

version: 1.2
workflows:
  - subclass: WDL
    primaryDescriptorPath: /assoc-aggregate/assoc-aggregate.wdl
    readMePath: /assoc-aggregate/readme.md
    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
    readMePath: /pc-air/README.md
    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 path to a workflow-specific readme in the Git repository. If not provided, Dockstore will show
    # the readme.md present at the root of the Git repository if it is present.
    # If you have multiple workflows in a single Git repository, it is recommend to give each one a readme.
    readMePath: <String>

    # 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:
      - orcid: <String>
      - name: <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>