citesync

Software citation metadata.

On this page

Changelog

All notable changes to this project are documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Documentation code examples have keyboard-accessible copy buttons and feedback when copying is blocked.
  • The website publishes an accessibility statement, with keyboard instructions and testing limitations. Documentation links include page-specific social previews.

Changed

  • The playground and documentation use a shared green design with local IBM Plex Sans fonts. File actions sit above the preview; documentation search sits beside the article on desktop, with compact navigation on phones (playground guide).

Fixed

  • Playground file selectors display their dropdown arrows under the website's Content Security Policy.

0.6.0 - 2026-11-14

Added

  • The documentation website includes installation, playground guides and reference pages beside the playground. Search the full documentation without leaving the website; guides remain readable without JavaScript.
  • The playground's Field lookup searches the pinned CodeMeta mappings across six metadata formats, including fields those formats cannot represent (playground).
  • Shared website links show a social card with an example of package metadata converted to CITATION.cff.
  • Opt-in required-fields checks report missing values in selected metadata files as required-field-missing errors. Missing files and values fail even when the source lacks the facts. Default omission handling and write behavior stay the same.
  • dataset-codemeta and dataset-license (plus --dataset-codemeta and --dataset-license) write and check a dataset CodeMeta file (@type: Dataset, defaulting to dataset.codemeta.json) for sourceledger release --codemeta, keeping code and dataset licences separate, including RO-Crate and Croissant checks and optional required-field checks (configuration).

Changed

  • On the same v0.5.0 metadata, check averaged 60.2 ms versus 61.5 ms in 0.5.0 (about 2% lower). Both used Python 3.14.4 with JIT disabled and 30 runs after three warm-ups; shared-host variation exceeds the difference.

Fixed

  • Both pre-commit hooks now recognize dataset.codemeta.json, including nested paths. For custom names, use always_run: true (hook setup).

  • CLI help and finding links open the on-site documentation.

  • Existing dataset CodeMeta files now have their Dataset resource type checked and repaired by write (configuration).

  • Software citation exports no longer inherit a dataset's licence or other fields when the software source lacks them. Dataset files supply export values only when explicitly selected as the source.

  • Choosing an output format stays selected while the preview updates.

  • Documentation navigation preserves command names and marks the current guide or section. Reference tables scroll on narrow screens without splitting filenames; field lookup starts with a search prompt.

0.5.0 - 2026-11-10

To upgrade from 0.4.0:

  • citesync needs Python 3.13 or newer, the git hooks included.
  • A run that couldn't finish exits 3, not 2: a script that tests for 2 tests for 3. In --json output, version is now schema_version, and every report has errors (output).
  • check can fail on a codemeta.json that passed before: an unknown key is now an unknown-term error, and typst.toml keywords compare with their separators. ignore = ["unknown-term"] and keywords-ignore-separators = true keep the old behaviour (configuration).

Added

  • check reports a codemeta.json key that isn't a term of its CodeMeta version as an unknown-term error, with the closest term or the version that has it, and one another declared context may define as a foreign-term warning. The term lists come from codemeta-drift's export, for CodeMeta 3.0, 3.1 and 4.0 (checks). A codemeta.json that passed before can now fail; ignore = ["unknown-term"] in the config turns the check off.
  • The playground makes incomplete R DESCRIPTION, Julia Project.toml, Typst typst.toml and Quarto _extension.yml templates beside the Python, Rust and JavaScript ones (playground).
  • check compares ro-crate-metadata.json and croissant.json, as sourceledger's release writes them, with the source on every field, from codemeta-drift's new rows. It finds them at the repo root, or under manifests, write never changes them, and init takes nothing from them (dataset files).
  • citesync export --format ris and --format endnote print a RIS or EndNote tagged record of type computer program, each tag where codemeta-drift's rows put it. List a .ris or .enw file under exports to keep it in step; the playground offers both (citation exports).
  • citesync export --format datacite prints DataCite Metadata Schema 4.7 XML (citation.datacite.xml, resource type Software). List a .datacite.xml file under exports to have write keep it in step and check report it as export-stale. It needs a DOI, an author, a publisher and a release year, and says which source field to set when one is missing. The playground offers it when the record has all four (citation exports).

