One knowledge graph, distinct publications
An ontology project can publish a specification, a companion website, and a PDF. They are separate publications with separate target identities. They share identified resources and selected fragments, rather than being three skins over an identical document.
| Publication | Reader purpose | Typical content | Renderer |
|---|---|---|---|
| Specification | Find the authoritative definition | Terms, constraints, conformance, references, publication status | specification |
| Companion website | Understand the ideas and learn to use them | Overview, stories, guides, tutorials, showcases | website |
| PDF edition | Review or approve a document | Explicit document order, contents, references, glossary, appendices | typst |
Authority comes from the identified publisher and publication process. A standards-style layout alone does not confer approval. Draft and final editions must declare their actual status.
Model each publication explicitly
A ga:Project can have several ga:Target resources. Each target binds a scope,
profile, renderer, and destination. A scope chooses which documented subjects
belong in that publication. A profile arranges their components using placements.
A specification and PDF may share a scope while using independent profiles. A companion site usually has a different scope and profile: its guides should not silently become normative specification sections. A shared explanation can be reused deliberately in more than one profile.
For example, these are distinct target definitions, not renderer-wide global settings:
@prefix ga: <https://ekgf.org/ontology/grapharch#> .
@prefix ex: <urn:example:> .
ex:project a ga:Project ; ga:target ex:spec, ex:site, ex:pdf .
ex:spec a ga:Target ;
ga:scope ex:reference-content ; ga:profile ex:spec-order ;
ga:renderer <https://ekgf.org/ontology/grapharch#SpecificationRenderer> ; ga:destination "spec/develop" .
ex:site a ga:Target ;
ga:scope ex:guides-and-stories ; ga:profile ex:site-navigation ;
ga:renderer <https://ekgf.org/ontology/grapharch#WebsiteRenderer> ; ga:destination "companion" .
ex:pdf a ga:Target ;
ga:scope ex:reference-content ; ga:profile ex:approval-document ;
ga:renderer <https://ekgf.org/ontology/grapharch#TypstRenderer> ; ga:destination "pdf" .
This snippet shows the target relationships; a complete project also declares
scope members, profiles, placements, fragments, and specification metadata.
Output directories must be separate and non-overlapping unless one target
declares that it contains another. Deployment can mount the companion output at
/dprod/, the specification at /dprod/spec/develop/, and the document at an
appropriate download URL. Those public URLs and the local artifact directories
are different concerns.
Compose targets and link between them
A target can contain other targets of the same project. Their destinations nest beneath its own, so one output tree has the deployed layout:
ex:site ga:destination "site" ; ga:containsTarget ex:spec, ex:pdf .
ex:spec ga:destination "site/spec/develop" .
ex:pdf ga:destination "site/pdf" .
Nesting without the declaration, or a contained target at the container's own destination, fails planning. Republishing the container keeps the contained outputs; a container file at a contained destination is a collision.
A link whose destination is a bare target IRI, in Markdown or in authored HTML
such as a custom metadata row, resolves to the relative path from the page to
that target's entry file: index.html for an HTML target, the PDF for a Typst
target. An IRI declared as a target but not registered by the project fails.
Read the [specification](urn:example:spec) or download the [PDF](urn:example:pdf).
Pin the family to one revision
Collect and document the sources, assemble one accepted revision, then resolve each target against that revision. Each target gets its own pinned plan and publication-job record. Readers can identify exactly which source revision each publication represents, even when its selection and arrangement differ.
The DPROD showcase exercises this flow. It publishes:
- A specification containing generated ontology and SHACL reference fragments.
- A multipage companion website containing an introduction, a story, and a guide.
- An independently planned review PDF, with the worked example arranged as an appendix.
The companion prose is excluded from the specification and document profiles. The test removes the input files, restores the exported KG, and renders all three targets. It checks shared revision provenance and separate profiles.
The specification renderer also emits a paired PDF for its own download button.
That is a rendition of the specification target; it is distinct from the
independently planned review document. When the family's Typst targets already
publish the PDF editions, set ga:pairedPdf false on the specification target
and link the editions by target IRI, for example in a custom metadata row, so
the same document is not published twice.
<urn:example:spec> ga:pairedPdf false ; ga:metadataRow <urn:example:pdfs> .
<urn:example:pdfs> a ga:MetadataRow ; ga:order 1 ; ga:field "custom" ;
dct:title "PDF editions:" ;
ga:body """<a href="urn:example:pdf">Community draft</a>""" .
CLI and implementation boundaries
All these renderers are part of the same Rust library and CLI. The persistent
publication assemble, publication plan, and publication render operations
can work with explicit targets. publication build-revision collects and
documents one exact content commit with definitions from an exact controlling
commit, then resolves and renders the selected targets from a restored KG; see
exact-revision builds. The
DPROD showcase builds this way, with specification/, website/, and pdf/
output directories. The publication build-site convenience command builds a
Markdown website target; it is not yet a general project configuration runner
for arbitrary mixed collector and documentor pipelines.
PDF edition names
Every PDF edition is named from definitions, so its URL tells readers what they
download: <authority>-<document-type>-<document-name>[-<edition>].pdf, such as
ekgf-spec-use-case-ontology-pr-23.pdf.
| Segment | Declared by |
|---|---|
| authority | ga:slug of the target's ga:publisher |
| document type | ga:slug of the target's ga:documentType: ga:SpecificationDocument (spec), ga:OverviewDocument (overview), ga:SubmissionDocument (submission) or ga:ReviewDocument (review) |
| document name | the target's ga:slug, else the ga:slug of the family its profile publishes |
| edition | the build input --edition |
Slugs are lowercase ASCII letters and digits in hyphen-separated words. A missing declaration is an error; nothing is derived from titles.
--edition is required for every build that renders a PDF, on build-family,
build-site, build-revision and render. Pass default only for the build of
the declared default branch, which publishes the unsuffixed name. Every other
build passes its branch slug, pr-<number> for a pull-request preview, or the
release version, so builds of different branches never overwrite each other's
PDFs. A PDF build without --edition fails.
A ga:TypstRenderer target owns exactly its one PDF file, not its destination
directory, so several PDF targets can share one directory such as pdf/. A
second target resolving to the same file name fails with a collision. The
target's manifest, Typst source and compiler inputs are retained beside the
output root in .grapharch/files/, outside the published tree. A
ga:SpecificationRenderer target names its paired PDF the same way inside its
own directory. Under a composing website, a PDF target's destination resolves
beneath the website's output like any other target.