Executable showcases
Browse the showcase gallery for live HTML previews, PDFs, and downloadable documentation graphs.
These fixtures are both runnable demonstrations and integration tests. The runner
and tests/showcases.rs use the same pipeline in support/mod.rs; tests do not
maintain a second implementation of collection or publication.
| Showcase | Native inputs | Processing | Outputs |
|---|---|---|---|
showcase/ | Authored RDF containing Markdown fragment bodies and publication definitions | RDF collection, assembly, three target plans | Specification HTML, reader HTML, review PDF |
w3c-rdf12-n-triples/ | Pinned RDF 1.2 N-Triples Working Draft | Published-document collector, assembly, specification target | HTML and PDF, native anchors and queryable constructs, plus a diagnostic addendum for an upstream broken reference |
specification/ | Authored RDF containing publication metadata and Markdown fragments | RDF collection, assembly, specification target plan | Standards-style HTML with nested numbered ToC, publisher front matter, abstract, status, and appendix |
dprod/ | A content/ tree with the pinned DPROD ontology, SHACL shapes and dataset-schema Markdown, plus separate definitions.ttl | Exact-revision build from two Git repositories: configured Git collectors, vocabulary reference documentor, three target plans | Specification HTML, companion website, review PDF, exported KG |
ekg-ontologies/ | Latest default branch of a configured remote ontology repository; separate offline acceptance corpus | Parallel RDF collection and source-annotation documentation, explicit family membership, cross-ontology links | Family specification, PDF, exported KG with annotation-gap diagnostics |
skos/ | Native SKOS Turtle, split across source files | Scheme recognition, preferred labels, concepts and ordered collections | Standards-style HTML, PDF, exported KG |
use-cases/ | Actual EKGF UseCase instances in Turtle | Use-case documentor, ownership/reuse validation, retained SVG neighborhoods | Reader HTML, review PDF, exported KG |
mixed-sources/ | Separate Markdown, SPARQL, OWL, and publication-definition files | Four specialized collectors scheduled concurrently, OWL class documentor, assembly, two target plans | Reader HTML, review PDF |
From the repository root:
cargo run --example publish_showcase
cargo run --example publish_showcase -- --skos
cargo run --example publish_showcase -- --use-cases
cargo run --example publish_showcase -- --mixed
cargo run --example publish_showcase -- --specification
cargo run --example publish_showcase -- --w3c --keep-going
cargo test --test showcases
Pass an optional positional output root to any invocation. Defaults are
output/pdf/grapharch-showcase, output/pdf/grapharch-mixed-sources, output/pdf/grapharch-specification,
and output/pdf/grapharch-w3c-rdf12-n-triples. The DPROD example is an
exact-revision build; its tests commit content/ and definitions.ttl to two
Git repositories and run grapharch publication build-revision
(cargo test --test revision_build --test dprod_showcase).
The RDF 1.2 keep-going run deliberately exits nonzero after producing diagnostic
artifacts because its upstream source has an unresolved link.
Each output root includes documentation.nq, an export containing the retained
contributions, validated revision, pinned plans, and publication-job records.
The authored example demonstrates shared content with different target ordering, styles, table rendering, code, glossary, references, and appendices. Its test exports and restores the dataset into a fresh store before rendering, after removing the original input. It checks shared revision provenance, common content, different section ordering, and PDF production.
The mixed example contains no authored ga:body triples. Markdown frontmatter and
a SPARQL comment pragma identify documentable subjects. An OWL rdfs:comment
becomes a documentation fragment through OwlClassDocumentor. The query is
published as source text, without execution. Its test removes every input before
rendering and checks that both outputs contain prose from all three source types.
The mixed runner explicitly binds components to the stable fragment IDs exposed
by the collectors and documentor. File enumeration and bindings are example
wiring in Rust; ga:source declarations do not yet drive automatic discovery.
Only the OWL class description is placed in these outputs; generated assertion
fragments remain in the graph. This is not full ontology documentation coverage
or a DPROD acceptance fixture.
The specification example tests publication metadata, nested numbering, local CSS, escaped content, and output from a KG after source deletion. Invalid status/date metadata and unsafe publication links must preserve the previous output. A runner regression test verifies that its default output root differs from the original authored showcase.
The ontology-family guide shows how to run the EKGF family
from a remote repository, a local checkout, or the separate offline acceptance corpus.
The gallery normally fetches the latest default branch (ga:gitRef "HEAD")
declared in examples/ekg-ontologies/showcase.ttl; its downloadable KG records
the concrete commit observed by each build. It is pinned to the ekg-ontologies
migration commit c7d9bc2 until that migration reaches the default branch. The
repository registers a website built from its declared ga:contentSource
pages, which contains the paginated family reference (spec/main/) and the
Typst PDF edition (pdf/). Every target is published; each retains the
documentation graph where its definitions place it, and links between them name
the target IRIs.
Showcase configuration
GraphArch-owned showcase configuration is RDF. examples/showcases.ttl
registers every ga:Showcase; a runner that needs settings reads them from the
showcase.ttl its ga:source names, which describes exactly that one
showcase. Unknown ga: settings are errors.
| Runner | Settings on the ga:Showcase |
|---|---|
| Exact revision | ga:gitRepository, ga:gitCommit, ga:definitionsCommit, ga:definitionsPath, ga:showcaseProject, and ga:allTargets true or ga:showcaseTargets ( … ) |
| Ontology family over Git | ga:gitRepository, ga:gitRef (exact commit or moving reference such as HEAD), optional ga:hintsPath and an ordered ga:showcaseTargets selection of hinted targets (every registered target when absent), or local definitions |
| Ontology family over RDF URLs | ga:rdfDocument IRIs, each with ga:format, plus local definitions |
| MkDocs | ga:gitRepository, ga:gitCommit, ga:mkdocsConfiguration, ga:materializedPath, ga:licensePath |
Local definitions are ga:definitionsPath (beneath the configuration),
ga:showcaseProject and ga:showcaseTargets, whose first target is the family
publication. Copied fixture files are recorded with ga:copiedSource entries
(ga:localPath, ga:contentDigest, and ga:sourcePath or ga:copiedFrom),
plus ga:copiedRepository, ga:copiedRevision and ga:copiedFromWorkingTree
on the showcase; showcases::verify_copied_sources checks every digest.
Adding a showcase
Keep native input files readable and small. Declare what the example demonstrates
and its limits in this catalog. Put shared pipeline code in support/ and add a
behavioral integration test before implementing the new path. Assert observable
content, provenance, ordering, failure behavior, or graph relationships; avoid
byte-for-byte PDF snapshots and copying renderer internals into tests.
The real N-Triples fixture proves semantic round-tripping and native anchor preservation; it does not yet establish exact W3C visual parity. ReSpec is publicly named as a reference in the compatibility map.
The DPROD fixture documents four OWL classes, thirteen object properties, one datatype
property, one SKOS concept scheme, six SHACL node shapes, and twenty-eight property
shapes. Its content/ tree carries no GraphArch configuration; definitions.ttl
configures the collectors, reference sections and placements. Its test deletes
both repositories and the cache and renders from a restored graph. Source files
are unchanged copies pinned to a DPROD commit with checked digests. This is
a three-publication family and derivative reference preview, not a full migration of the DPROD specification
or an official OMG publication.
Dedicated skos/ and use-cases/ fixtures are now included in the gallery and
its CI verification. The SKOS example has a standalone concept scheme, multilingual
preferred labels, hierarchy/mapping links, and an ordered collection. The use-case
example documents actual EKGF UseCase instances, with independent roots,
ownership, cross-branch reuse, a persona, an outcome, and a referenced concept.
Both have exported-KG restoration tests in tests/taxonomy_use_case_showcases.rs.
See Use-case trees for the vocabulary and diagram contract.
Live DPROD gallery
The gallery case is an exact-revision build of EKGF/dprod.
examples/dprod/showcase.ttl names the repository (ga:gitRepository), the
exact content commit (ga:gitCommit), the exact controlling commit and path of
DPROD's GraphArch definitions (ga:definitionsCommit, ga:definitionsPath),
the project (ga:showcaseProject) and the target selection (ga:allTargets true or an ordered ga:showcaseTargets list). The gallery, not DPROD's
definitions, supplies where it is deployed: the registry's
ga:showcaseArtifactsUrl followed by the showcase slug, from which each
target's ga:thisVersion is derived. The ga:RevisionBuildShowcaseRunner fetches both
commits through a reusable bare Git cache; branch names are rejected. Content
comes only from the content commit; the definitions come only from the
controlling commit. Missing source files, invalid definitions and unavailable
sources stop the build; copied fixtures are never used as a replacement.
Both pins currently name commit 72e9d27 of EKGF/dprod develop (the merge of #299), whose
publication/definitions/develop.ttl holds the controlling definitions.
The definitions place the formal prose and worked examples independently from the companion website. Required section roles check the actual selected fragments; collecting a file alone does not satisfy a requirement. The generated vocabulary reference fills components whose placements are authored beneath the declared reference section.
The comparison baseline is OMG DPROD 1.0 beta 2. The draft sources cover scope, conformance, references, terms, symbols, namespaces, model explanations, data contracts, acknowledgements, and the publisher preface. They include eight core and seven contract examples, with separate machine-readable example files retained in the KG. Existing legal notices are collected without changing their wording. These are draft outputs, not a claim of OMG approval for 1.1.
A separately registered release target requires an authority-assigned document identifier, release date, version URL, and formal approval status. The showcase publishes the draft targets; it does not fill in missing release metadata.
Repository links resolve to published companion pages where available, or to verified files at the same commit on GitHub. Images are collected into the publication KG, checked for supported content and size, and restored from that KG when producing HTML and PDF. Renderers do not fetch images or reopen Git.
The pinned corpus in examples/dprod/ remains an offline regression fixture;
the live gallery uses the remote repository. Run its network acceptance
explicitly with cargo test --test live_dprod -- --ignored.