Rules
<!-- Generated from src/citesync/rules.py by uv run python -m citesync.rules > docs/rules.md. Edit that file, not this one. -->
citesync rules lists these rules, and citesync explain <id> prints one section.
The eleven rules from name-mismatch to date-mismatch compare a field with the source. When the source doesn't hold the field (pyproject.toml has no DOI), the other files that hold it must agree with each other.
metadata-omitted
An imported metadata value cannot be represented safely. Severity: warning.
Legacy Core Metadata License text is not assumed to be an SPDX expression. Values that cannot be represented are omitted with this notice; import-only metadata is never rewritten.
To fix: Add an explicit supported value in the source metadata, then generate the citation files again.
name-mismatch
The title differs from the source's. Severity: error.
CFF title and CodeMeta and Zenodo name/title compare as written, with whitespace collapsed. Manifests are not compared: a manifest name is a package id, and a Quarto title a display title.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
version-mismatch
The version differs from the source's. Severity: error.
Semver pre-release tags are read as PEP 440 first, so 0.3.1-rc.1 equals 0.3.1rc1.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
author-mismatch
The authors differ from the source's. Severity: error.
Citation files must list the same people in the same order, with equal ORCIDs where both have one. Names compare case-insensitively. Zenodo's Family, Given and npm, Cargo or Typst Name <email> count as names. Manifests are compared on names only. npm's one author and Quarto's one author string are compared with the first author.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
contributor-mismatch
The contributors differ from the source's. Severity: error.
Compared as authors are. Only the people count, not a CodeMeta Role or a Zenodo contributor type. CITATION.cff, pyproject.toml and Cargo.toml have no contributor list. npm's contributors is compared on names.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
license-mismatch
The licence differs from the source's. Severity: error.
SPDX ids, SPDX URLs and Zenodo's lowercase ids are the same licence, compared case-insensitively. A list of licences reads as A OR B.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
doi-mismatch
The DOI differs from the source's. Severity: error.
DOIs compare case-insensitively, with or without https://doi.org/. Manifests have no DOI.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
swhid-mismatch
The Software Heritage identifier (SWHID) differs from the source's. Severity: error.
CFF identifiers of type swh, Zenodo related_identifiers with scheme swh (or no scheme), and a SWHID in CodeMeta identifier, as a string or a PropertyValue beside the DOI. Only the core, swh:1:<type>:<hash>, compares, with the hash in any case: qualifiers after ; are ignored, since CFF 1.2.0 takes none. Manifests have no SWHID.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
repository-mismatch
The repository URL differs from the source's. Severity: error.
git+, .git and a trailing slash are removed first, and npm shorthands and SSH remotes are read as https URLs.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
description-mismatch
The description differs from the source's. Severity: error.
Compared as written, with whitespace collapsed. Manifests are not compared, because a manifest description is a one-line summary, not an abstract.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
keywords-mismatch
The keywords differ from the source's. Severity: error.
Citation files must hold the same keywords, in any order. A manifest's keywords are checked by keywords-not-subset instead. Keywords that differ only in separators (big-data, big_data, big data) are named in the message, and write gives them the source's spelling. keywords-ignore-separators = true makes them equal. Against Cargo.toml they are always equal, because crates.io refuses a keyword with a space.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
date-mismatch
The release date differs from the source's. Severity: error.
CFF date-released, CodeMeta datePublished and Zenodo publication_date compare as YYYY-MM-DD. A time after the date is ignored. Manifests have no release date.
To fix: Make the file agree with the source, or the other way round if the source is wrong.
keywords-not-subset
A manifest has a keyword the citation file doesn't. Severity: error.
A manifest's keywords must all be in the citation file's, whichever of the two is the source. A citation file can hold more keywords than a registry allows (crates.io allows five). Keywords that differ only in separators (big-data, big_data, big data) are named in the message, and write gives them the source's spelling. keywords-ignore-separators = true makes them equal. Against Cargo.toml they are always equal, because crates.io refuses a keyword with a space.
To fix: Add the keyword to the citation file, or remove it from the manifest.
dataset-type-mismatch
The dataset CodeMeta file does not declare the Dataset type. Severity: error.
The configured or discovered dataset CodeMeta file must declare Dataset in its JSON-LD type. The type alias, schema:Dataset, full schema.org IRIs and lists containing Dataset also pass.
To fix: Run citesync write to set the dataset resource type.
context-mismatch
codemeta.json's @context is not the configured CodeMeta version. Severity: error.
With codemeta-version unset, the rule is silent: CodeMeta 2.0, 3.0, 3.1 and 4.0 all pass.
To fix: Change the @context to the configured version, or set codemeta-version in the config.
role-dangling
A CodeMeta Role in codemeta.json points at a person who isn't listed. Severity: warning.
A Role entry in codemeta.json's author or contributor list names its person by ORCID in schema:author. credit-matrix writes CRediT roles this way. The rule warns when no Person in either list has that ORCID as its @id, for example after someone is replaced. write never changes a Role.
To fix: Add the person back, point the Role at their ORCID, or remove the Role.
unknown-term
A key in codemeta.json isn't a term of its CodeMeta version. Severity: error.
Every key in codemeta.json, at any depth, must be a property term of the CodeMeta version its @context names, a JSON-LD keyword such as @type, the alias type or id, or a key under the schema: or codemeta: prefix, which passes unchecked. The term lists come from the vendored codemeta-drift export: 3.0 and 3.1 share one list, 4.0 has its own, so softwareSuggestions is unknown there. A 2.0 file isn't checked. The message names the CodeMeta version that has the term, or else suggests the closest one. write never changes the key.
To fix: Fix the spelling, or declare the context the term comes from in @context.
foreign-term
A key in codemeta.json may come from a context other than CodeMeta. Severity: warning.
A key that isn't a CodeMeta term warns instead of failing when another context the file declares may define it: a key with any prefix, such as ex:grant, even one the file doesn't declare, or a full IRI; a term an inline @context object defines; any key when @context also names a remote context that isn't CodeMeta or sets @vocab; and any key in an object with its own @context. citesync reads no context from the network, so it can't tell whether that context defines the key.
To fix: Check the key is meant to come from that context, or use the CodeMeta term.
version-behind-tag
The source's version is older than the repo's newest git tag. Severity: warning.
Tags that read as a PEP 440 version count, with or without a leading v, so v0.2.0 is newer than 0.1.0. Outside a git repository, or when no tag reads as a version, the rule is silent. write never changes the version for this warning.
To fix: Bump the version in the source and run citesync write, so the next release isn't cited as the last one.
zenodo-license-list
CITATION.cff's license is a list, and Zenodo would refuse the release. Severity: error.
Without a .zenodo.json, Zenodo's GitHub integration reads CITATION.cff and takes its license as one string. A list, even of one licence, fails the release with "Citation metadata load failed". Checked only when no .zenodo.json sits beside CITATION.cff.
To fix: Give one licence in CITATION.cff, or add a .zenodo.json, which Zenodo reads instead.
zenodo-drops-field
Zenodo won't carry this CITATION.cff field into the record. Severity: warning.
Without a .zenodo.json, Zenodo reads CITATION.cff but leaves out identifiers and references. It takes the DOI from the release, and the version and date from the tag. Checked only when no .zenodo.json sits beside CITATION.cff.
To fix: Add a .zenodo.json with the field's Zenodo form (related_identifiers, references) if the record needs it.
file-missing
A file listed under files doesn't exist. Severity: error.
Only for a citation file named in the files setting. Without that setting, citesync checks the citation files that are there. citesync write creates codemeta.json from the source, with the configured codemeta-version, else 3.0. It also creates .zenodo.json from the source, with upload_type set to software. Use citesync init to create a CITATION.cff.
To fix: Run citesync write to create codemeta.json or .zenodo.json; use citesync init for CITATION.cff, or take the file off files.
required-field-missing
A field listed under required-fields has no normalized value in its selected file. Severity: error.
Each configured path must exist and hold a non-empty normalized value for every listed CodeMeta term. The check uses the pinned mapping, even when discovery excludes the file or a manifest is private. A missing file reports one finding per required term. An unreadable file reports unreadable instead. A missing source or explicitly listed manifest still stops discovery with exit 3 before this check runs. The source need not know the value. identifier requires a DOI, not an arbitrary identifier. This validates presence, not factual accuracy or full format conformance. write preserves omitted fields and does not fill them to satisfy this rule.
To fix: Set the verified value in the selected file, or remove the requirement if it does not apply.
export-stale
A file listed under exports is missing or differs from what the source gives. Severity: error.
Each exports entry is a citation made from the source: BibTeX (.bib), CSL-JSON (.csl.json), APA 7 (.apa.txt), schema.org JSON-LD (.jsonld), DataCite XML (.datacite.xml), RIS (.ris) or EndNote (.enw). The file must equal what citesync export prints for its format, with CRLF line ends read as LF. A term the source doesn't hold comes from the first other file that holds it. write rewrites the whole file, so don't edit an export by hand.
To fix: Run citesync write; for an export that can't be made, set the missing field in the source. A link or folder at that path, which write won't replace, has to move first.
unreadable
citesync could not read the file. Severity: error.
The file could not be opened or parsed, is not UTF-8, or points outside the repo root through a symlink. Or its content has a shape its format doesn't allow, or a format version citesync doesn't read: CFF other than 1.2.0, or a codemeta.json whose @context is not CodeMeta. The finding gives the parser's message, with a line and column when the parser reports them. The other files are still checked against each other. When the source is unreadable, each field it has a place for is not-checked. This rule can't be ignored.
To fix: Fix the file so its parser accepts it.
manifest-skipped
A manifest at the repo root was left out, because it isn't released. Severity: info.
A pyproject.toml without [build-system] and a package.json with "private": true aren't packages anyone installs, so citesync doesn't compare them. Text, GitHub and SARIF output show it only with --verbose.
To fix: List it under manifests to check it anyway.
not-checked
A field was not compared. Severity: info.
Either no file holds a value for the field, or the source could not be read. It never changes the exit code. Text and GitHub output show it only with --verbose.
To fix: Add the field to the source if the files should carry it.