Changed

  • Breaking: exit codes and JSON reports follow one convention across the tools: 0 done, 1 an error finding, 2 a usage error, 3 citesync couldn't run (a bad config, a missing source file), 130 interrupted with Ctrl-C. A run that couldn't run exited 2 before, the same code as a mistyped option. The --json report names its version schema_version, not version, and has an errors list of {message, help} objects; a run that couldn't finish prints a report with only its errors instead of a line on stderr (exit codes, JSON).
  • Breaking: typst.toml and _extension.yml are read through their own rows in the field mapping, not Cargo's and npm's. init and export now take a Quarto extension's title as its name; check still doesn't compare it. typst.toml keywords are now compared with their separators (big data is not big-data), as other manifests' are; set keywords-ignore-separators = true to keep the old leniency (plugin manifests).
  • The field mapping uses codemeta-drift 0.8.0, which adds rows for DataCite, typst.toml, Quarto extensions, RIS, EndNote, RO-Crate and Croissant among others, reads PKG-INFO's Author as a list, and mapping paths can now combine parts with + and filter on a member of a list.
  • PKG-INFO, METADATA, R DESCRIPTION and Julia Project.toml files are read through codemeta-drift's own rows for those formats, not reshaped into PEP 621 or CodeMeta first. What each one gives is unchanged, and check findings on them now carry a line number (formats).
  • The playground's input and output file lists are grouped under labelled headers, sorted by name and searchable, and Names look right closes the name split until the author names change (playground).

Fixed

  • An empty .git folder, such as a stray /tmp/.git, no longer marks a repo root. Like git, citesync now needs a .git folder with HEAD, or a .git file. Before, a stray one moved the root, and GitHub and SARIF output gave paths relative to the wrong folder.
  • citesync init and export --format cff name each manifest they skipped, such as a private package.json, and say how to read it. Before, its licence and keywords were left out without a word (init).
  • A codemeta.json that holds its version as softwareVersion is checked against the source, and write updates it there. Before, its version was never compared.
  • The schema.jsonld export writes license only as a URL: the SPDX page for a single licence id, or the URL the source gives. A LicenseRef- id, an expression such as MIT OR Apache-2.0 and other text are left out instead of written as a made-up or non-URL value.
  • A PKG-INFO or METADATA Author such as Datadog, Inc. is one author, not two: a company suffix stays with the name before it, and an et al. entry is dropped (formats).
  • init reads the manifests the manifests setting lists, so a Quarto extension under _extensions/<name>/ can give the new CITATION.cff (init).
  • A codemeta.json with no @context is reported as having none, not as @context None is not CodeMeta.
  • write --diff -q no longer prints the would fix count on stderr.

Removed

  • Breaking: Python 3.12 is no longer supported. citesync needs Python 3.13 or newer.

0.4.0 - 2026-11-01

Added

  • citesync export --format apa|bibtex|csl-json|jsonld prints a citation made from the source. List files under exports to have write keep them in step, check report a stale one, and the pre-commit hooks run when one changes (citation exports).
  • citesync export --format cff|codemeta|zenodo prints the CITATION.cff, codemeta.json or .zenodo.json citesync would make from the source, without writing it (citation files).
  • APA 7 references and schema.org JSON-LD for websites, in the CLI and the playground.
  • Check and update Typst typst.toml and Quarto _extension.yml plugin manifests, so a release moves their version with CITATION.cff; init reads them too (plugin manifests).

Changed

  • The field mapping uses codemeta-drift 0.5.0, with its schema 1.4 contract and rows for PKG-INFO, R DESCRIPTION, Julia and BibTeX. Its paths for the six formats citesync already read are unchanged.
  • PKG-INFO and METADATA take the description from Summary only, not the README in Description or the body, and the repository from a Project-URL labelled source, repository, sourcecode or github before Home-page (distribution metadata).
  • BibTeX and CSL-JSON citation keys come from the title, such as credit-matrix, instead of software.
  • BibTeX citations are biblatex-software @software entries with the version, licence, DOI, SWHID, abstract and keywords, named as codemeta-drift's bibtex rows name them. Plain BibTeX styles print them as @misc (citation exports).
  • An R DESCRIPTION gives the citation name as Package: Title, as cffr and codemetar do, instead of the title alone (R and Julia imports).
  • A Julia Project.toml no longer gives a description or licence: the format has neither field, so keys added by hand aren't read (R and Julia imports).

