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.

PublicationReader purposeTypical contentRenderer
SpecificationFind the authoritative definitionTerms, constraints, conformance, references, publication statusspecification
Companion websiteUnderstand the ideas and learn to use themOverview, stories, guides, tutorials, showcaseswebsite
PDF editionReview or approve a documentExplicit document order, contents, references, glossary, appendicestypst

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.

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.

SegmentDeclared by
authorityga:slug of the target's ga:publisher
document typega:slug of the target's ga:documentType: ga:SpecificationDocument (spec), ga:OverviewDocument (overview), ga:SubmissionDocument (submission) or ga:ReviewDocument (review)
document namethe target's ga:slug, else the ga:slug of the family its profile publishes
editionthe 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.

Search documentation

Enter words to search this site.