Maturity models
MaturityModelDocumentor generates fragments for the EKGF maturity-model
vocabulary's Model, Pillar, CapabilityArea, Capability, and Level
instances. It reads a pinned collected KG revision. It does not execute the
legacy Python/MkDocs generator or read source files during documentation.
The vocabulary namespace is
https://raw.githubusercontent.com/EKGF/ontology-maturity-model/main/maturity-model.ttl#.
The hierarchy comes from pillarInModel, inPillar, inArea, and
levelInModel. Parents must exist with the expected explicit type; missing,
ambiguous, and incorrectly typed parents fail. This documentor does not perform
OWL inference. Capability numbers and explicit sort keys determine natural
numeric order, so A.1.2 precedes A.1.10.
Source rdfs:label supplies labels, rdfs:comment supplies plain-text taglines,
and dct:description supplies the Markdown descriptions used by this model's
authoring convention. English or language-neutral annotations are selected;
ambiguous selected values fail. Generated hierarchy links use the original
subject identities so publication plans can choose their routes.
let documentor = MaturityModelDocumentor::new(dataset, snapshot, project)?;
documentor.document(&writer).await?;
let subjects = documentor.subjects().await?;
// Bind documentor.fragment_id(&subject) to components in the target profile.
The library API can bind these fragments to any target components. Website builds can also invoke the documentor through an explicit project definition:
<urn:project> ga:documentor <urn:maturity-pages> .
<urn:maturity-pages> a ga:DocumentorUse ;
ga:documentorType ga:MaturityModelDocumentor ;
ga:source "docs-fragments" ;
ga:route "pillar/" .
The source path is relative to the project root and must stay within it. RDF
collectors must retain the model metadata before this stage. Exclude legacy
generated pages (for example ga:excludeSourcePath "pillar") from the authored
content tree. Website pages derive hierarchy routes from mm:iriLocalName,
which must identify safe, unambiguous path segments. The model index occupies
pillar/, levels occupy pillar/level/, and pillar/area/capability pages nest
according to the source parent assertions.
Existing authored Markdown under docs-fragments/pillar/<pillar>/<area>/<capability>/
is collected independently. Recognized companions are background-and-intro,
dimensions, levels, value, traditional-approach, ekg-approach, and
use-cases, with .md extensions. Present companions appear in that order;
missing optional sections produce no invented content. Their source identity
and contribution remain separate from generated hierarchy fragments. The
website composes them as page topics, and maps RDF subject links to the
corresponding page headings. No MkDocs generator is executed.
RDF collection alone does not invoke an unconfigured documentor. Each fragment retains its input revision and contribution. Changes regenerate the affected fragment content; removed subjects retire the corresponding generated contributions while historical snapshots remain valid.
The current source vocabulary does not define assessment statements linking
capabilities to levels. Existing levels.md, introductory, dimensions, value,
and approach fragments remain authored content to collect and place alongside
these generated fragments. The documentor does not invent assessment claims or
copy that prose into another source file.
Execution has explicit limits: 4,096 model subjects, 8 MiB of hierarchy metadata, 256 KiB per annotation, and 512 KiB per generated fragment. Descriptions are read one subject at a time. Exceeding a limit fails with an explicit error.
Taxonomy overview
A second configured documentor with ga:documentorType ga:MaturityOverviewDocumentor and
ga:route "intro/overview/" publishes a single hierarchy table from the pinned
model. It lists each capability with its pillar, area, number and rdfs:comment
(measurable ability), linking to native detail pages. It needs no companion
source. Exclude the legacy generated overview Markdown from collection when
replacing it at the same route; the authoritative RDF remains the only source
for the taxonomy facts.
Native documentors participate in a sidebar only when they explicitly declare
ga:navigationProfile. The model retains its parent hierarchy; ga:order
positions the root after or among authored entries (default: 1000000).
For an overview within an existing Introduction section, use
ga:navigationParentPath "intro" with the same profile as the directory
navigation collector. This references the collected section entry, not a
copied generated .pages.yaml file. Unknown parent entries fail validation.
Unlisted pages are never automatically added to an explicitly authored menu.