Digital Object Identifiers

Introduction

Why would you need a DOI?

A Digital Object Identifier (DOI) is a permanent identifier that can be used in publications to identify the exact version of a workflow or tool (entry). A DOI can be used by both humans and machines to resolve a reference to a piece of information or data in a persistent way. DOIs are commonly referenced from academic papers.

See the DOI Foundation for more details.

Why would you need a DOI for software?

When others use your software, they should cite your software and what version of your software was used, especially in the methods section. In addition, in the context of reproducible science, it can be critically important for readers to understand which version of your software was used since different versions of software can have different performance or can be compatible with different platforms. Nothing can be more frustrating than not knowing what version of a piece of software should be used in addition to not knowing in what environment it should be used.

Citing the version of software used is not intended to supplant a traditional scholarly publication, but is intended to supplement it. This can help future researchers to run your software both in new contexts or in larger contexts. In particular, the software DOI approaches that we recommend point to an archive (sometimes frozen for more certainty) of the source code for the version of the workflow in question. This archive can include all or some of the other pieces of information that we recommend such as a Dockerfile(s) to describe the creation of the environment for the source code, licensing information, test parameter files, and more.

See the Software citation principles, the link rot and redundancy discussions of Ten simple rules for writing a paper about scientific software, and How Not to Cite Software (and how to be cited), for more details.

Dockstore Support for DOIs

Creating and assigning DOIs is commonly known as “minting”. Many repositories mint DOIs. Dockstore currently only supports Zenodo DOIs. Dockstore uses Zenodo to mint DOIs, and it can also recognize DOIs generated by Zenodo outside of Dockstore.

Zenodo supports DOI versioning with a concept DOI for an overall record, and version-specific DOIs.

In Dockstore, the concept DOI is associated with the entry as a whole, and version DOIs are associated with entry versions.

Dockstore can generate DOIs for entries, as well as recognize some DOIs generated outside of Dockstore. Dockstore displays DOIs associated with entries. If you have multiple concept DOIs associated with a single entry, you can specify which DOI to display.

Dockstore generates DOIs for entries 2 ways:

  • Explicitly initiated by a Dockstore user. This approach requires you linking your Zenodo account. You select a version via the Dockstore UI and click to create a DOI. See Creating Snapshots & Requesting DOIs for more details

  • Dockstore can automatically generate DOIs for your entries without you needing to link your Zenodo account. These DOIs are created in the Dockstore Zenodo Community

In addition, Dockstore can discover DOIs created by a Zenodo-GitHub integration.

Choosing which DOI to display

When viewing the public page of an entry, the entry’s concept DOI and the selected version’s DOI are displayed.

Show DOIs

Dockstore only displays one DOI associated with a entry, even if there is more than one DOI, e.g., one generated by GitHub-Zenodo integration, and another generated by Dockstore. If this situation arises, you can control which DOI is displayed via your dashboard. Select the entry, then click “Manage DOIs”, and you’ll get a dialog like this. Select your choice and click “Save”.

Manage DOIs

Overview of the different ways of issuing DOIs

With the different ways Dockstore supports DOIs, it may be confusing as to how to generate DOIs for your Dockstore entries. Following are some details on the differences.

Creating Snapshots & Requesting DOIs

See Creating Snapshots & Requesting DOIs for more details

  • You must initiate the DOI creation for each version

    • More control over when DOIs are created

    • You have to individually do it for every tag

  • The DOIs are minted in the Zenodo Dockstore community

  • Version on Dockstore is snapshotted (frozen)

  • Requires a Zenodo account that you link to your Dockstore account

Automatic Dockstore DOI Generation

Note

This feature is currently only available on request. Please contact the Dockstore team at discuss.dockstore.org if you want to participate.

Dockstore will automatically mint a DOI for a version that corresponds to a Git tag, if:

  • The entry is published on Dockstore

  • The version is valid and has at least one author in its metadata

  • The tag is created after you publish the entry, or the tag is one of the 10 most recent when you publish the entry

Automatically-generated DOIs:

  • Do not require a Zenodo account

  • Are minted in the Zenodo Dockstore community

  • Are editable by request to the Dockstore team

  • Will be editable via a Zenodo account in a subsequent Dockstore release

GitHub-Zenodo Generation

Zenodo has a feature where you can link your GitHub account, then specify repositories where Zenodo automatically mints DOIs when GitHub releases are created. Note that a GitHub release is not the same as a Git tag; GitHub releases require Git tags, but have extra features.

To set up and configure your Zenodo-GitHub integration, navigate to Zenodo GitHub account settings.

The DOIs created by this integration follow a certain pattern that Dockstore can detect. Dockstore will poll Zenodo to see if any new DOIs have been created against Dockstore entries’ GitHub repositories.

  • Automatic

  • Only mints DOIs for GitHub releases

  • Can mint DOIs for GitHub repos without associated workflows in Dockstore

    • Useful for minting DOIs for GitHub repositories that aren’t workflows or tools

    • Can mint DOIs for entries that haven’t yet been registered in Dockstore

Summary of Differences

Generation Type

Zenodo Account Required

Snapshot Required

Triggered by

Manual by Dockstore User

Yes

Yes

User request

Automatically by Dockstore

No

No

Push of a Git tag to GitHub for

a published Dockstore entry, or

on publication of entry

Zenodo-GitHub integration

Yes

No

GitHub release for a repository

with a published Dockstore entry