Generated artefacts

Generated artefacts

CONTRIBUTING.md lists src/oscal/datamodel/, project/ and docs/schema/ as artefacts generated from the schema.¹ It asks that a schema edit be followed by just gen-project, just gen-doc and just lokf-adapt, and that their output be committed, since project/, src/oscal/datamodel/, docs/schema/ and .lokf/oscal.yaml are generated. The README says not to edit the files in project/.² The pre-commit configuration excludes all four, so that no hook rewrites what the next run would rewrite back.

project/

just gen-project runs LinkML’s gen-project with .linkml/generators.yaml, which skips the markdown generator and merges imports for the generators it configures.³ The recipe then moves the Python output into src/oscal/datamodel/ and writes the Pydantic model with gen-pydantic. It runs gen-java, gen-typescript and gen-owl on their own, because some generators ignore the configuration file or cannot create directories.⁴

project.justfile adds just gen-project-extended, which runs the generators that gen-project does not cover:⁵ a merged LinkML file, resolved YAML, SSSOM, Python namespaces, a TSV summary, Graphviz, Mermaid class diagrams, a Mermaid ER diagram, PlantUML, RDF in Turtle, SPARQL queries, CSV, DBML, SQLAlchemy models, SQL validation queries, TerminusDB, TypeDB, Java, Go, Rust, C++, Pandera, a Markdown data dictionary and GOLR views. The YAML, RDF, DBML, Java, Pandera and Markdown data dictionary recipes run patched scripts from scripts/issues/, and each script’s docstring names the upstream generator bug it works around. For example, a comment says that gen-java without merged imports generates no file, because the root schema’s classes are all defined in the modules it imports.

project/ holds one folder for each of cpp, csv, dbml, erdiagram, excel, golang, golr, graphql, graphviz, java, jsonld, jsonschema, linkml, markdown-datadict, mermaid, namespaces, owl, pandera, plantuml, prefixmap, protobuf, rdf, rust, shacl, shex, sqla, sqlschema, sqlvalidation, sssom, summary, terminusdb, typedb, typescript and yaml. tests/test_data.py validates the example data against project/jsonschema/oscal.schema.json, the generated JSON Schema.

The Python models

src/oscal/datamodel/oscal.py holds the dataclasses, and src/oscal/datamodel/oscal_pydantic.py holds the Pydantic models. just gen-python regenerates both, and just test runs it before pytest. Validate OSCAL data against the schema says what the dataclasses check.

docs/schema/ and docs/elements/

just gen-doc writes docs/schema/oscal.yaml with gen-yaml, and the schema’s Markdown pages into docs/elements/ with gen-doc. Git ignores the pages in docs/elements/, and the documentation site builds them when it needs them.

The domain schema copy

just lokf-adapt writes .lokf/oscal.yaml, the bundle’s domain schema, and just lokf-adapt-check fails when it is stale against the schema or .lokf/lokf.yaml. OSCAL Schema (top-level) says what the copy is, and Element names and the shared namespace says what it renames.

Footnotes

1. CONTRIBUTING.md, the table of paths and the first item of Before opening a pull request ↩

2. README.md, the Repository Structure section ↩

3. .linkml/generators.yaml, excludes and generator_args ↩

4. justfile, the gen-project, gen-python, gen-doc and _gen-yaml recipes ↩

5. project.justfile, the supplemental generator recipes and gen-project-extended ↩