How citesync check works
citesync check compares eleven fields with one file, the source (CITATION.cff by default): title/name, version, authors and contributors with ORCID, licence, DOI, Software Heritage identifier (SWHID), repository URL, description, keywords and release date. When the source doesn't hold a field (pyproject.toml has no DOI), the other files that hold it must agree with each other.
Options
citesync check --source pyproject.toml # pick another source file
citesync check --root path/to/repo # check another directory
citesync check --format json # or --json; also github and sarif, see output.md
citesync check -v # also list the fields not compared and the manifests left out
citesync check -q # only errors, no summary line
citesync check --color never # or always; the default, auto, colours on a terminal
citesync rules # every rule and its severity; --format json too
Which files it reads
By default it reads every citation file present, and the package manifests and dataset files (ro-crate-metadata.json, croissant.json) at the repo root. It skips a pyproject.toml without [build-system], a private package.json, and any field in pyproject's dynamic list. -v names each manifest it skipped and why (manifest-skipped). It reads a Cargo workspace through [workspace.package]. Configuration changes the lists.
Run from a subdirectory, citesync walks up to the nearest directory with a citation file or a citesync config. It stops at the git root, so a submodule keeps its own files, and uses the git root when it found neither. File paths in findings are relative to that root. citesync config prints the root in use. --root must be a directory.
A file citesync can't read or parse is an unreadable finding. The other files are still checked against each other.
Every key in codemeta.json must be a term of the CodeMeta version its @context names, by the term list citesync vendors from codemeta-drift. A misspelt or unknown key is an unknown-term error, such as licence for license, or softwareSuggestions in a 4.0 file. A key another context the file declares may define, or any prefixed key, is a foreign-term warning; a schema: or codemeta: key passes unchecked. citesync doesn't look inside a schema.org object such as a PropertyValue, and doesn't check a 2.0 file. A key repeated in several list items, such as nick on two authors, is one finding, at the first.
How values compare
citesync treats these spellings as equal:
- SPDX ids, SPDX URLs and Zenodo's lowercase ids. A licence list reads as
A OR B. - ORCID URLs and bare iDs.
- Zenodo's
"Family, Given"and npm or Cargo"Name <email>". CFFname-particleandname-suffixcount as part of the family name. A name in one string, such as codemetanameor npmauthor, also matches given and family names written family name first, as inTu Youyouor屠呦呦. Two split names must have the same parts. - DOIs with or without
https://doi.org/, and a DOI in a codemeta.json PropertyValue. - SWHIDs by their core,
swh:1:<type>:<hash>, in any case of the hash. Qualifiers after;, such as;origin=..., don't compare, since CFF 1.2.0 takes none:writespells a SWHID in CITATION.cff without them, and elsewhere keeps them with the hash in lower case, as Zenodo requires. CFF reads theidentifiersentry of typeswh, .zenodo.json therelated_identifiersentry with schemeswhor with no scheme, and codemeta.json a SWHID inidentifier, as a string or a PropertyValue beside the DOI. - Repository URLs, read as npm's hosted-git-info reads them: with or without
git+,.git,http://orwww., as npm shorthands (github:owner/repo) or SSH remotes. A branch, tag or file page on GitHub, GitLab, Codeberg, Gitea or Bitbucket names its repository, as in…/tree/v1.0. Host names, and GitHub paths, compare in any case. - PEP 621 url labels, normalised as packaging does (
Source Code,homepage). - PEP 440 versions:
v1.2.3=1.2.3,1.0=1.0.0,0.3.1-rc.1=0.3.1rc1,1.0.0-dev.1=1.0.0.dev1. A version that isn't PEP 440 (unreleased) must match exactly.
Names and keywords compare case-insensitively. Titles and descriptions compare as written. All of them compare with whitespace collapsed and Unicode in NFC. Findings show each file's own spelling. Two config keys change how keywords compare:
keywords-case-sensitive = truecompares keywords by case too.keywords-ignore-separators = truetreatsbig-data,big_dataandbig dataas equal. Without it, the finding names such a keyword as a near miss, and write gives it the source's spelling.
A dataset file is compared like a citation file, on every field it holds.
When dataset-license is configured, dataset CodeMeta, RO-Crate and Croissant use that licence instead of the software source's. Manifests are compared on version, authors' names (and npm contributors' names), licence, repository URL and keywords. They aren't compared on name or description. npm's and Quarto's one author is compared with the first author, and an author list there, in package.json or a Quarto _extension.yml, makes the file unreadable.
Findings and exit codes
Each finding is a line, file:line:column: severity[rule] field: message, with a help: line under it that says what to do. The line and column point at the key the finding is about; a finding with no such key, such as a file citesync can't read at all, names the file alone. A line after the findings counts them. When check fails, a last line counts the errors citesync write would fix:
.zenodo.json:2:1: error[unreadable] Expecting property name enclosed in double quotes
help: Fix the file so its parser accepts it.
codemeta.json:3:3: error[version-mismatch] version: '2.0.0', CITATION.cff has '1.0.0'
help: Make the file agree with the source, or the other way round if the source is wrong.
2 errors, 0 warnings in 3 files
1 fixable with `citesync write`
A keyword finding between citation files names the words that are missing and extra, not both lists.
On a terminal the severity is in colour. NO_COLOR turns colour off. FORCE_COLOR turns it on anywhere, and FORCE_COLOR=0 or false turns it off. NO_COLOR wins. --color always or never wins over both.
A config error names the bad entry first and suggests the closest valid one. An ignore entry that matched no finding prints a warning to stderr, unless you pass -q.
citesync rules lists every rule id and its severity. rules.md says how to fix each one.
| Exit | When |
|---|---|
| 0 | no error finding: warnings and info don't fail a run |
| 1 | an error finding, an unreadable file included |
| 2 | usage error: an unknown command or option, an option that doesn't go with another, or an unknown rule for explain. stdout is empty; stderr prints the usage and says why |
| 3 | citesync couldn't run: a bad config, a missing source file, a file it can't write, or an internal error. stdout is empty and stderr says why, or with --json the report holds the error. A missing source names the root it looked in |
| 130 | interrupted with Ctrl-C. Files write moved into place before stay written. The command then ends by SIGINT, as Ctrl-C does, so a shell loop around it stops too |
The JSON, GitHub and SARIF formats are in output.md.
Require selected fields
Set required-fields to fail check when selected files omit values.
The check uses CodeMeta terms and the pinned format mapping. It reports missing values even when the source also lacks them.
Defaults still allow omissions, and write still preserves them.