Fixed

  • citesync init keeps every author when package.json is the source and codemeta.json or .zenodo.json lists more than one (init).
  • citesync write names the file it can't write and why, such as one in a read-only folder, instead of reporting an unexpected error (writing).
  • An author list in package.json is reported as unreadable instead of being skipped without a finding (checks).
  • citesync init stops when the source named with --source or source is missing, instead of building CITATION.cff from another file (init).

0.3.0 - 2026-11-01

Added

  • Generate citation files in the browser playground from an existing metadata file or basic project details, with live previews, input detection and editable author names. Export CITATION.cff, CodeMeta, Zenodo metadata, BibTeX and CSL-JSON; Python, Rust and npm outputs are labelled as incomplete package templates (guide).
  • Import Python PKG-INFO/METADATA, R DESCRIPTION and Julia Project.toml/JuliaProject.toml in the CLI and playground without executing package code. Imported files remain read-only; unsupported or omitted values are reported (supported files).
  • Create a missing .zenodo.json with citesync write when files lists it. Set zenodo-contributor-type to supply a default for new contributors; existing types are preserved (configuration, writing).
  • Use the contribution handoff guide for linked CodeMeta people and roles from CRediT Matrix, and the Pandoc guide for software citations from CSL-JSON or BibTeX.
  • A Matrix consumer check runs the published Credit Matrix 0.10.0 CLI through citesync write/check, including linked roles, local identities and explicit Zenodo contributor types.

Changed

  • The field mapping uses codemeta-drift 0.4.0, with original crosswalk cells and its schema 1.3 contract. Field paths remain unchanged.
  • The playground uses larger text for file previews, code snippets, hints and footer links.

Fixed

  • CodeMeta person identifiers that are not ORCIDs no longer overwrite ORCIDs in other files. Writes preserve these identifiers and refuse to remove a person if that would discard them. Both id/@id and type/@type spellings are supported (contribution guide).
  • citesync write preserves a byte order mark at the start of CITATION.cff (writing).

0.2.0 - 2026-10-30

To upgrade from 0.1.0:

  • citesync check has five new error rules: contributor-mismatch, date-mismatch, swhid-mismatch, zenodo-license-list and file-missing. To turn any of them off for now, list it under ignore (docs/rules.md).
  • codemeta-version no longer defaults to 3.0. To keep checking codemeta.json's @context as before, set codemeta-version = "3.0".
  • Use citesync through its command line or the pre-commit hook. Its Python modules are internal and may change in any release.
  • write-manifests takes only version, author, contributor, license, codeRepository and keywords, the fields a manifest holds. Take any other field off the list.
  • The text output changed: each finding starts with file:line:col and has a help: line under it, a failing check ends with an N fixable line, and citesync write ends with N fixed, M left in K files. In GitHub output, each annotation ends with its help: line and the ::notice:: line gives write's new count, so scripts should read --format json instead (docs/output.md).

