# A CITATION.cff file makes your software citable without a manual > The Citation File Format is a YAML file that carries the citation metadata for a piece of software or a dataset, so GitHub, Zenodo, Zotero and other tools can all read the same answer. It is a specification rather than a library, it is CC-BY-4.0 licensed, and the version 1.2.0 schema is the current one with releases dating back to 2021. **citation-file-format/citation-file-format** — 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. - Repository: https://github.com/citation-file-format/citation-file-format - Website: http://citation-file-format.github.io - Stars: 563 · Forks: 125 - Language: Python - License: CC-BY-4.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/citation-file-format-citation-file-format ## One YAML file that four tools can read 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. The file is named CITATION.cff and it lives in the root of the repository, and the format is YAML. The reason to care is that the same file feeds several systems at once. The documentation lists four things that happen when you add it. Users of your software can cite it using the metadata. If your repository is hosted on GitHub, the citation information appears in the sidebar, which makes it easy for visitors to cite your software or dataset correctly. When you publish on Zenodo through the GitHub-Zenodo integration, Zenodo uses the metadata from the file. And people can import the correct reference into Zotero through a browser plugin. So the format is a contract between a repository and the tools around it. Nothing in it is specific to GitHub, but GitHub is what makes the value obvious, because the sidebar rendering is immediate and visible. The project describes itself as a research software engineering effort, with a topic list that includes attribution, credit, software-sustainability and wssspe, and it is published under CC-BY-4.0 with a Zenodo DOI badge for the specification itself. ## The fields a CITATION.cff file actually carries The example in the documentation is the fastest way to see the whole structure, and it is worth reading as a single block because it shows both required and optional parts: ```yaml 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/1234-5678-9101-1121" - 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" ``` Several design decisions are visible in that example. The version key is the version of the software being described, while cff-version is the version of the format itself, and confusing the two is the most common mistake when writing one by hand. The authors list shows two shapes. A person is described by family-names, given-names and an orcid, and an organisation is described by a single name field. The orcid matters more than it looks, because it is the identifier that lets a bibliography manager merge your work with everything else a person has published. The identifiers list is the part that makes per-version citation possible, with a description, a type and a value for each. The example has a concept DOI for the collection of all archived snapshots, and a separate DOI for the specific version, and the difference between them is the difference between citing the project and citing the release. ## Referencing other work, and redirecting the credit Beyond describing the artefact itself, the format covers two cases that come up constantly in research software. The first is providing references to works that the software or dataset builds on. The documentation points at a section of the schema guide on referencing other work, and the point of it is attribution: a paper that your package implements, a dataset it was derived from, a prior implementation it replaces. The second is credit redirection, where you ask people to cite a different, related work instead of the software or dataset itself. The documentation has a section for that in the schema guide too. This is the case for a piece of software that exists only to run someone else's method: the thing that deserves the citation is the method paper, not the wrapper. Both are extensions to the core file rather than a different file, which is the practical point. The same CITATION.cff that GitHub renders in the sidebar can also carry a list of prior work and a pointer at a paper that should get the credit instead. The complete format specifications are in the Guide to the Citation File Format schema, schema-guide.md, with the machine readable schema itself in schema.json at the root of the repository. ## Validate it before you tag a release The validation step is a Python package called cffconvert, and it is the piece of tooling that makes a hand-written file safe to ship. The documented commands are short: ```shell # Install cffconvert with pip in user space python3 -m pip install --user cffconvert # Validate your CFF file cffconvert --validate ``` The guidance on what to do when validation fails is practical. If you get a traceback with error messages, look for the relevant validation error and fix it. If the output is very long, search it for lines starting with jsonschema.exceptions.ValidationError, since the underlying schema validator produces a lot of noise and the specific error is the part you need. If you would rather not install Python, there is a Docker image, and the invocation mounts the current directory at /app so the tool finds the file: ```bash cd docker run --rm -v ${PWD}:/app citationcff/cffconvert --validate ``` The repository's own development requirements list cffconvert, pytest, jsonschema, ruamel.yaml and bump2version, and the tests directory plus an examples directory holding one folder per format version, 1.0.3, 1.1.0 and 1.2.0, which is a useful way to see what changed between revisions of the schema. ## Three ways to create the file, and a tool catalogue Creating a CITATION.cff file is deliberately easy. You can use the cffinit website, copy and paste the example snippet from the documentation and adapt it, or create a new file called CITATION.cff using the Add file button on GitHub and use the template GitHub provides. The GitHub route is the fastest for a new repository, since the template is already valid, and for a repository that already exists the cffinit site produces a file interactively. There is also a catalogue of tools. The documentation keeps a table of what is known to exist, with columns for creation, editing and updating, validation, and conversion, and rows for command line tools and, further down, for other categories. The command line row lists cffconvert for validation, and for conversion it lists cffconvert, bibtex-to-cff, cff-from-621 and openCARP-CI. The last two are worth noting for what they imply: there is a path from a BibTeX file into the Citation File Format, and one from the 621 format used by some research software, so a project with existing bibliography files does not have to retype them. The catalogue is a living list with a stated process for gaps. If a tool is missing, the documentation asks you to open a new issue on the repository and say so, which is a reasonable way to keep a community-maintained list honest. ## A specification at version 1.2.0, with the releases trailing the work The version history is where a reader should slow down. The releases are 1.2.0 from 2021-08-09, 1.1.0 from 2021-05-12, and v0.9-RC1 from 2017-10-06, which was named as a release candidate for the format specifications. So the published releases of the specification stop in 2021, while the last push to the repository was on 2026-09-29. The repository is not archived, and the commits continue, but they are not producing new tagged versions of the format. That is the correct behaviour for a format specification, since the schema is a contract and changing it under a new version number would break every existing file. Changes now go into the guide, the schema and the example files, and the version in the cff-version key of new files stays at 1.2.0. The practical consequence for you as a user is that cff-version 1.2.0 is the version to write, and the schema guide is the reference to consult for what each field means and what the validation rules are. The three example directories in the repository, 1.0.3, 1.1.0 and 1.2.0, show you how a real file changed between those revisions if you are migrating an older one. The specification itself is archived on Zenodo under a concept DOI, and the repository holds its own CITATION.cff, a CHANGELOG, a code of conduct, a contributing guide and a tool catalogue, so the format is documented, exemplified and self-applied in one place. ## Conclusion Adopt the Citation File Format if you publish software or data and want a machine readable statement of who to cite, because a CITATION.cff file is what GitHub renders in the sidebar and what the GitHub-Zenodo integration reads when it archives a release. Do not adopt it if your project is not citable as a work, such as a private internal tool, since the format is about attribution of a published artefact. Before you write one, check three things: the cff-version you put at the top of the file, since the schema has moved through 0.9, 1.1.0 and 1.2.0 and the format specifications live in the schema guide, the identifiers you list, because a DOI per version is what lets a reader cite the exact release rather than the project, and that you run cffconvert --validate before you tag a release, since a malformed file silently degrades the metadata to whatever your other tooling provides. ## FAQ ### What is a CITATION.cff file? It is a YAML file, named CITATION.cff and placed in the repository root, that carries citation metadata for a piece of software or a dataset. The format is the Citation File Format, and its complete specifications are in the schema guide. ### How do I validate my CITATION.cff file? Install cffconvert with pip in user space, then run cffconvert --validate. If the output is long, search it for lines starting with jsonschema.exceptions.ValidationError to find the specific error. There is also a Docker image, run with the current directory mounted at /app. ### Which cff-version should my CITATION.cff file declare? 1.2.0, which is the current schema version. The repository's example directories cover 1.0.3, 1.1.0 and 1.2.0 if you are migrating an older file, and the released versions of the specification stop at 1.2.0 from 2021-08-09. ### Can I cite a paper instead of the software itself with a CITATION.cff file? Yes. The format allows you to ask people to cite a different, related work instead of the software or dataset, and it also allows references to the works your software or dataset builds on. Both are covered in the schema guide. ### Which tools can create or convert CITATION.cff files? You can create a file with the cffinit website, by copying the documented example, or with the template GitHub provides through its Add file button. For conversion the catalogue lists cffconvert, bibtex-to-cff, cff-from-621 and openCARP-CI, and the project asks for an issue when a tool is missing from the list. ## Sources - [citation-file-format/citation-file-format on GitHub](https://github.com/citation-file-format/citation-file-format) - [License: CC-BY-4.0](https://github.com/citation-file-format/citation-file-format/blob/main/LICENSE) - [Project website](http://citation-file-format.github.io) - [README](https://github.com/citation-file-format/citation-file-format/blob/main/README.md) - [Releases](https://github.com/citation-file-format/citation-file-format/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/citation-file-format-citation-file-format