OSCAL Version Monitoring and Support-Data Delivery

Status: idea / design notes. Not started — set aside to ship the current release. Captured: 2026-11-13.

Goal: the published oscal package should include the latest NIST OSCAL release in its support database as soon as possible after NIST publishes it, while staying transparent to users (pip install oscal is all they do) and working fully offline once installed.

Background: how the support database works today

Relationship to the SBOM

Options considered

1. Scheduled database update committed to main

A scheduled workflow checks NIST for new releases, runs update_support --new, runs the unit tests, and commits the zip to main if they pass. The next library release picks it up.

2. Scheduled update + automatic library release + automatic PyPI publish — rejected

Extends option 1 to bump the patch version and run the release workflow automatically.

Rejected (for now) because the release would build from the current state of main, not the last release. Anything merged to main but not yet meant for release would ship with the data update. It also creates version collisions with develop (the bot and a human both claiming the next patch number) and requires removing the human PyPI approval gate.

If ever revisited, required guardrails:

3. Database regeneration once per PR

To have the regenerated database reviewed in the PR without rebuilding it on every PR update:

Publish the database as its own PyPI project (e.g. oscal-support-data) that oscal depends on (dependencies = ["oscal-support-data>=2026.11"]). This is how tzdata and certifi work.

Costs / contract:

Options also ruled out: download-on-first-use (breaks offline), install-time hooks (wheels can’t run code at install), an optional extra like pip install oscal[data] (a plain install wouldn’t include the data). A later add-on could let users refresh data into a local cache (update_support --new) that the library prefers when present.

Two PyPI projects from this one repository

Supported by both PyPI and GitHub (common in large projects).

class/
  pyproject.toml                       # oscal (library)
  oscal/
  packages/oscal-support-data/
    pyproject.toml                     # oscal-support-data
    oscal_support_data/
      __init__.py                      # path helper only
      oscal_support.zip

Suggested sequence when picked up

  1. Settle the data format contract (format version + how unsupported OSCAL versions are ignored).
  2. Split the data into packages/oscal-support-data and make oscal depend on it.
  3. Add publish-data.yml (manual first), register the PyPI pending publisher, release once.
  4. Add the scheduled check (update_support --new → tests → data release), with failure issues.
  5. Remove the support-data regen from the library’s CI.