Schema workflow

Schema workflow#

src/rsm_schema/schema/rsm.schema.json is canonical. Everything else in the package is derived from it.

After changing the schema#

Regenerate the models and run the checks:

poetry run datamodel-codegen
poetry run pre-commit run --all-files
poetry run pytest

Commit the schema and the regenerated src/rsm_schema/generated/models.py together. CI regenerates the models and rejects a stale generated module.

Generation is configured under [tool.datamodel-codegen] in pyproject.toml.

If a change adds a name to $defs, export its generated counterpart from src/rsm_schema/generated/__init__.py to include it in the public API.

Releasing a new version#

The release version appears in both the schema’s $id and its published URL. Update them together:

  1. Bump version in pyproject.toml.

  2. Set $id to https://lumc-dcc.github.io/rsm-schema/schema/<version>/rsm.schema.json.

  3. Copy the schema into the archive:

    mkdir -p schema-archive/<version>
cp src/rsm_schema/schema/rsm.schema.json schema-archive/<version>/

  4. Update the versioned URL quoted at the top of README.md and the documentation home.

Where the two validation paths differ#

The package has two validation paths with one documented difference.

When contributors is non-empty, JSON Schema validation requires at least one author. datamodel-code-generator cannot express this list-wide if/then condition in a Pydantic model. A list containing only maintainers therefore fails validate_document() but passes RSMMetadata.model_validate().

Everything else the schema states is enforced on both paths, including the per-entry roles requirement. Use rsm_schema.validate_document() when conditional rules must be enforced. It validates against the bundled JSON Schema.

Inspection scope#

The inspection API provides JSON Pointer lookup, local $ref resolution, property and definition traversal, array items, and oneOf/anyOf/allOf traversal. It does not fetch external $ref targets.

Building the docs locally#

poetry install --with docs
poetry run sphinx-build -b html -W --keep-going docs docs/_build/html

-W matches CI and treats warnings as errors.