Software Citation with CITATION.cff

The Citation File Format lets you provide citation metadata, for software or datasets, in plaintext files that are easy to read by both humans and machines.

Fig. 98 Research software developers get recognition by making software citable. The Turing Way project illustration by Scriberia. Zenodo. http://doi.org/10.5281/zenodo.3332807

To provide this metadata, start by writing a CITATION.cff file and include it with your software or dataset. A CITATION.cff file aggregates the information in a key-value format that can be easily interpreted and updated by humans, and easily parsed and converted with existing tools.

Why Use CITATION.cff?

There are great advantages when using a CITATION.cff file for the citation information for your software!

It’s easier for you: When you host your software source code on GitHub and have a CITATION.cff in your repository, you can use the Zenodo-GitHub integration to automatically publish new releases of the software. Zenodo will use the information from CITATION.cff and show it together with the publication. You don’t have to edit this information manually on Zenodo anymore.

Fig. 99 More credits for the software creators. The Turing Way project illustration by Scriberia. Zenodo. http://doi.org/10.5281/zenodo.3332807

It’s easier for the users of your software:

1. They can directly use the citation information from CITATION.cff to cite your software.

2. If your source code is on GitHub, they will show the citation information in the sidebar as a formatted citation, and also in the BibTeX format. Users can copy either, paste it into their manuscripts, and/or cite your software correctly.

3. If they use the Zotero reference manager, they can import the citation metadata directly from the CITATION.cff file in the GitHub repository to their reference manager.

How to Create a CITATION.cff File

The CITATION.cff is a YAML file with its own schema definition. The schema defines the rules for each field, and which fields are required and which ones are optional. The user must follow these rules in order to create a valid CITATION.cff file.

A minimal example of a valid CITATION.cff file, that only contains the required keys, would look like this:

authors:
  - family-names: Doe
    given-names: John
cff-version: 1.2.0
message: "If you use this software, please cite it using the metadata from this file."
title: "My research software"

However, adding more fields can help you create more descriptive metadata of your software. The example below also provides important information of software such as version, release date, DOI, license, keywords.

abstract: "This is my awesome research software. It does many things."
authors:
  - family-names: Doe
    given-names: John
    orcid: "https://orcid.org/0000-0001-8888-9999"
cff-version: 1.2.0
date-released: "2021-10-13"
identifiers:
  - description: "This is the collection of archived snapshots of all versions of My Research Software"
    type: doi
    value: 10.5281/zenodo.123456
  - description: "This is the archived snapshot of version 0.11.2 of My Research Software"
    type: doi
    value: 10.5281/zenodo.123457
keywords:
  - "amazing software"
  - research
license: Apache-2.0
message: "If you use this software, please cite it using the metadata from this file."
repository-code: "https://github.com/citation-file-format/my-research-software"
title: "My Research Software"
version: 0.11.2

The complete list of fields is described in the CFF schema guide. In the next section, you can find out which tools can help you create and use the CITATION.cff file.

Steps to Make Your Software Citable

To make your software citable, you need to follow the two steps below.

Step 1. Create a CITATION.cff File

There are two ways of creating a CITATION.cff file.

1. Use cffinit, a web application which guides you through the process of creating your citation file. The cffinit has a few advantages compared to manual editing such as

   • no need for installing extra tools;

   • no need for manual validation;

   • guidance for each fields;

   • visual feedback to indicate issues.

   We suggest using cffinit as it simplifies the creation and validation. For more details on using cffinit see Create a CITATION.cff using cffinit.

2. Edit the file manually in your favorite code editor. The disadvantages of this method are installing the required tools on your system and doing the validation yourself. Also, the error messages of the validation can be relatively long and difficult to understand. Once you have a CITATION.cff file, it needs to be validated to make sure there are no issues. You can validate your CITATION.cff file on the command line with the cffconvert Python package.

   cd path/to/CITATION.cff
   cffconvert --validate
   

   If you prefer to use Docker, you can use the cffconvert Docker image:

   cd path/to/CITATION.cff
   docker run --rm -v ${PWD}:/app citationcff/cffconvert --validate
   

   If you get error messages, look for the relevant validation error and fix it.

Note

To make sure your GitHub repository always has a valid CITATION.cff file, you can use the cff-validator GitHub Action.

Step 2. Add Your CITATION.cff to a Public Code Repository

After creating a valid CITATION.cff file, you will need to add it to root of your code or data repository so that it can be easily found and cited.

Updating your CITATION.cff file

When you need to update your CITATION.cff file, for example to add an author or to change the information about releases, you will need to edit the file manually. It is recommended to update your CITATION.cff file before making a software release.

How to Cite Using CITATION.cff

If you have found software or datasets that contain a CITATION.cff, there are a few ways to obtain the reference information to cite them in your publication.

• You can use one of the tools, such as cffconvert command line program, to convert your CITATION.cff file to one of the supported formats, such as APA, BibTeX or EndNote.

• Alternatively, if the software or datasets you want to cite are available on GitHub, you can use GitHub’s interface to copy the reference in either APA or BibTeX formats by clicking the “Cite this repository” button (see the green area in the image below). For more details on software citation on GitHub please see GitHub’s guide on software citation.

  

  Fig. 100 “Cite this repository” automatically converts the CITATION.cff file to APA’s and BibTex’s format. The screen capture is from the Citation File Format repository.

  Note

  “Cite this repository” button only appears when there is a CITATION.cff file in the repository.

Available Tools

Several tools exist to facilitate the creation and validation of CITATION.cff files, as well as the conversion to and from other formats. The Citation File Format’s repository provides a list of all known tools for this.