Element names and the shared namespace

Element names and the shared namespace

OSCAL’s own names

CONTRIBUTING.md asks for UpperCamelCase classes and enums, OSCAL’s own keys as slot names, and a short description on every element, which just lint checks. .linkmllint.yaml keeps LinkML’s recommended lint rules but lowers standard_naming to a warning, which just lint does not fail on. Its comment says why: slots keep OSCAL’s own hyphenated keys, such as last-modified and finding-uuid, so the schema reads as the metaschema does. It adds that the generators write those keys with underscores, so an OSCAL JSON document has its keys rewritten before it validates, as the _test-linkml-validate recipe and tests/test_data.py do.¹

OSCAL’s class key is the slot class_. The catalog module’s comment says that a slot or alias named class makes the generated dataclasses invalid Python, and that gen-doc names a page after the slot, so _class hid its page from the site. class_ is the spelling the generated Pydantic model gives a slot named class.² CHANGELOG.md records the rename from _class.³

AI_COVENANT.md says that everything the schema defines lives under oscal:, which is https://w3id.org/lmodel/oscal/, and that OSCAL’s own names, such as property names and link relations, appear only as values the schema documents.⁴ CHANGELOG.md says that every element’s IRI moved there from a namespace per module, such as https://w3id.org/lmodel/oscal_catalog/, that no w3id route serves.

The adapt copy’s renames

The README says that a host imports the adapt copy, .lokf/oscal.yaml, beside lokf.yaml, and that LinkML merges the two into one namespace, where the last definition of a name wins silently.⁵ So the copy renames what LOKF defines. The classes Role, Parameter, Citation and Revision take an Oscal prefix, and seventeen keys, such as title, version and last-modified, take an oscal_ one. The copy also writes OSCAL’s hyphenated keys with underscores, so oscal-version becomes oscal_oscal_version.

The copy’s last note lists the seventeen keys, each renamed with its IRI unchanged: title, description, id, name, type, status, sources, last-modified, version, media-type, algorithm, constraints, unit, target, reason, source and predicate.⁶ The README adds that OSCAL gives none of the eight model classes an identifier slot, so a concept keeps each one’s required uuid and metadata, and its id names it beside them.

Keys shared with slsa and github-actions

The README says that seven keys are OSCAL’s and also slsa’s or github-actions’ under another IRI: attestations, dependencies, parties, provenance, subject and value in slsa’s copy, and actions in github-actions’ copy. A host that imports this copy beside either projects each of those keys under one vocabulary’s IRI.

tests/test_schema_rules.py lists the seven in SHARED_WITH_NEIGHBOURS.⁷ Its comment says that they are OSCAL’s own keys, and that lokf adapt renames only what lokf.yaml defines, so they stay until it can rename what a neighbour copy defines too. Two tests check the names:

• test_names_apart_from_lokf fails when a class, enum, type or subset name of .lokf/oscal.yaml is LOKF’s, or when a slot name the two share carries another IRI;
• test_names_apart_from_neighbours fails when such a name appears in tests/neighbours/slsa.yaml or tests/neighbours/github-actions.yaml, or when the keys shared with them under another IRI are not exactly the listed ones, so a new shared key fails it.

CONTRIBUTING.md asks contributors to keep names apart from LOKF’s, slsa’s and github-actions’, because a host imports the copies together.

Footnotes

1. .linkmllint.yaml, the comment and rules ↩

2. src/oscal/schema/oscal_catalog.yaml, the comment on the class_ slot ↩

3. CHANGELOG.md, the Changed items of the Unreleased section ↩

4. AI_COVENANT.md, the third item of A note specific to this project ↩

5. README.md, the Knowledge Trust Ladder (KTL) section ↩

6. .lokf/oscal.yaml, the last note, which lokf adapt wrote ↩

7. tests/test_schema_rules.py, SHARED_WITH_NEIGHBOURS and its comment, test_names_apart_from_lokf and test_names_apart_from_neighbours ↩