Examples
Worked examples
- Is an instance
A repository maintainer adds a CITATION.cff to a GitHub repo's default branch; GitHub automatically reads it and shows a 'Cite this repository' panel with a ready-made APA/BibTeX citation.
- Is an instance
A software author runs the cffconvert command-line tool against their CITATION.cff to generate a CodeMeta.json or a BibTeX entry for a manuscript, without retyping metadata.
- Is an instance
When a GitHub repository is archived through the GitHub-Zenodo integration, Zenodo reads the CITATION.cff metadata (authors, title, version) to pre-populate the deposit record before minting a DOI.
Counter-examples
Looks similar, but isn't
- Not an instance
A free-text 'How to cite this software' paragraph in a README is not a CITATION.cff -- it is not machine-readable and GitHub/Zenodo tooling cannot parse it.
- Not an instance
Citation-relevant fields inside a package.json, DESCRIPTION, or setup.py are not CITATION.cff files either, even though they may carry overlapping metadata -- they follow their own ecosystem-specific schemas, not the Citation File Format specification.
Editorial commentary
The Citation File Format (CITATION.cff) is a plain-text, YAML-based metadata schema for describing how to cite a piece of software or a dataset. A conformant CITATION.cff file sits in the root of a repository and records structured citation metadata — authors (ideally with ORCID iDs), title, version, release date, identifiers such as a DOI, and licence — so both humans and tooling can generate a correct, consistent citation instead of guessing from a README.
The format is maintained by the citation-file-format project, with development support credited to the German Aerospace Center’s (DLR) Institute for Software Technology, the Netherlands eScience Center, and the Software Sustainability Institute. The current schema version is 1.2.0.
The problem it solves
Before CITATION.cff, ‘how to cite this’ guidance for software lived, if it existed at all, as inconsistent free text scattered across READMEs, wikis, or nowhere. That text couldn’t be parsed by GitHub, Zenodo, reference managers, or citation-graph services, so software citations in papers were frequently incomplete, inconsistent, or missing a version number entirely — undermining the specificity and identification that citation is supposed to provide.
How it is used operationally
GitHub: when a repository’s default branch contains a CITATION.cff, GitHub parses it automatically and displays a ‘Cite this repository’ panel on the repo page, offering a ready-made APA-style citation and a BibTeX snippet.
Zenodo: when a repository is archived through the GitHub-Zenodo integration, Zenodo reads CITATION.cff metadata (authors, title, version) to pre-populate the archive record before minting a DataCite DOI for that specific release.
cffconvert: a command-line tool that converts a CITATION.cff into other formats — BibTeX, RIS, CodeMeta, EndNote, and schema.org JSON-LD among them — so the same source-of-truth metadata can feed multiple downstream systems without manual re-entry.
How it relates to the rest of the software-citation stack
CITATION.cff is the practical, machine-readable implementation layer underneath two higher-level standards. The FORCE11 Software Citation Principles (2016) establish why and what should be cited — importance, credit and attribution, unique identification, persistence, accessibility, and specificity down to the version. The FAIR4RS Principles (2022) extend the FAIR data principles to research software itself. A well-formed CITATION.cff operationalises both at once: it makes citation metadata machine-actionable (satisfying ‘unique identification’ and ‘accessibility’ from the Software Citation Principles) and improves a software repository’s Findability and Reusability under FAIR4RS. It also underpins the software paper workflow used by journals such as JOSS (Journal of Open Source Software), which expects the software under review to carry clear, citable metadata before a paper about it can be accepted.
What this means for a researcher or research office
Assessment and credit: a repository’s CITATION.cff is what lets downstream systems (GitHub’s citation panel, Zenodo, citation-graph tools) generate a correct, version-specific citation that a researcher can point to in a CV, grant report, or data management plan (DMP) as evidence of a discrete, citable research output — rather than software credit being folded invisibly into the paper that happens to describe it.
DMPs: a DMP addressing software outputs should state whether the software will ship a CITATION.cff, which repository/archive it will be deposited to for a persistent identifier, and who the named authors (with ORCID iDs) will be — the same questions a DMP already asks about datasets, applied to code.
Interaction with ORCID/DataCite/Zenodo: author ORCID iDs recorded in a CITATION.cff carry through when a repository is archived to Zenodo, which mints a DataCite DOI and can push the resulting work back to each author’s ORCID record via DataCite’s auto-update integration — closing the loop from source-code metadata to a persistent, attributed, citable record.
Frequently asked questions
Do I need a CITATION.cff file, or is a ‘How to cite’ section in my README enough?
A README section is better than nothing but isn’t machine-readable: GitHub’s citation panel, Zenodo’s metadata pre-fill, and tools like cffconvert can only act on a schema-conformant CITATION.cff. If the goal is consistent, low-friction citation by others — and interoperability with archiving/identifier services — a CITATION.cff is the mechanism built for that; free text is not a substitute, it’s a fallback.
Does adding a CITATION.cff automatically register a DOI for my software?
No. CITATION.cff only describes how to cite the software; it doesn’t mint an identifier by itself. A DOI is assigned separately when the software is archived through a service such as Zenodo (commonly via the GitHub-Zenodo integration) or figshare. The CITATION.cff’s metadata simply feeds that archiving step so the resulting DOI record is accurate.
How does CITATION.cff differ from CodeMeta?
Both describe software metadata, but CITATION.cff is deliberately citation-focused and human-editable YAML, while CodeMeta is a broader JSON-LD vocabulary (built on schema.org) aimed at general software description and cross-repository interoperability. In practice they’re complementary rather than competing: cffconvert can generate a CodeMeta.json from a CITATION.cff, so a project can maintain one file and derive the other.
Should our institution’s DMP template ask researchers about CITATION.cff?
If the template already asks about software outputs and their persistent identifiers, adding a specific line item for CITATION.cff (or equivalent machine-readable citation metadata) is a low-cost way to make that expectation concrete and checkable, rather than leaving ‘how will this software be citable’ as an open-ended narrative answer.
References
- citation-file-format.github.io — Citation File Format specification and guidance (schema version 1.2.0).
- github.com/citation-file-format — reference implementation, schema, and the cffconvert tool.
Machine-readable encodings
Use in your systems
<role vocab="credit"
vocab-identifier="https://casrai.org/dictionary/"
vocab-term="Citation File Format (CITATION.cff)"
vocab-term-identifier="https://casrai.org/dictionary/term/citation-cff" />{
"@context": "https://schema.org",
"@type": "DefinedTerm",
"@id": "https://casrai.org/dictionary/term/citation-cff",
"name": "Citation File Format (CITATION.cff)",
"identifier": "https://casrai.org/dictionary/term/citation-cff",
"description": "A CITATION.cff file is a plain-text, YAML-formatted metadata file, conforming to the Citation File Format schema, placed in the root of a code (or dataset) repository to record machine- and human-readable citation information -- authors (ideally with ORCID iDs), title, version, release date, identifiers such as a DOI, and licence -- so tools and humans can produce a correct, consistent citation without guesswork.",
"inDefinedTermSet": "https://casrai.org/dictionary/domain/reproducibility-comp#set",
"url": "https://casrai.org/dictionary/term/citation-cff",
"sameAs": [],
"license": "https://creativecommons.org/licenses/by/4.0/",
"publisher": {
"@id": "https://casrai.org/#organization"
},
"author": {
"@id": "https://casrai.org/#editorial-team"
},
"datePublished": "2026-08-22T08:44:49",
"dateModified": "2026-09-04T07:25:28",
"inLanguage": "en-GB",
"isAccessibleForFree": true
}
