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.

ShowcaseNative inputsProcessingOutputs
showcase/Authored RDF containing Markdown fragment bodies and publication definitionsRDF collection, assembly, three target plansSpecification HTML, reader HTML, review PDF
w3c-rdf12-n-triples/Pinned RDF 1.2 N-Triples Working DraftPublished-document collector, assembly, specification targetHTML and PDF, native anchors and queryable constructs, plus a diagnostic addendum for an upstream broken reference
specification/Authored RDF containing publication metadata and Markdown fragmentsRDF collection, assembly, specification target planStandards-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.ttlExact-revision build from two Git repositories: configured Git collectors, vocabulary reference documentor, three target plansSpecification HTML, companion website, review PDF, exported KG
ekg-ontologies/Latest default branch of a configured remote ontology repository; separate offline acceptance corpusParallel RDF collection and source-annotation documentation, explicit family membership, cross-ontology linksFamily specification, PDF, exported KG with annotation-gap diagnostics
skos/Native SKOS Turtle, split across source filesScheme recognition, preferred labels, concepts and ordered collectionsStandards-style HTML, PDF, exported KG
use-cases/Actual EKGF UseCase instances in TurtleUse-case documentor, ownership/reuse validation, retained SVG neighborhoodsReader HTML, review PDF, exported KG
mixed-sources/Separate Markdown, SPARQL, OWL, and publication-definition filesFour specialized collectors scheduled concurrently, OWL class documentor, assembly, two target plansReader 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.

RunnerSettings on the ga:Showcase
Exact revisionga:gitRepository, ga:gitCommit, ga:definitionsCommit, ga:definitionsPath, ga:showcaseProject, and ga:allTargets true or ga:showcaseTargets ( … )
Ontology family over Gitga: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 URLsga:rdfDocument IRIs, each with ga:format, plus local definitions
MkDocsga: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.

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.

Search documentation

Enter words to search this site.