commonmeta-schema 1.0rc1

Commonmeta JSON Schemas and conformance fixtures

commonmeta-schema

Language-neutral JSON Schema definitions and conformance fixtures for Commonmeta, the scholarly metadata interchange format.

This repository is the shared source of truth consumed by the following Commonmeta implementations:

• commonmeta-rs (Rust)
• commonmeta-py (Python)

Keeping the schema and the golden fixtures in one place lets every implementation validate against the same contract and run the same cross-format conformance tests.

Layout

schemas/
  commonmeta_v1.0rc1.json      # the Commonmeta JSON Schema (current: v1.0rc1)
fixtures/
  commonmeta/                  # canonical Commonmeta records (round-trip + expected output)
  <format>/                    # input fixtures in a given source format
  <format>_out/                # expected writer output (Commonmeta -> format)
  <format>_commonmeta/         # expected reader output for non-JSON inputs

Schema versions

Schemas are versioned by filename. The current version is commonmeta_v1.0rc1.json; new versions are added alongside it rather than replacing existing files, so implementations can pin a version. The schema_version field of a Commonmeta record is the URL https://commonmeta.org/commonmeta_v1.0rc1.json.

Fixture conventions

The conformance harness in each implementation follows these naming rules (a missing pair is skipped, so partial coverage is fine):

Test kind	Input	Expected
Round-trip	fixtures/commonmeta/<name>.json	itself (re-serialized, semantically equal)
Reader (JSON input)	fixtures/<format>/<name>.json	fixtures/commonmeta/<name>.json
Reader (text input)	fixtures/<format>/<name>.<ext>	fixtures/<format>_commonmeta/<name>.json
Writer	fixtures/commonmeta/<name>.json	fixtures/<format>_out/<name>.<ext>

Formats currently covered: crossref, crossref_xml, datacite, datacite_xml, schemaorg, csl, bibtex, cff, ris, jsonfeed, inveniordm, codemeta.

Semantic comparison

Fixtures are compared as parsed JSON trees, not as strings, using an omitempty-aware and numeric-aware diff: key order and whitespace are irrelevant, an absent field equals an empty/zero/null value, and 52 equals 52.0. This keeps hand-authored fixtures robust across implementations.

Using this repository

Each implementation vendors (copies) the schema and fixtures it needs from here. Update the canonical files in this repository first, then sync them into commonmeta-rs and commonmeta-py.

Packaging and publishing

This repository can be published as both:

• a Python package on PyPI (commonmeta-schema)
• a Rust crate on crates.io (commonmeta-schema)

For the initial release, publish explicitly via CLI (not CI automation).

Package versions follow the schema version:

• PyPI uses PEP 440 form: 1.0rc1
• crates.io uses SemVer form: 1.0.0-rc.1

Python (PyPI) via uv publish

1. Ensure you are authenticated for PyPI (recommended: trusted publisher or API token).
2. Build distribution artifacts:

uv build

3. Optionally validate the build metadata:

uvx twine check dist/*

4. Publish to PyPI:

uv publish

Rust (crates.io) via cargo publish

1. Log in once with a crates.io token:

cargo login

2. Validate package contents from the crate directory:

cargo package --manifest-path rust/Cargo.toml --allow-dirty

3. Publish:

cargo publish --manifest-path rust/Cargo.toml

Recommended first-release order

1. Publish 1.0rc1 to PyPI with uv publish.
2. Publish 1.0.0-rc.1 to crates.io with cargo publish.
3. Create a git tag v1.0rc1 after both uploads succeed.

License

MIT © 2026 Front Matter