Skip to content
Permalink
main
Switch branches/tags
Go to file
11 contributors

Users who have contributed to this file

@sdruskat @jspaaks @ots22 @yochannah @hainesr @monperrus @mcmarius @jodischneider @egonw @dieghernan @bast

Citation File Format

Build Status DOI License: CC BY 4.0 Project homepage

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.

Structure

You can specify citation metadata for your software (or dataset) in a file named CITATION.cff. This is what a typical CITATION.cff file may look like for research software:

cff-version: 1.2.0
message: If you use this software, please cite it using these metadata.
title: My Research Software
abstract: This is my awesome research software. It does many things.
authors:
  - family-names: Druskat
    given-names: Stephan
    orcid: "https://orcid.org/0000-0003-4925-7248"
  - name: "The Research Software project"
version: 0.11.2
date-released: "2021-07-18"
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"
license: Apache-2.0
repository-code: "https://github.com/citation-file-format/my-research-software"

In addition, the Citation File Format allows you to

Format specifications 📚

You can find the complete format specifications in the Guide to the Citation File Format schema.

Why should I add a CITATION.cff file to my repository? 💡

When you do this, great things may happen:

  1. Users of your software can easily cite it using the metadata from CITATION.cff!
  2. If your repository is hosted on GitHub, they will show the citation information in the sidebar, which makes it easy for visitors to cite your software or dataset correctly.
  3. When you publish your software on Zenodo via the GitHub-Zenodo integration, they will use the metadata from your CITATION.cff file.
  4. People can import the correct reference to your software into the Zotero reference manager via a browser plugin.

Creation

To create a CITATION.cff file, you can

  • use the cffinit website,
  • copy and paste the example snippet, and adapt it to your needs, or
  • create a new file called CITATION.cff using the Add file button on GitHub, and use the template they provide.

Validation ✔️

You can validate your CITATION.cff file on the command line with the cffconvert Python package:

# Install cffconvert with pip in user space
python3 -m pip install --user cffconvert

# Validate your CFF file
cffconvert --validate

If you get a Traceback with error messages, look for the relevant validation error and fix it. If the output is very long, it may help if you search it for lines starting with jsonschema.exceptions.ValidationError.

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

cd <directory-containing-your-CITATION.cff>
docker run --rm -v ${PWD}:/app citationcff/cffconvert --validate

Tools to work with CITATION.cff files 🔧

There is tooling available to work with CITATION.cff files to do different things: create new files, edit existing files, validate existing files, convert files from the Citation File Format into another format. The following table gives an overview of the tools that we know about. If there is a tool missing from this table, please open a new issue and let us know.

Creation Editing/Updating Validation Conversion
Command line cffconvert cffconvert
bibtex-to-cff
GitHub Actions cff-validator cffconvert
codemeta2cff
GitHub Bot #238
Docker cffconvert Docker image cffconvert Docker image
Go datatools/codemeta2cff
Haskell cffreference
Java CFF Maven plugin CFF Maven plugin CFF Maven plugin
JavaScript Citation.js plugin
Julia Bibliography.jl Bibliography.jl
PHP bibtex-to-cff
Python doi2cff cffconvert cffconvert
doi2cff
R citation
r2cff
handlr
cffr
Ruby ruby-cff ruby-cff ruby-cff ruby-cff
TypeScript #28
Website cffinit

Maintainers 🤓

The Citation File Format schema is maintained by

Contributing 🤝

The Citation File Format is a collaborative project and we welcome suggestions and contributions. We hope one of the invitations below works for you, but if not, please let us know!

🏃 I'm busy, I only have 1 minute

  • Tell a friend about the Citation File Format, or tweet about it!
  • Give the project a star !

I've got 10 minutes - tell me what I should do

  • Create a CITATION.cff file for your repository.
  • Suggest ideas for how you would like to use the Citation File Format, or for an improvement to the format or its tooling.
  • If you know how to validate CITATION.cff files, help someone with a validation problem and look at the issues labeled GitHub labels

💻 I've got a few hours to work on this

🎉 I want to help grow the community

  • Write a blog post or news item for your own community.
  • Organise a hack event or workshop to help others use or improve the Citation File Format.

Please read the more detailed contributing guidelines and open a GitHub issue to suggest a new idea or let us know about bugs. Please put up pull requests for changes to the format and schema against the develop branch!

License ⚖️

Copyright © 2016ff. The Citation File Format Contributors

This work is licensed under a Creative Commons Attribution 4.0 International (CC-BY-4.0) license.

Acknowledgments 🙏

We'd like to thank everyone who has contributed to the Citation File Format!
They are listed in the CITATION.cff file for this repository. Please open an issue if you find that you are missing from the file.

We gratefully acknowledge support from:

Research notice

Please note that this repository is participating in a study into sustainability of open source projects. Data will be gathered about this repository for approximately the next 12 months, starting from June 2021.

Data collected will include number of contributors, number of PRs, time taken to close/merge these PRs, and issues closed.

For more information, please visit our informational page or download the participant information sheet.