Skip to content

Contributing overview

This guide covers everything needed to contribute to the hdr_schemata package — from setting up a local environment to adding a new schema version and getting it published.

Prerequisites

  • Python 3.11 (the generator's output is interpreter-dependent — see Releasing a version)
  • Git
git clone https://github.com/HDRUK/schemata-2.git
cd schemata-2
pip install -e .              # install package in editable mode
pip install -r requirements.txt  # docs and test dependencies

Repository layout

hdr_schemata/
  models/
    HDRUK/
      v2_1_2/        # base model — all HDRUK versions derive from here
      v2_2_1/        # overrides only what changes from v2_2_0
      2.2.1/         # generated schema.json (dotted version name)
      __init__.py    # version registry — import each vX_Y_Z class here
    GWDM/            # same pattern
    CRUK/
    SchemaOrg/
  definitions/HDRUK/ # ~60 reusable field types, enums, validators
  annotations/       # config.yaml files with field titles and descriptions
  examples/          # example JSON files used by tests
  tests/             # pytest — one file per schema family
  build.py           # regenerates all schema.json + available.json + docs
  utils/
    create_markdown.py  # renders docs/ markdown and form.json from the models

Schema families and versions

The available.json file at the repo root is the authoritative list of all registered schema versions. It is auto-generated by python -m hdr_schemata.build — do not edit it by hand.

Versions are discovered from each family's __init__.py. Removing a version's import there de-registers it, which drops it from available.json and stops it being built or documented.

frozen.json is the hand-authored exception: versions listed there are merged back into available.json even though no model produces them. Use it to retire a version from maintenance while keeping it resolvable for consumers — see Releasing a version.

Next steps