Added

  • citesync init writes a CITATION.cff from codemeta.json, .zenodo.json and the package manifests when a repo has none. It passes citesync check when those files already agree, and citesync write fixes the rest (docs/init.md).
  • Contributors are compared across codemeta.json, .zenodo.json and package.json, the same way as authors (contributor-mismatch).
  • Release dates are compared across CITATION.cff, codemeta.json and .zenodo.json (date-mismatch).
  • Software Heritage identifiers (SWHIDs) are compared across CITATION.cff, codemeta.json and .zenodo.json, and citesync write fixes them (swhid-mismatch, docs/check.md).
  • version-behind-tag warns when the source's version is older than the repo's newest git tag.
  • --format sarif prints a SARIF log that GitHub code scanning can upload.
  • citesync write creates codemeta.json when the files setting lists it and it doesn't exist yet.
  • citesync --help lists the exit codes and where config is read from. citesync with no command prints the help.
  • Two rules for repos where Zenodo reads CITATION.cff: zenodo-license-list and zenodo-drops-field.
  • A keyword that differs from another file's only in hyphens, underscores or spaces is named as such, and citesync write gives it the source's spelling. keywords-ignore-separators = true treats such keywords as equal.
  • A failing citesync check says how many findings citesync write would fix, and citesync write how many it fixed and left (docs/check.md).
  • -v names each manifest check left out, and why (manifest-skipped). citesync config prints the repo root in use.
  • --color auto|always|never sets colour whatever NO_COLOR and FORCE_COLOR say, and -V is short for --version.
  • Each finding on a key gives the key's line and column, so an editor or code scanning can jump to it (docs/output.md).
  • A mistyped rule id, --format value or write-manifests field gets a "did you mean" suggestion. On Python before 3.14, option values get none.

Changed

  • Breaking: codemeta-version has no default. When it's unset, any CodeMeta version passes and citesync write leaves @context alone.
  • Breaking: a file listed in the files setting that doesn't exist is a file-missing error. 0.1.0 skipped it.
  • The field mapping comes from codemeta-drift 0.3.0, which adds contributors, release dates and SWHIDs.
  • citesync check starts about a third faster.
  • Breaking: write-manifests = "all" means the six manifest fields, and naming any other field is a config error.
  • A keyword finding between citation files lists the missing and extra words, not both files' lists.
  • A missing source file names the directory citesync looked in. Run outside any citation files, citesync uses the git root, and --root must be a directory.
  • A bad ignore entry is named in the error, and an unquoted codemeta-version = 3.0 says to write it as a string (docs/config.md).
  • The warning about an unused ignore entry is quiet under -q.

Fixed

  • citesync write dropped an author's ORCID when the source renamed them and had no ORCID for them. It now leaves that file's authors for you to edit (docs/write.md).
  • citesync write wrote a CITATION.cff entity (an author with only a name) to codemeta.json as a Person. It's now an Organization.
  • citesync write reformatted the existing entries of a JSON author list when it added an author.
  • python -m citesync failed with "No module named citesync.__main__".
  • With doi: "" in CITATION.cff, the DOI under identifiers was ignored.
  • codemeta.json entries written with type and id instead of @type and @id were ignored.
  • A name in one string, such as codemeta.json name, written family name first (Tu Youyou, 屠呦呦) was an author-mismatch against CITATION.cff's given and family names, and citesync write rewrote it.
  • A title with an accent typed two different ways didn't match itself.
  • citesync write folded an author's name-particle and name-suffix into family-names when it changed the given name.
  • GitHub annotations didn't attach to their files when the root was a subdirectory of the git repo.
  • codemeta.json keywords given as one string weren't split on full-width (,) or ideographic (、) commas.
  • A manifest or .zenodo.json that starts with a byte order mark gave a confusing parser error.
  • A file behind a symlink that points out of the repo was read, and write could change it. It's now unreadable.
  • Control characters in a file could retitle the terminal or hide lines. They now print as \xNN.
  • Printing non-ASCII text to a stdout that isn't UTF-8, such as a Windows pipe, crashed.
  • Some inputs made citesync check run for minutes, such as an author string with a long run of spaces or a keyword list thousands long.
  • A repository URL with whitespace before a trailing slash, such as https://example.org/r /, kept that whitespace when read.
  • citesync write dropped the comments above a --- line at the top of CITATION.cff.
  • An author with an ORCID and no name was written to pyproject.toml, Cargo.toml or package.json as an empty entry, one more on each run. citesync write now leaves that list for a hand edit and says why.
  • citesync write turned every line end of a file with both LF and CRLF line ends into CRLF, even when it changed nothing else. It now keeps the more common one (docs/write.md).

0.1.0 - 2026-10-29

