Software metadata

Structured metadata makes your software findable, citable, and reusable. This page explains which metadata files belong in a research software repository, why they matter, and how to create, check, and maintain them. The field-by-field reference lives in the LUMC CodeMeta profile, so that this page and the profile cannot drift apart.

This page focuses on the metadata files themselves. For the surrounding decisions, see the guidance on choosing a repository and license, minting persistent identifiers, picking registries, and recording programming languages and data formats.

Quick start

Add two files to the root of your repository:

• codemeta.json — the primary metadata record, harvested by registries and archives
• CITATION.cff — a citation-specific file that GitHub and Zenodo render automatically

The LUMC rs-metadata tool creates both and checks them:

pip install rs-metadata
rs-metadata init       # writes codemeta.json, CITATION.cff, and a CI workflow
rs-metadata validate   # checks them against the LUMC CodeMeta profile

init infers what it can from your packaging metadata (pyproject.toml, package.json, DESCRIPTION, Cargo.toml, Project.toml) and the git remote, and leaves a placeholder wherever it could not. Replace every placeholder before you publish. validate reports leftovers as errors, because a placeholder is worse than a missing field: it asserts an identifier that does not exist, and registries ingest it anyway.

You can also write both files by hand. Start from the worked codemeta.json examples, or use the CodeMeta generator and cffinit.

Why metadata matters

Three purposes, in increasing order of ambition.

Citability. A CITATION.cff file enables GitHub to show a "Cite this repository" button and allows Zenodo to auto-populate citation records. Without it, users either cite only the associated paper (losing credit for the software itself) or cite the repository URL in a way that is not persistent or versioned.

Discoverability. A complete codemeta.json is harvested by Zenodo, Software Heritage, the Research Software Directory, and other archives, making your software visible in search results and institutional inventories. EDAM operation terms enable semantic discovery in bio.tools and other life-sciences registries.

Reuse. Machine-readable metadata allows automated tools to verify compatibility, resolve dependencies, and reproduce computational environments, which is the practical foundation for genuinely reusable research software.

The two files

codemeta.json

CodeMeta is a software metadata vocabulary built on schema.org and represented in JSON-LD. It is the primary record: the file registries and archives read. A working group of LUMC, Amsterdam UMC, DReaMS, and ELIXIR-NL scored five candidate standards (CodeMeta, CITATION.cff, Bioschemas, biotoolsSchema, and maSMP) against a weighted rubric that prioritized reuse over discoverability over citability; CodeMeta ranked first. See how the metadata standard was chosen for the criteria and the scores.

LUMC defines a profile of CodeMeta v3.1 — the LUMC CodeMeta profile — which sets a mandatory minimum and highlights the most useful optional fields. Any valid CodeMeta field is welcome; the profile constrains rather than restricts.

CITATION.cff

CITATION.cff is a YAML file focused on citation. GitHub renders it as a "Cite this repository" button, and Zenodo uses it to populate citation records when a release is archived. It is simpler to write than codemeta.json and is native to the GitHub interface.

It has no fields for programming language, software type, or operations, so it is not a replacement for codemeta.json. Maintain both, and keep name, version, and authors consistent between them — rs-metadata validate checks exactly that.

What goes in them

Ten fields are mandatory under the LUMC profile:

name, description, version, identifier, author, license, codeRepository, programmingLanguage, applicationCategory, and schema:featureList (what the software does, EDAM terms preferred).

A further fifteen are recommended, covering release dates, keywords and topics, documentation and issue-tracker URLs, maintainers, funding, related publications, support status, platforms, dependencies, supporting data, containers, changelogs, and continuous integration.

For what each field means, which values are accepted, and how they are constrained, see the LUMC CodeMeta profile. A few of the underlying decisions are covered elsewhere in this guide: software title, software license, persistent identifiers, and functions and operations.

Note that EDAM-typed inputs and outputs have no CodeMeta or schema.org field. If you need them recorded, define them in bio.tools (see Registering your software).

Other metadata files

Some projects carry additional machine-readable metadata alongside the two above: .zenodo.json for deposit-specific fields, biotools.json for a bio.tools entry, Dockerfile labels, or a registry-specific descriptor. These are fine to keep, but they are secondary: codemeta.json stays the record everything else is derived from, and any duplicated field must agree with it. Record which file follows which standard, and against what schema it validates, so a later maintainer knows whether a value is authoritative or a copy.

When to update

Update both files when you:

• Create a new release (version, identifier, datePublished)
• Add or change authors
• Change the license
• Move the repository
• Change the software's primary function

Validation

rs-metadata validate runs two checks:

• Schema validation — that codemeta.json conforms to the LUMC CodeMeta profile and that CITATION.cff is valid CFF 1.2.0.
• Consistency — that the shared fields (name, version, authors) agree between the two files and your packaging metadata.

Run it locally while you edit, and in CI on every push and pull request. rs-metadata init writes a .github/workflows/metadata.yml that does exactly that; the project is also published as a GitHub Action, so an existing workflow can call it directly.

Registering your software

For where to register and how to choose, see Registries. Two registries interact directly with your metadata files:

• bio.tools — a popular registry for life-sciences tools. A documented CodeMeta–biotoolsSchema crosswalk means most fields map conceptually, though the bridge tool currently registers from a GitHub repository rather than from codemeta.json. After registering, add the bio.tools ID to both files.
• Research Software Directory — the national Dutch registry. It ingests codemeta.json from GitHub automatically, so a complete file is the main prerequisite.

Tools

Further reading

• LUMC CodeMeta profile — the full field reference
• CodeMeta user guide
• CITATION.cff specification and schema guide
• EDAM ontology documentation
• bio.tools curator guide
• RDMkit — documentation and metadata