The BAM Masterdata repository contains the masterdata schemas defined at BAM and provides utility functions for working with them.

If you want to install it, do:

pip install bam-masterdata

Development

If you want to develop locally this package, clone the project and enter in the workspace folder:

git clone https://github.com/BAMresearch/bam-masterdata.git
cd bam-masterdata

We recommend using uv to manage your virtual environment and the dependencies, as well as using Python 3.14:

uv venv --python 3.14

Activate the environment:

• Linux/MacOS

  source .venv/bin/activate

• Windows

  .venv\Scripts\activate

With the virtual environment activated, make sure to install the optional dependencies:

uv sync --all-extras

Run the tests

You can locally run the tests by doing:

python -m pytest -sv tests

where the -s and -v options toggle the output verbosity.

You can also generate a local coverage report:

python -m pytest --cov=src tests

Run auto-formatting and linting

We use Ruff for formatting and linting the code following the rules specified in the pyproject.toml. You can run locally:

ruff check .

This will produce an output with the specific issues found. In order to auto-fix them, run:

ruff format .

If some issues are not possible to fix automatically, you will need to visit the file and fix them by hand.

Pre-commit hooks (recommended)

We use pre-commit to run fast checks automatically on every commit (formatting, linting, secrets scanning, and a repository-specific policy check).

Install once:

pip install pre-commit
pre-commit install

(Optional) Run on the whole repo:

pre-commit run --all-files

Secrets baseline: the repository uses .secrets.baseline. If you add new secrets intentionally (rare), update the baseline:

detect-secrets scan > .secrets.baseline

Documentation on Github pages

To view the documentation locally, make sure to have installed the extra packages with the setup commands explained above (especifically, uv sync --all-extras). This command installs the zensical dependency.

The first time, build the server:

zensical build

Run the documentation server:

zensical serve

The output looks like:

Serving .../site on http://localhost:8000
Build started
No issues found

Simply click on http://localhost:8000. The changes in the md files of the documentation are immediately reflected when the files are saved (the local web will automatically refresh).

Schema Explorer

The Schema Explorer is an interactive web application for browsing and visualizing the BAM Masterdata schemas.

It supports:

• Exploring object types and their properties.
• Visualizing inheritance relationships.
• Searching and navigating between object types.
• Switching between datamodel versions (v0 and v1).

For development instructions, see Schema Explorer.