Regenerate and test the schema

Regenerate and test the schema

Set up

CONTRIBUTING.md asks for Python 3.10 or later, uv and just.¹ Clone https://github.com/lmodel/oscal.git, run uv sync --group dev in it, and list the recipes with just --list. On WSL2, run export JUST_TEMPDIR=/tmp first, because the justfile’s shebang recipes otherwise fail with permission errors.² .copier-answers.yml records that the project was made from https://github.com/linkml/linkml-project-copier at v0.5.0.³ just update runs copier update and upgrades linkml and linkml-runtime in uv.lock.

Change the schema

1. Edit the files in src/oscal/schema/. Leave src/oscal/schema/metaschema/ as upstream wrote it: Move the upstream pins says how to replace it.
2. Render what OSCAL defines. Name in the pull request the metaschema definition that an element renders, and give each enum the lists it renders in oscal_allowed_values.
3. Follow the schema’s conventions: UpperCamelCase classes and enums, OSCAL’s own keys as slot names, a short description on every element, and no name shared with LOKF’s, slsa’s or github-actions’ copies. Element names and the shared namespace explains these.
4. Regenerate. just gen-project writes project/ and the Python datamodel, just gen-doc writes docs/schema/ and the element pages, and just lokf-adapt writes .lokf/oscal.yaml. Commit the output. Generated artefacts lists what each writes.
5. Add example data to tests/data/valid/ and tests/data/invalid/, named ClassName-suffix.yaml, with an invalid example for each constraint. Test data and schema tests describes the folders.
6. If the change alters behaviour, not just wording, add an entry under ## [Unreleased] in CHANGELOG.md.

Check it

• just test runs schema generation, pytest and linkml-validate over tests/data/, and the check of the Luigi Carpio fixture.
• just lint runs linkml-lint --ignore-warnings on the schema directory, so it fails on errors only.
• just lokf-adapt-check fails when .lokf/oscal.yaml is stale against the schema or .lokf/lokf.yaml.
• uvx pre-commit run runs the hooks on what is staged, which CONTRIBUTING.md names as ruff, yamllint, codespell, typos and the uv.lock check. The hooks leave alone the metaschema copy, the generated files, .lokf/lokf.yaml and the adapt copy, the sidecar’s scripts, tests/neighbours/ and the third-party fixtures.
• Update uv.lock, or .lokf/uv.lock, in the same change as a dependency edit, because CI installs with uv sync --locked and fails otherwise.
• Run cd .lokf && just lokf-validate after a change to the knowledge bundle.

Build and test runs just test on Python 3.10 to 3.14, and just lint and just lokf-adapt-check on Python 3.13 only.⁴ CONTRIBUTING.md says that Lint & docs is easy to trip locally: it runs ShellCheck, actionlint, markdownlint, link checking and codespell over every Markdown file.

Footnotes

1. CONTRIBUTING.md, Development setup and Before opening a pull request ↩

2. justfile, the _wsl2_compat_check, update, test and lint recipes ↩

3. .copier-answers.yml, _src_path and _commit ↩

4. .github/workflows/main.yaml, the test job ↩