Added

  • citesync check: compares title/name, version, authors with ORCID, licence, DOI, repository URL, description and keywords across CITATION.cff, codemeta.json, .zenodo.json, pyproject.toml, Cargo.toml and package.json, with any of them as the source. Exit 0 when they agree, 1 on an error finding, 2 when citesync couldn't run (a bad config or option, a missing source file, an internal error).
  • Each finding names its rule, such as version-mismatch or keywords-not-subset, and has a severity. citesync rules lists the rules and citesync explain <rule> describes one; docs/rules.md has them all.
  • A file citesync can't read or parse is an unreadable finding, with the parser's line and column when it gives them, and the other files are still checked against each other.
  • Output as text, JSON (--format json or --json) or GitHub workflow annotations (--format github). Text is coloured on a terminal (NO_COLOR and FORCE_COLOR are honoured) and ends with a summary line; --quiet prints only errors. JSON is one document with a version, the tool, a summary and the findings, each with its rule, severity, help, a link to the rule's docs and its position when known. GitHub output ends with a notice that counts the findings. JSON always lists every finding, whatever -q or -v say.
  • A JSON compatibility policy: a minor release may add rule ids and optional fields, so ignore what you don't know; removing or retyping a field bumps the report's version, in a major release.
  • citesync --version.
  • Without --root, citesync walks up from the current directory to the nearest directory with a citation file or a citesync config, stopping at the git root.
  • A role-dangling warning for a CodeMeta Role in codemeta.json's author or contributor list, such as a CRediT role from credit-matrix, whose schema:author ORCID no listed person has. write keeps Roles as they are.
  • A pre-commit hook, citesync, for prek or pre-commit. It runs citesync check when a commit changes a citation file, a package manifest or citesync's config, at any depth, and fails the commit on an error finding.
  • A manual-stage hook, citesync-write, that runs citesync write when you ask for it.
  • ignore in the config drops the findings of the rules it lists, and warns about an entry that matched nothing.
  • citesync config, and config discovery from citesync.toml, .citesync.toml, pyproject.toml, Cargo.toml or package.json. Config keys are kebab-case, such as codemeta-version.
  • The field mapping, vendored from codemeta-drift 0.1.0 with its JSON Schema.
  • An author with only a name, such as an organization, compares as a family name in CITATION.cff, codemeta.json and .zenodo.json, and write keeps it.
  • Keywords compare case-insensitively, as author names do, so LCA matches lca. Set keywords-case-sensitive = true in the config to compare them by case. codemeta.json may give them as one comma-separated string, as schema.org allows.
  • Repository URLs compare by the repository they name: http://www.github.com/Owner/Repo/tree/v1.0 matches https://github.com/owner/repo. Branch, tag and file pages count on GitHub, GitLab, Codeberg, Gitea and Bitbucket; paths ignore case on GitHub only. Findings show the URLs as written.
  • A codemeta.json identifier given as a schema.org PropertyValue is read as a DOI when its propertyID is DOI or its value or url is a DOI. Other PropertyValues, such as a SWHID or a ROR id, are skipped.
  • Versions compare as PEP 440 versions, so v1.2.3 matches 1.2.3, 1.0 matches 1.0.0 and 0.3.1-rc.1 matches 0.3.1rc1. A version that isn't PEP 440, such as unreleased, must match exactly.
  • citesync write: rewrites the citation files that disagree with the source, and the manifest fields listed in write-manifests, keeping comments, key order, formatting and CRLF line ends, and writing through symlinks. Fields a file leaves out stay out. A value a file can't hold without losing something is left for you, with the reason: a compound licence in .zenodo.json, an AND licence in CITATION.cff or codemeta.json, a version semver can't spell in Cargo.toml or package.json, a version that isn't PEP 440 in pyproject.toml, or a renamed author whose old entry holds an email or affiliation. It reports the findings left as check does, each saying what to do, and never writes an ignored finding or an unreadable file. Exit 0 when the files agree afterwards, 1 when an error finding remains, 2 when it couldn't run and wrote nothing.
  • citesync write --diff prints the edits write would make as a unified diff and writes nothing. Exit 0 when there is nothing to change, 1 when there is or when a file can't be read (listed on stderr), as ruff format --diff does.