3 minute read

Citation File Format (CFF)

Citation File Format is a human- and machine-readable file format in YAML 1.2 which provides citation metadata for software. It is maintained openly on GitHub: https://github.com/citation-file-format.

The current version is 1.0.3, for which there is a detailed format specification.


If you want to make your software easily citable, you can put a file called CITATION.cff in the root of your repository. This file should provide at least the minimally necessary metadata to cite your software. For example:

cff-version: 1.0.3
message: If you use this software, please cite it as below.
  - family-names: Druskat
    given-names: Stephan
    orcid: https://orcid.org/0000-0003-4925-7248
title: My Research Tool
version: 1.0.4
doi: 10.5281/zenodo.1234
date-released: 2017-12-18

A CFF file can also be used to record much more information about your software. For an overview of what software metadata can be supplied with the Citation File Format, please see the current version of the format specifications.


There are a number of tools that can help you work with the Citation File Format to perform useful tasks: generate a CITATION.cff file from a DOI, convert CFF files to formats required by reference management software’, or validate CITATION.cff files. For further information, please see the CFF GitHub repository.


The spectrum of available concepts for software citation metadata files reaches from non-standardized CITATION files as suggested by Robin Wilson (Wilson, 2013)1 to full transitive credit encoded in JSON-LD (Katz & Smith, 2015).

Along this spectrum, Citation File Format is located somewhere between these two extremes as it adds machine-readability and thus a greater re-use potential to CITATION files, but does not offer transitive credit capabilities (yet), or support for all citation use cases as outlined by Smith et al., (2016).

Citation File Format aims at providing a practical solution, and human-friendly properties such as readability and writability, for the most common software citation use cases, i.e., 1. Use software for a paper, 2. Use software in/with new software, and 15. Store software entry (cf. Table 2, Smith et al., (2016), p. 6).

The basic structure of Citation File Format (i.e., having a message and one or more references) explicitly reflects the structure of plain-text CITATION files and manifests its status as a compromise between what is currently useful and usable, and what is desired (fully transitive credit and attribution). As such, it has value both as a discrete format with everyday application and as a input format populating other citation formats.


Software citations enhance the dissemination of code, improve software sustainability and ensure authors receive credit for development work. The Citation File Format is an indirect outcome of the discussion group “DS3. Development and implementation of a standard format for CITATION files.” at the Workshop on Sustainable Software for Science: Practice and Experiences (WSSSPE5.1) (6 September 2017, Manchester, UK). The group discussed the potential and outlined requirements for a format for machine-readable CITATION files, and has authored a blog post on the subject, published on the blog of the Software Sustainability Institute.

Members of the group were:

  • Stephan Druskat (Humboldt-Universität zu Berlin, Germany), Lead
  • Neil Chue Hong (Software Sustainability Institute, University of Edinburgh, UK)
  • Raniere Silva (Software Sustainability Institute, University of Manchester, UK)
  • Radovan Bast (University of Tromsø, Norway)
  • Andrew Rowley (University of Manchester, UK)
  • Alexander Konovalov (University of St. Andrews, UK)

One requirement for the blog post was to be able to make a concrete suggestion for a format for these machine-readable CITATION files, which triggered the development of Citation File Format.


Contributions to CFF are welcome! Please have a look at the guidelines for contributing.


  1. Wilson, Robin. (2013). Encouraging citation of software - introducing CITATION files. Retrieved from https://www.software.ac.uk/blog/2013-09-02-encouraging-citation-software-introducing-citation-files.

  2. Katz, Daniel S, & Smith, Arfon M. (2015). Implementing transitive credit with JSON-LD. Journal of Open Research Software, 3(e7). https://doi.org/10.5334/jors.by.

  3. Smith, Arfon M., Katz, Daniel S., Niemeyer, Kyle E., & FORCE11 Software Citation Working Group. (2016). Software citation principles. PeerJ Computer Science, 2, e86. https://doi.org/10.7717/peerj-cs.86.

  1. Not providing a file with software citation metadata is not considered a valid option here.