Skip to content
oscal

OSCAL Knowledge Bundle

A LOKF knowledge base for OSCAL (Open Security Controls Assessment Language). Every Markdown file under knowledge/ is one concept; together they form a queryable knowledge graph, derived from this repository’s code and docs.

Datasets

Section titled “Datasets”
  • OSCAL Schema (top-level) - The umbrella LinkML schema of OSCAL 1.2.3, src/oscal/schema/oscal.yaml (schema id https://w3id.org/lmodel/oscal, prefix oscal:): it imports the eight model modules, pins OSCAL’s tag v1.2.3 and commit e061961 in its annotations, and its lokf adapt copy .lokf/oscal.yaml, rooted on the eight models, is this bundle’s domain schema.
  • OSCAL Catalog Schema - The catalog module of the OSCAL schema, src/oscal/schema/oscal_catalog.yaml (id https://w3id.org/lmodel/oscal/oscal_catalog, OSCAL 1.2.3): the Catalog model of controls, groups, parameters and parts, the metadata, back matter, shared types and mixins every other module imports, and OscalDocument, the schema’s tree root.
  • OSCAL Profile Schema - The profile module of the OSCAL schema, src/oscal/schema/oscal_profile.yaml (id https://w3id.org/lmodel/oscal/oscal_profile, OSCAL 1.2.3): the Profile model, a selection of controls from catalogs or profiles and how it merges and modifies them, with ProfileDocument as its document root; it imports the catalog module.
  • OSCAL System Security Plan Schema - The system security plan module of the OSCAL schema, src/oscal/schema/oscal_ssp.yaml (id https://w3id.org/lmodel/oscal/oscal_ssp, OSCAL 1.2.3): the SystemSecurityPlan model of a system’s characteristics, its implementation and how it implements a profile’s controls, with SspDocument as its document root; it imports the catalog and assessment plan modules.
  • OSCAL Assessment Plan Schema - The assessment plan module of the OSCAL schema, src/oscal/schema/oscal_assessment_plan.yaml (id https://w3id.org/lmodel/oscal/oscal_assessment_plan, OSCAL 1.2.3): the AssessmentPlan model of what an assessment covers, and the assessment-common and implementation-common classes (subjects, tasks, observations, findings, risks, system components) that the component, SSP, assessment results and POA&M modules import.
  • OSCAL Assessment Results Schema - The assessment results module of the OSCAL schema, src/oscal/schema/oscal_assessment_results.yaml (id https://w3id.org/lmodel/oscal/oscal_assessment_results, OSCAL 1.2.3): the AssessmentResults model of what an assessment observed and found, with its results, attestations and assessment log, and AssessmentResultsDocument as its document root; it imports the catalog and assessment plan modules.
  • OSCAL Component Definition Schema - The component definition module of the OSCAL schema, src/oscal/schema/oscal_component.yaml (id https://w3id.org/lmodel/oscal/oscal_component, OSCAL 1.2.3): the ComponentDefinition model of components, their capabilities and the controls each implements, with ComponentDefinitionDocument as its document root, against which the CNCF and Luigi Carpio fixtures are validated; it imports the catalog and assessment plan modules.
  • OSCAL Mapping Collection Schema - The mapping collection module of the OSCAL schema, src/oscal/schema/oscal_mapping.yaml (id https://w3id.org/lmodel/oscal/oscal_mapping, OSCAL 1.2.3): the MappingCollection model of how the controls of one catalog or profile relate to another’s, with its provenance, maps, qualifiers, gap summaries, confidence scores and coverage, and MappingCollectionDocument as its document root; it imports the catalog module.
  • OSCAL POA&M Schema - The plan of action and milestones module of the OSCAL schema, src/oscal/schema/oscal_poam.yaml (id https://w3id.org/lmodel/oscal/oscal_poam, OSCAL 1.2.3): the PlanOfActionAndMilestones model of the risks a system still carries and how they are tracked, through its POA&M items, with PoamDocument as its document root; it imports the catalog and assessment plan modules.
  • CNCF AI Ecosystem OSCAL Benchmarks - 31 OSCAL component definitions from oscal-compass-lab/ai-benchmarks, one for each of 31 CNCF AI ecosystem projects (PyTorch, TensorFlow, LangChain, Kubernetes and others), in tests/data/cncf-ai-benchmarks/ under Apache-2.0, with fault-injected copies in tests/data/invalid/cncf-ai-benchmarks/ whose last-modified offset is +0000; tests/test_data.py and just test validate both as ComponentDefinitionDocument after rewriting their keys with underscores.
  • NIST 800-53 Rev 5 to AWS Service Mapping (Luigi Carpio) - A third-party OSCAL 1.1.2 component definition by Luigi Carpio, tests/data/luigi_carpio/component-definition.json under MIT, mapping 31 NIST 800-53 Rev 5 controls to AWS services, each with a fedramp-high property, and marking with cjis-delta where CJIS v6.0 exceeds FedRAMP High (AC-2, IA-2, AU-6, SC-28, IR-6); the test-luigi-carpio recipe, which just test runs, checks it.
  • OSCAL metaschema copy - OSCAL’s metaschema sources from the v1.2.3 release (usnistgov/OSCAL src/metaschema at commit e061961), copied byte for byte with NIST’s LICENSE.md into src/oscal/schema/metaschema/: never edited here, the source of the allowed values every enum renders, which tests/test_schema_rules.py checks, and compared weekly with upstream by scripts/check_upstream_release.py.
  • Generated artefacts - Files generated from the OSCAL schema and never edited by hand: project/ (what just gen-project writes, such as JSON Schema, JSON-LD, OWL, SHACL, ShEx, SQL, GraphQL, protobuf, Excel and TypeScript, and the further formats of just gen-project-extended), the dataclass and Pydantic models in src/oscal/datamodel/, docs/schema/oscal.yaml, the gen-doc pages in docs/elements/ and the domain schema copy .lokf/oscal.yaml.
  • Test data and schema tests - Example instances of the OSCAL schema in tests/data/: 36 valid files and 26 counter-examples, each named after the class it instantiates (Catalog-001.yaml, Profile-missing-imports.yaml), with an example and a counter-example for every model, the problem/ fixtures and two third-party OSCAL sets; tests/test_data.py and just test hold them to the dataclasses, the generated JSON Schema and linkml-validate, and tests/test_schema_rules.py holds the schema to the metaschema copy and the adapt copy’s names apart from LOKF’s, slsa’s and github-actions’.

References

Section titled “References”
  • NIST OSCAL - NIST’s Open Security Controls Assessment Language (OSCAL), the upstream standard this repository renders: release 1.2.3 (tag v1.2.3, commit e061961 of usnistgov/OSCAL), whose metaschema defines the catalog, profile, component definition, system security plan, assessment plan, assessment results, POA&M and mapping collection models, documented at pages.nist.gov/OSCAL.
  • LinkML - LinkML, the Linked Data Modeling Language the OSCAL schema is written in: the repository was built from linkml-project-copier v0.5.0, uv.lock pins linkml and linkml-runtime 1.11.1, and its recipes run LinkML’s generators (gen-project, gen-pydantic, gen-doc, gen-java, gen-owl), linkml-lint, linkml-validate and linkml-run-examples; the tests record where the generated code falls short.

Playbooks

Section titled “Playbooks”
  • Knowledge Sources - The librarian’s scrape map: every repository location and external page this bundle derives concepts from (schema, metaschema copy, adapt copy, generated artefacts, tests and fixtures, workflows, website, governance files), the concepts each yields, how to re-check each on a refresh run, and the paths left out on purpose.
  • Regenerate and test the schema - How to change the OSCAL schema: set up with uv and just, edit src/oscal/schema/ but never the metaschema copy, give each enum its oscal_allowed_values, regenerate with just gen-project, gen-doc and lokf-adapt, add examples, then run just test, just lint, just lokf-adapt-check and the pre-commit hooks, as the Build and test workflow does on Python 3.10 to 3.14.
  • Release the schema - How a releasing commit merged to main makes semantic-release promote CHANGELOG.md’s Unreleased section, tag vX.Y.Z and publish a GitHub Release, then dispatch the Knowledge Release workflow once KNOWLEDGE_RELEASE_ENABLED is true; below 1.0.0 from a v0.0.0 baseline tag, with a breaking change as a minor bump, no file bumped and nothing published to PyPI.
  • Move the upstream pins - What to do when the upstream watch opens its issue because NIST released a newer OSCAL or the metaschema copy drifted: replace src/oscal/schema/metaschema/ whole from the new tag’s src/metaschema/, move PINNED_TAG and PINNED_COMMIT with the schema header’s version, source and annotations, run just test and update every enum that tests/test_schema_rules.py reports.
  • Validate OSCAL data against the schema - How to check an OSCAL document against the schema with linkml-validate, naming the module and the class (-s src/oscal/schema/oscal_catalog.yaml -C Catalog), after rewriting native OSCAL JSON’s hyphenated keys with underscores; what the generated JSON Schema and the dataclasses check, and the metaschema constraints no tool here checks.

Organizations

Section titled “Organizations”
  • lmodel - lmodel, the GitHub organization that holds this repository (github.com/lmodel/oscal), its documentation site at lmodel.github.io/oscal and the schema’s w3id namespace under w3id.org/lmodel/oscal/, and the publisher of this bundle; lmodel/slsa and lmodel/github-actions release the adapt copies the tests read as neighbours.

Explanations

Section titled “Explanations”
  • Element names and the shared namespace - Why the OSCAL schema names its elements as it does: OSCAL’s own keys as slot names (last-modified, and class_ for OSCAL’s class), UpperCamelCase classes and enums, and every element under oscal:; and why its adapt copy gives LOKF’s Role, Parameter, Citation and Revision an Oscal prefix and seventeen keys an oscal_ one, and shares seven keys (attestations, dependencies, parties, provenance, subject, value, actions) with slsa’s and github-actions’ copies under another IRI.
  • Scope, influences and mappings - What the OSCAL schema renders and leaves out, and why: OSCAL 1.2.3’s eight models as NIST’s metaschema defines them, no influence beyond OSCAL apart from lmodel/slsa’s module layout, release asset and governance files, no mapping yet to another vocabulary, and the metaschema constraints it does not check (index, index-has-key, is-unique, expect and has-cardinality).

Policies

Section titled “Policies”
  • License and attribution - Which licence covers what in the oscal repository: Apache-2.0 for the schema, the generated models and the code; the OSCAL metaschema copy, NIST’s work in the public domain and dedicated worldwide under CC0 1.0, with NIST’s request for acknowledgement; the CNCF AI benchmark fixtures under Apache-2.0 and Luigi Carpio’s fixture under MIT; the linkml-project-copier scaffolding under MIT; the KTL sidecar and site templates under Apache-2.0; and the bundle under CC BY 4.0.
  • Security policy - How to report a vulnerability in oscal (GitHub’s private vulnerability reporting, not a public issue), which release gets fixes, what the repository releases and runs, what holds each workflow, and the three repository settings not yet in force: required reviewers on the release Environment, a deletion and force-push rule on main, and secret scanning with push protection.
  • AI covenant - The rules for AI-assisted work in oscal: a contributor owns what they submit; every element says what OSCAL’s metaschema says at the pinned release and each enum names its lists in oscal_allowed_values; the metaschema copy is never edited; everything the schema defines lives under oscal:; and the scheduled librarian works through pull requests a person approves, with least privilege.

Services

Section titled “Services”
  • oscal documentation site - The Astro Starlight site in website/, built from the README, docs/, the schema’s gen-doc pages, the changelog and the knowledge bundle by the Knowledge website workflow, which deploys it to GitHub Pages at lmodel.github.io/oscal once KNOWLEDGE_WEBSITE_ENABLED is true; it replaced the mkdocs site, and its REDIRECTS send the mkdocs addresses on to the new pages.

Workflows

Section titled “Workflows”
  • Build and test (main.yaml) - The Build and test workflow, .github/workflows/main.yaml: on a push to main and on every pull request, its test job runs just test on Python 3.10 to 3.14, and on 3.13 also just lint and just lokf-adapt-check, the check that .lokf/oscal.yaml is current.
  • Lint & docs (lint-and-docs.yaml) - The Lint & docs workflow, .github/workflows/lint-and-docs.yaml: on a push to main, every pull request, a Monday 06:00 UTC schedule and by hand, four jobs run ShellCheck, actionlint, the word budgets of CONTRIBUTING.md (1000) and SECURITY.md (900), and markdownlint, lychee and codespell over the Markdown.
  • Semantic release (semantic-release.yml) - The Semantic release workflow, .github/workflows/semantic-release.yml: on a pull request into main, its plan job checks that the commits, the changelog and the title would release and previews the release; on a push to main, its release job in the release Environment tags vX.Y.Z, publishes the GitHub Release and dispatches Knowledge Release.
  • Upstream watch (upstream-watch.yaml) - The Upstream watch workflow, .github/workflows/upstream-watch.yaml: every Monday at 07:00 UTC and by hand, its oscal-metaschema job runs scripts/check_upstream_release.py against usnistgov/OSCAL’s releases and the pinned metaschema tree, and on a finding opens or updates the issue titled Upstream watch: OSCAL has changed.
  • Knowledge website (knowledge-website.yaml) - The Knowledge website workflow, .github/workflows/knowledge-website.yaml: on pushes and pull requests that touch the site’s sources, every Monday at 05:23 UTC and by hand, its build job builds website/ and checks its links read-only, and its deploy job publishes the default branch’s build to GitHub Pages once KNOWLEDGE_WEBSITE_ENABLED is true.
  • Knowledge Registrar (knowledge-registrar.yaml) - The Knowledge Registrar workflow, .github/workflows/knowledge-registrar.yaml: the gate on the knowledge bundle, run on pull requests that touch .lokf/, every Monday at 06:00 UTC and by hand; it validates the bundle and its relation targets against the domain schema, runs the conventions script, and checks that each new confirmation by a person is backed by an approval or a signed commit.
  • Knowledge Librarian (knowledge-librarian.yaml) - The Knowledge Librarian workflow, .github/workflows/knowledge-librarian.yaml: every Monday at 05:00 UTC and by hand, once KNOWLEDGE_LIBRARIAN_ENABLED is true, it runs an LLM agent with the ktl-librarian skill (pinned by TRUST_LADDER_SKILLS_REF at v0.57.0) in a read-only job and opens a review pull request with the bundle change from a separate privileged job.
  • Knowledge Release (knowledge-release.yaml) - The Knowledge Release workflow, .github/workflows/knowledge-release.yaml: dispatched with a release’s tag, or started by a published release once KNOWLEDGE_RELEASE_ENABLED is true, it attaches knowledge-<tag>-<name>.zip, the domain schema as schema-<tag>-oscal.yaml and the Copilot skills to the release, but only when the bundle changed since the last release that carries one, or when force is set.
  • Knowledge sync (knowledge-sync.yaml) - The Knowledge sync workflow, .github/workflows/knowledge-sync.yaml: every Monday at 04:10 UTC and by hand, it moves the sidecar’s copies and the skills pin to the newest Knowledge Trust Ladder release through one pull request from the knowledge-sync branch, opened with the KNOWLEDGE_SYNC_TOKEN secret, and holds the workflow changes for a person to apply.
The root file declares
Base IRI https://w3id.org/lmodel/oscal/knowledge/
JSON-LD context https://w3id.org/lokf/context.jsonld
Licence CC BY 4.0
Publisher lmodel
Concepts 37

How far it has been checked

Section titled “How far it has been checked”

The bundle health page gives each concept’s label. The counts, computed from frontmatter when the site was built:

  • Confirmed by a person: 0 of 37
  • Checked by automation only: 1
  • Nobody has checked: 36
  • Drafts: 22
  • Reopened: 0
  • Past review date: 0
  • Edited since confirmed: 0
  • Retired: 0

Files

Section titled “Files”
  • concepts.jsonld: every concept’s frontmatter and body under one JSON-LD context.
  • graph.nt: the whole bundle as N-Triples.
  • graph.json: the typed relations as cytoscape.js elements, which the knowledge graph draws.
  • datasets.jsonld: a schema.org Dataset description for each Dataset or Table concept.
  • index.md: the bundle’s root file, which declares the header above.
  • log.xml: the bundle log as an Atom feed, its newest 20 days.
  • previews.json: each concept’s title, type, genre, trust label and definition, which a link to the concept shows before it is followed.
  • Each concept page links the concept’s own Markdown file and its JSON-LD, at the concept’s path with .md or .jsonld added.
  • The bundle as it stood at each release is a zip on the releases page.

Contents

Section titled “Contents”