FAIR principles for research software, explained

The FAIR principles were published in 2016 as guidance for scientific data: data should be findable, accessible, interoperable and reusable, by people and by machines. They spread quickly into funder policies and data management plans. Software was mentioned, but the principles were written with datasets in mind.

Code is different from data in a few ways that matter. It is executable, it has versions that change behaviour, and it depends on a stack of other software. So a working group set out to adapt FAIR for research software. The result, usually called FAIR4RS, is a short list of principles that is worth knowing even if no one has asked you to comply with it yet.

What is FAIR4RS?

FAIR4RS is a version of the FAIR principles rewritten for research software. It came out of a working group convened jointly by the Research Data Alliance, FORCE11 and the Research Software Alliance, and the principles were published in 2022 after a period of community consultation.

The structure follows the original: four letters, each with a few numbered sub-principles. The wording is changed where software needs it. For example, the original talks about data and metadata. FAIR4RS adds explicit points about versions, about components at different levels of granularity, and about software that depends on other software.

It helps to be clear about what FAIR4RS is not. It is not a quality standard. Code can be perfectly FAIR and still be wrong. It is also not a demand that everything be open. Accessible means retrievable through a clear and standard route, which can include authentication where that is justified.

What does findable mean for code?

Findable means someone can locate a specific version of your software and know what it is. In practice that comes down to identifiers and metadata.

• A persistent identifier. A repository URL is not persistent. Repositories move, get renamed or deleted. A DOI from an archive such as Zenodo is designed to last.
• Distinct identifiers per version. FAIR4RS asks that different versions get different identifiers. Version 1.2 and version 2.0 may give different results, so a paper needs to point to the one that was used.
• Rich metadata. Name, authors, description, keywords, language, license, related publications. This is what search engines and indexes read.
• Metadata that includes the identifier. The record describing the software should carry its own DOI, so the two do not drift apart.

The principles also mention components. A large package may have modules that are reused on their own, and it can make sense to identify those separately. For most research projects one identifier per release is enough.

If you have not archived code before, our guide to archiving code with a DOI walks through the steps.

What does accessible mean for code?

Accessible means that once someone has the identifier, they can retrieve the software using an open, standard protocol, and that the metadata stays available even if the software itself does not.

HTTPS and git both count as open protocols. The point is that nobody should need special tools or a personal email exchange just to download the code. Where access has to be controlled, for example because of export rules or third party licensing, the route to request access should be stated clearly.

The second part is easy to overlook. Repositories disappear. If the code is removed, a reader should still be able to find the metadata record and learn what the software was, who made it and why it is no longer available. Archives handle this for you. A personal web page does not.

Long term preservation services such as Software Heritage add another layer by archiving public source code repositories at scale. Deposit there is not a replacement for a versioned release with a DOI, but it is a useful safety net.

What does interoperable mean for code?

Interoperable means your software works with other things through shared formats, interfaces and standards. For data, this is mostly about vocabularies. For software, it is about how the code reads and writes data and how it is called.

• Read and write common file formats used in your field, rather than a private format only your scripts understand.
• Document inputs and outputs: what columns, units, encodings and file types are expected.
• Expose a stable interface, whether that is a command line, a function API or a web service.
• Reference the other software and data you depend on, with versions. FAIR4RS calls these qualified references.

A small analysis script does not need a formal API. But it does benefit from accepting a standard format and writing results in one. That alone makes it far easier for someone to slot your code into their own pipeline.

What does reusable mean for code?

Reusable means someone else can understand, run and legally build on your software. This is where FAIR4RS is most concrete.

• A clear license. Without one, others have no legal right to reuse the code. Sites like choosealicense.com help, and we cover the choices in choosing a licence for research code.
• Provenance. Who wrote it, when, from what earlier work, and with what funding. A changelog and an authors list cover most of this.
• Dependencies with versions. A lockfile, environment file or container definition.
• Community standards. Follow the conventions of your language and field for packaging, layout and documentation.

Reuse also depends on things the principles do not spell out, like tests and a README that a stranger can follow. FAIR gives you the minimum. Good practice fills in the rest.

What does a FAIR repository look like in practice?

A reasonable FAIR baseline for a research code repository is short. Most of it is files you can add in an afternoon.

analysis-project/
  README.md          # what it does, how to run it, inputs and outputs
  LICENSE            # an OSI-approved license
  CITATION.cff       # machine-readable citation metadata
  CHANGELOG.md       # what changed between versions
  environment.yml    # dependencies with versions
  src/
  tests/

The CITATION.cff file follows the Citation File Format. It holds the title, authors, version, license and DOI in a plain text file that both humans and tools read. Some code hosting platforms show a citation box based on it, and archives can import from it.

Then, for each release you want to cite:

1. Tag the version in git.
2. Archive the tagged release in a repository that issues a DOI.
3. Update the version and DOI in your citation metadata.
4. Cite that DOI in the paper's code availability statement.

How FAIR does your code need to be?

As FAIR as its likely reuse. FAIR is a direction, not a pass or fail test, and the effort should match the software.

Type of code	Reasonable FAIR target
One-off analysis behind a paper	Archived release with DOI, license, README, pinned dependencies
Lab tool used across projects	All of the above, plus citation metadata, changelog, tests, documented inputs and outputs
Package for a wider community	All of the above, plus stable interfaces, packaging in a standard registry, contribution guide

Do not let the principles become a reason to avoid sharing. Messy code that is archived, licensed and described is more useful than tidy code that never leaves your laptop.

Where do the principles get vague?

A few parts of FAIR4RS leave room for judgement, and it is fine to say so.

Granularity is one. Should a single function get an identifier? Usually not. Identify the unit that people cite and download. Community standards are another. Some fields have strong conventions for formats and metadata. Others have very few, and you will have to pick something sensible and document it.

Machine actionability is the third. The original FAIR principles emphasise that machines should be able to find and use resources. For software, that mostly means structured metadata in standard formats. You do not need to build anything special. Using CITATION.cff, a recognised license identifier and a proper archive gets you most of the way. The GO FAIR initiative keeps a reference copy of the original principles if you want to compare the wording.

What to do this week

Pick one repository that sits behind a published or submitted paper and work through this list:

• Add a license if there is none.
• Add a CITATION.cff with authors, title and version.
• Write or update the README so it states inputs, outputs and how to run the main analysis.
• Pin dependencies in an environment file or lockfile.
• Tag a release, archive it and record the DOI in the citation file and the paper.

That is most of FAIR4RS in practice. If you are planning a new project, write these steps into a software management plan so they happen from the start rather than at submission.