ebm-schemas 0.2.0

Canonical Pydantic schemas for QueryTek Education Benefits Manager (EBM)

ebm-schemas

Canonical Pydantic models used across the QueryTek EBM services.

This package provides small, stable, and extensible Pydantic models used as the single source of truth for API contracts, worker payloads, and OpenAPI generation.

Included models (Phase‑0)

• Person
• Course
• Milestone
• Refund
• Entitlement
• Provider
• Enrollment
• Transaction
• Organization
• WebhookEvent
• EntitlementAssignment

Purpose

• Provide canonical, backwards-compatible shapes for payloads exchanged between services.
• Make the OpenAPI spec authoritative by using the same models in the service code and the exporter.
• Allow other services to import the models and validate provider payloads with a shared contract.

Extension rules & versioning

• Backwards-compatible changes:
  • Add new optional fields freely.
  • Add new models in minor releases.
• Breaking changes:
  • Avoid removing or renaming existing fields.
  • If you must break a model, introduce a new versioned model and bump the package major version.
• Versioning policy:
  • The package follows semantic-style versioning for consumer consumption (0.x for early development). When stable, move to 1.0.0.

How to use locally

Install editable during development:

cd /path/to/repo
. services/ebm-api/venv/bin/activate
pip install -e libs/ebm_schemas

Import in code:

from ebm_schemas import Person, Provider, WebhookEvent

Building a wheel locally

Recommended: use the build module (PEP 517):

python -m pip install --upgrade build
cd libs/ebm_schemas
python -m build --wheel
# wheel will be in libs/ebm_schemas/dist/

Publishing

• To create a git tag and GitHub release:
  • Tag: git tag -a v0.2.0 -m "ebm-schemas 0.2.0"
  • Push: git push origin v0.2.0
  • Create release and attach wheel (or let CI create release artifacts).
• To publish to PyPI (if desired), use twine:

python -m pip install --upgrade twine
python -m twine upload dist/ebm_schemas-0.2.0-*.whl

(Only publish to PyPI if you want the package publicly available.)

Notes

• The package depends on email-validator because models use pydantic.EmailStr.
• The exporter script has been made robust to automatically import and inject these canonical schemas into the OpenAPI export used by the ebm-api service.