commonmeta-rs

commonmeta-rs is a Rust library to implement Commonmeta, the common Metadata Model for Scholarly Metadata. Use commonmeta to convert scholarly metadata in a variety of formats, listed below. Commonmeta-rs is work in progress, the first release was on June 17, 2026. Implementations in other languages are also available (Go, Python, Ruby).

Supported Metadata Formats

Commonmeta-rs reads and/or writes these metadata formats:

commonmeta: the Commonmeta format is the native format for the library and used internally. Later: we plan to implement this format in a later release.

Build & run

cargo build
cargo test

The commonmeta binary has eight subcommands: convert, encode, decode, install, list, push, put, and match.

# Encode/decode a Crockford base32 identifier suffix
cargo run -- encode 10.5555
cargo run -- decode 10.5555/nwbyp-29t86

# Convert a single record between formats, fetching it by DOI
cargo run -- convert 10.5555/12345678 --from crossref --to csl

# Convert a local file and write the result to disk
cargo run -- convert record.json --from commonmeta --to csl --file out.json

# Render a formatted citation (CSL style + locale)
cargo run -- convert 10.5555/12345678 --from crossref --to citation --style apa --locale en-US

# Fetch a batch of records from an API and write them as a commonmeta JSON array
cargo run -- list --from crossref --number 100 --type journal-article --file out.json

# Read metadata from a local VRAIX SQLite file
cargo run -- list crossref-2026-06-15.sqlite3 --from vraix --number 0 --to commonmeta --file out.json.gz

# Parquet output (.parquet file extension, --to commonmeta only): records are split into batches of 100,000, written in parallel, and zstd-compressed
cargo run --release -- list crossref-2026-06-15.sqlite3 --from vraix --number 0 --file out.parquet

# Register records with a live InvenioRDM instance (creates/updates and publishes
# real records — registration is currently only supported with --to inveniordm)
cargo run -- push --from crossref --number 10 --to inveniordm --host rogue-scholar.org --token TOKEN

# Same as push, but for a single record (DOI, URL, or file path)
cargo run -- put 10.5555/12345678 --from crossref --to inveniordm --host rogue-scholar.org --token TOKEN

# Download the latest ROR data release and install it as a local SQLite database
cargo run -- install ror

# Match a free-text affiliation string to a ROR organization (uses local DB when available)
cargo run -- match "Leibniz Universität Hannover"
cargo run -- match "Leibniz Universität Hannover" --to inveniordm

# Look up a ROR organization (uses local DB when available)
cargo run -- convert https://ror.org/02nr0ka47
cargo run -- convert https://ror.org/02nr0ka47 --to inveniordm

Use cargo run -- <subcommand> --help for the full list of options for each subcommand.

Local database

The install, match, and convert subcommands can use a local SQLite database of ROR organizations for faster, offline lookups instead of querying the ROR API.

Install with:

commonmeta install ror

The database path is resolved in this order:

1. --file flag (on install and match)
2. COMMONMETA_DB environment variable
3. Platform default:

# Use a custom path via environment variable
COMMONMETA_DB=/data/ror.sqlite3 commonmeta match "MIT"

# Use a custom path via flag
commonmeta install ror --file /data/ror.sqlite3
commonmeta match "MIT" --file /data/ror.sqlite3

Documentation

Documentation (work in progress) for using the library is available at the commonmeta-rs Documentation website.

Meta

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License: MIT