.dockstore.yml for Tools 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 tool

version: 1.2
tools:
  - subclass: CWL
    primaryDescriptorPath: <String>
    testParameterFiles: <String Array>
    authors:
      - name: <String>
        email: <String>

Filled-out example of a single tool without a name

Although the author has a name, the tool itself is not identified with one.

version: 1.2

tools:
  - subclass: CWL
    primaryDescriptorPath: /runGlobalAligner.cwl
    testParameterFiles:
        - /test/globalAligner.cwl.json
    authors:
        - name: Bob Generic Example
          email: makesuretofilloutanactualemailaddress@ucsc.edu

Filled-out example of a single tool with a name

Same as the example above, but we explictly name the tool “globalAligner” using the name field, a user-defined identifier string that can contain letters, numbers, internal hyphens, and internal underscores, but no spaces or other characters.

version: 1.2
tools:
  - name: globalAligner
    subclass: CWL
    primaryDescriptorPath: /runGlobalAligner.cwl
    testParameterFiles:
        - /test/globalAligner.cwl.json
    authors:
        - name: Bob Generic Example
          email: makesuretofilloutanactualemailaddress@ucsc.edu

Filled-out example of multiple tools in the same repository

This .dockstore.yml will result in the creation of two entries on Dockstore: One for globalAligner, and one for localAligner.

You will note that localAligner has three authors. The first two are identified with orcids. The third author is instead identified with their name and email address.

version: 1.2
tools:
  - name: globalAligner
    subclass: CWL
    primaryDescriptorPath: /runGlobalAligner.cwl
    testParameterFiles:
        - /test/globalAligner.cwl.json
    authors:
        - name: Bob Generic Example
          email: makesuretofilloutanactualemailaddress@ucsc.edu
  - name: localAligner
    subclass: CWL
    primaryDescriptorPath: /runLocalAligner.cwl
    testParameterFiles:
        - /test/localAligner.cwl.json
    authors:
        - orcid: 0000-0000-0000-0000
        - orcid: 1111-1111-1111-1111
        - name: Bob Generic Example Jr
          email: anotherpersonsemailaddress@ucsc.edu

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 tools. Each element corresponds to a tool entry on Dockstore.
tools:

  # The optional name for a tool, 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 tools, this field is required
  # to uniquely identify tools in the repository. Otherwise, it is optional.
  #
  # 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 tool. Note that .dockstore.yml registration does not support WDL tools,
    # as we discourage the registration of WDL tools and may deprecate them in the future.
    subclass: <CWL>

    # Tool-wide setting that will affect ALL branches/tags; only set this as needed in a main branch.
    # Set to true to publish an unpublished tool, or false to unpublish a published tool.
    # 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.
    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:
      - 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`, `mycooltool/**`)
    # 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/`, `/mycooltool\/.*/`).
    filters:
      branches: <String Array>
      tags: <String Array>

See Also