Publish an ontology family
GraphArch can publish a family of related ontologies from a directory, a local Git checkout, or a remote Git repository. The same collectors and renderers work with your own ontologies, namespaces, family registry, and publishing authority. Family membership and publication identities come from your project configuration.
A family publication keeps each ontology's identity and namespace, generates an overview with descriptions and chapter links, and resolves references across the family. Its documentation KG can produce a standards-style specification and a PDF, alongside a separately configured companion website.
Choose your source
Use publication build-family with one source option:
| Source | Option | Contents read |
|---|---|---|
| Directory | --source ./ontologies | RDF files in that directory tree |
| Local Git checkout | --local-repository /path/to/your-repo | Working-tree files, including uncommitted edits |
| Remote Git repository | --git-repository https://git.example.org/team/ontologies.git --git-ref main | Files at one resolved commit |
| GitHub repository | --github OWNER/REPO --git-ref main | The same remote Git mode, with a GitHub URL shortcut |
When the source RDF contains one unambiguous ga:Project with one ga:Target,
GraphArch discovers the publication hints directly:
grapharch publication build-family \
--local-repository /path/to/your-repo \
--output-root ./output/family
Hints can live inside an ontology or in a separate RDF file in the same
repository. The source owns its title, authority, family membership, and
publication settings. Multiple projects or targets require an explicit selection;
GraphArch does not choose one arbitrarily. build-family publishes one target, so
a project registering several needs the override options below.
A gallery family showcase publishes every target the hinted project registers, in
IRI order, each into its own ga:destination. A targets list in the showcase
configuration selects registered targets instead, in its own order. The family
bindings belong to the profile of the first selected target with a
specification, specification-pages, bookshelf or Typst renderer and an
artpub:publishesFamily profile. Another family target with its own profile
that publishes the same family, such as a Typst PDF edition, receives its own
bindings. A website target publishes the pages in the project's
ga:contentSource directory, read from the same checkout or commit as the
ontologies. Without a declared content source it is rejected rather than
published empty. Any other target with its own profile is rejected.
A target can retain the documentation graph inside its own output with
ga:documentationGraphPath, a relative .nq path beneath its destination.
Pages can then link to the graph with a portable relative reference:
<urn:example:specification> ga:documentationGraphPath "documentation.nq" .
For external publication definitions, supply all three override options:
grapharch publication build-family \
--local-repository /path/to/your-repo \
--definitions ./publication.ttl \
--project urn:example:project \
--target urn:example:specification \
--output-root ./output/family
Replace the paths and identifiers with your own. The project and target must be
defined in publication.ttl. Generated files stay under the chosen output root;
the source repository is not modified. With a target destination of
specification, outputs include specification/index.html, its PDF and Typst
source, and documentation.nq.
A ga:TypstRenderer target publishes a PDF-only edition of the family, with no
single-page HTML copy. Give it its own profile that declares the family and
ga:theme ga:SpecificationTheme for the specification presentation, including the
target's status and version metadata. See PDF edition names for
how its file is named and where it is published:
<urn:example:pdf-profile> a ga:Profile, artpub:PublicationProfile ;
artpub:publishesFamily <urn:example:family> ;
ga:theme ga:SpecificationTheme .
<urn:example:pdf> a ga:Target ;
ga:profile <urn:example:pdf-profile> ;
ga:renderer ga:TypstRenderer ;
ga:documentType ga:SpecificationDocument ;
ga:publisher <urn:example:authority> ;
ga:destination "pdf" .
<urn:example:authority> ga:slug "example" .
<urn:example:family> ga:slug "example-ontologies" .
The target needs the same scope, title, description, status comment and
publication metadata as the HTML specification target. Build it with its own
build-family --target ... --edition default run; it publishes
pdf/example-spec-example-ontologies.pdf.
For a remote source, replace the source option with --git-repository URL --git-ref REF, or the GitHub shortcut. Unqualified refs mean branches; use
refs/tags/<tag> for a tag or a full commit ID for an immutable selection.
If --git-ref is omitted, GraphArch follows the remote default branch (HEAD).
Each build resolves that moving ref once and records the concrete commit in the
documentation KG. The cached bare repository is refreshed on subsequent runs.
Describe your family
Family identity and membership use the reusable Artifact Governance vocabulary; publication profiles use the Artifact Publication vocabulary. You can provide these relationships in your own registry, the ontology files, or the separate publication definitions. They do not have to come from a central registry.
@prefix ga: <https://ekgf.org/ontology/grapharch#> .
@prefix artgov: <https://ekgf.org/ontology/artifact-governance#> .
@prefix artpub: <https://ekgf.org/ontology/artifact-publication#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
<urn:example:family> a artgov:Family ;
rdfs:label "Example ontology family"@en .
<urn:example:profile> a ga:Profile, artpub:PublicationProfile ;
artpub:publishesFamily <urn:example:family> .
<https://example.org/ontology/core#>
artgov:inFamily <urn:example:family> ;
sh:declare [
sh:prefix "core" ;
sh:namespace "https://example.org/ontology/core#"
] .
This illustrates family relationships and namespace hints, not a complete publication configuration. Use your actual ontology IRIs and existing registered identities where available. Configure the project, target, scope, publication metadata, and authority as described in the publication pipeline and specification renderer guides.
Membership can also be asserted through artgov:Reference resources using
artgov:inFamily and artgov:refersTo; explicit IRI aliases are honored. Missing
registered members fail the build, preventing a silently incomplete publication.
The current builder requires explicit membership and namespace declarations;
it does not infer a family from an arbitrary folder or namespace prefix. Each
ontology source file must declare one named ontology. Each ontology needs one
unambiguous English rdfs:label for its chapter title. Namespace and prefix hints
use sh:declare and can be supplied separately without editing the source files.
An ontology may declare further display prefixes for vocabularies it reuses;
with several declarations, the one whose namespace is the ontology IRI names
the ontology itself. Turtle @prefix lines are parser syntax and are not kept
in the documentation KG. Well-known vocabularies (including rdf, rdfs,
owl, xsd, sh, skos, dc, dct, dcat, prov, vann, foaf,
schema, time, odrl, and org) are compacted without a declaration; a
source declaration of the same prefix or namespace takes precedence.
Typed xsd:date and xsd:dateTime values read as dates, for example
8 April 2020 and 8 April 2020, 00:00:01 UTC; HTML keeps the exact value in
<time datetime>. A date-time keeps its time even at midnight. Untyped strings
are shown as written; type a date in the source to have it read as one.
Choose collection terminology
A collection can be presented as a library, suite, portfolio, or another singular
noun phrase. Set ga:collectionTerm on the collection selected by the publication
profile:
<urn:example:family> a artgov:Family ;
rdfs:label "Example Ontology Library"@en ;
ga:collectionTerm "library" .
This produces “Library overview”, “Browse this library”, and “in this library”
consistently in generated content and navigation, including search results and
PDF headings. The OMG Commons showcase
uses this hint. Membership, ontology IRIs, the artgov:Family class and publication
APIs keep their meanings; this is a presentation preference, not a new kind of
ontology grouping.
The default is family. Supply a plain string of at most 80 characters, beginning
and ending with a letter or digit, with single spaces, hyphens or apostrophes
inside. Multiword terms such as ontology suite are supported. GraphArch does not
guess plural forms or indefinite articles.
What readers see
The opening overview provides ontology names, supplied descriptions, and quick links to the vocabulary chapters. Resource counts and annotation diagnostics appear in a documentation coverage appendix. Chapter titles use English ontology labels; prefixes remain available in metadata and technical identifiers.
The reference documents classes, properties, named individuals, and named SHACL
constructs. Explicit owl:NamedIndividual resources have readable headings and
linked instance-type summaries. Resources also declared as classes or properties
retain those additional roles. The presentation reference is
DCAT 3.
Supplied English labels and definitions are reproduced. Missing resource
annotations appear as warnings and become ga:Diagnostic resources with source
and revision provenance. Rendering does not invent definitions, execute SHACL
validation, or fetch external ontology imports.
Rich descriptions
Use annotation:markdownDescription from
https://ekgf.org/ontology/annotation# on an ontology, class, property, or
individual when its explanation needs Markdown:
@prefix annotation: <https://ekgf.org/ontology/annotation#> .
<https://example.org/ontology/Account>
annotation:markdownDescription """
## Scope
An account records **agreed responsibilities**.
- Identify the responsible party.
- Link the applicable agreement.
"""@en .
The reference renders headings, lists, links, fenced code, tables, and GitHub
Flavoured Markdown task lists. In an ontology's description, headings nest
beneath the chapter title. A class, property, or individual description is the
content of that term's entry, so its headings appear as bold run-in headings:
they add no numbered section, table-of-contents or sidebar entry, or PDF
bookmark, and their text is kept.
The rich description replaces the plain description in the detailed reference;
without it, the existing source definitions and comments remain available.
Ontology cards and full introductions share the same generic annotation mapping:
dct:abstract, dct:description, dc:description, skos:definition,
prov:definition, sh:description, then rdfs:comment. Cards use the first
available summary. Without an explicit rich description, the detailed ontology
introduction preserves all distinct paragraphs in that order, removing exact
repetitions across predicates. This works for any ontology namespace; no
publisher-specific content rules are required. Introductions admit up to 64
values per predicate and 256 KiB of selected plain text.
English publications select @en or untagged text. Identical rich
values are deduplicated; distinct rich values remain separately identifiable.
Descriptions in another language are not substituted for missing English text.
The original annotation and source provenance remain in the documentation graph.
Raw HTML and unsafe links fail rendering rather than executing or silently
losing content.
Publishing authority
Your publishing authority is configurable. Use artgov:Authority from the
Artifact Governance ontology directly; it denotes a Commons party role. Its organization is a
separate resource linked with cmns-rlcmp:isPlayedBy. Display names come from
English rdfs:label; acronyms use artgov:authorityAcronym or its equivalent
ga:shortName. Conflicting values fail validation.
Collection and caching
GraphArch reads Turtle, RDF/XML (.rdf), N-Triples, N-Quads, TriG, and N3.
XML catalog files are not treated as RDF sources.
Remote repositories are cached locally between runs. The default cache is under
the system temporary directory; use --git-cache /path/to/cache to choose another
location. Each run checks for updates and reads one fixed commit, without
creating a checkout. A failed update stops the build rather than publishing
outdated cached content.
GraphArch uses your Git credential configuration. Public repositories do not require a GitHub API token.
The KG retains the selected commit's author, committer, and timestamps. Local working-tree contents are identified independently from HEAD by the file collectors. Renderers read the resolved plan and pinned KG rather than reopening source files.
Current budgets are 4096 RDF files, 8000 documented family resources, 24 levels of anonymous RDF structure, and the renderer's 10000 entries and 16 MiB content limit. Unsupported structures and exceeded budgets are hard errors. Separate specification, companion-site, and approval-PDF publications are described in publication families.
Examples and validation
These projects are examples and test cases for the general pipeline:
- EKGF ontology family: the gallery follows the remote repository's latest default branch and records its resolved commit in the downloadable KG. A separate offline fixture covers 24 ontologies and 704 named resources. See the examples guide, or browse the showcase gallery. The copied corpus keeps regression tests reproducible without network access. Published gallery builds use the remote repository and fail if it cannot be fetched.
- DPROD: an individual-ontology showcase demonstrating a specification, companion website, and PDF. It is not a required vocabulary or input.
- FIBO Business Entities: the gallery publishes the complete 48-document BE
module from immutable official source URLs, with its native module hierarchy,
individual HTML pages, combined PDF and retained KG. External imports remain
references; see
examples/fibo-befor the exact inventory and license. - Full FIBO benchmark: the large-family and native-module benchmark reads an existing clone;
see
examples/fibofor source manifests, setup, and timing instructions.
The same pipeline works with other organizations, repositories, and ontologies. Tests also exercise independently defined families, namespaces, and authorities, and verify rendering from the KG after sources are removed.
Arrange each ontology reference
Each ontology chapter opens with an Overview, followed by nonempty Classes, Properties, Named Individuals, Shapes, and Other Terms sections. Term headings use supplied labels consistently; the prefixed identifier remains in the entry. Classification uses explicit source types, without fetching imports or inferring missing types. A punned named individual appears once under Named Individuals and retains all its declared types in its entry.
Put GraphArch hints in the ontology source to rename the overview or rename and reorder its resource sections:
@prefix ga: <https://ekgf.org/ontology/grapharch#> .
@prefix dct: <http://purl.org/dc/terms/> .
<https://example.org/vocabulary> ga:overviewTitle "Summary"@en ;
ga:referenceSection <https://example.org/docs/examples-section> .
<https://example.org/docs/examples-section> a ga:ReferenceSection ;
ga:sectionKind "individuals" ;
dct:title "Examples"@en ;
ga:order 0 .
Section kinds are classes, properties, individuals, shapes, and other.
Their default orders are 10, 20, 30, 40, and 50. Overrides require a title and an
integer order from 0 to 1000, distinct from every other section's order. Empty
sections are omitted; overrides do not hide resources. Titles are plain text,
with one English or untagged value per section.
The ontology IRI identifies the ontology; its namespace prefixes vocabulary
terms. They may differ (for example, https://example.org/vocabulary and
https://example.org/vocabulary#). The overview shows them in adjacent rows
when different and combines them into one row when equal.
Language-tagged labels and definitions are selected by RFC 4647 basic
filtering: the English range en also selects en-GB and en-US, so a term
labelled only with regional English variants keeps its labels. Plain-text
ontology introductions are prose: their indentation and line wrapping are
source formatting, and blank lines separate paragraphs.
Tabulate each ontology reference
A standards edition can present each ontology as tables instead of one section
per term. The profile selects a ga:TermTable:
@prefix ga: <https://ekgf.org/ontology/grapharch#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
<https://example.org/doc/profile> ga:termTable <https://example.org/doc/tables> .
<https://example.org/doc/tables> a ga:TermTable ;
ga:metadataCaption "{title} Metadata" ;
ga:detailsCaption "{title} Details" ;
ga:metadataLeadIn "Metadata for the {title} is given in {table}." ;
ga:detailsLeadIn "The terms of the {title} are given in {table}, below." ;
ga:metadataPredicates ( rdfs:label dct:abstract dct:license owl:versionIRI ) ;
ga:annotationPredicates ( skos:definition skos:note skos:example ) ;
ga:referenceSection <https://example.org/doc/classes>,
<https://example.org/doc/properties> .
<https://example.org/doc/classes> dct:title "Classes" ; ga:order 1 ;
ga:termType owl:Class .
<https://example.org/doc/properties> dct:title "Properties" ; ga:order 2 ;
ga:termType owl:ObjectProperty, owl:DatatypeProperty, owl:AnnotationProperty .
Each ontology chapter then holds its introduction, a numbered metadata
table and a numbered details table. The metadata table lists the
ontology IRI and one row per header statement, in the order of
ga:metadataPredicates (every header statement by prefixed name when absent);
multi-line values such as licences keep their lines. The details table has one
group per reference section, in ga:order. A term appears in the first group
whose ga:termType it declares; a term that no group selects fails the
publication. Rows are ordered by name and have three columns:
| Column | Content |
|---|---|
| Name | The local name in bold, followed by every English rdfs:label with its language tag, for example Authorization (authorisation@en-GB, authorization@en-US). |
| Annotations | One entry per annotation, labelled by the annotation property's English rdfs:label (skos:definition reads Definition). ga:annotationPredicates selects and orders them; without it every annotation is shown, ordered by label. A shown property without a label in the sources or definitions fails the publication. |
| Class Expressions, Property Axioms or Individual Axioms | Parent classes and properties, restrictions, equivalent and disjoint classes, domains, ranges, inverses, property chains, characteristics, types and property assertions. |
Axioms use description-logic notation: ∃ R.C (some values), ∀ R.C (all
values), ∃ R.{a} (has value), ≥ n R, ≤ n R and = n R, qualified as
≥ n R.C; C ⊓ D, C ⊔ D, ¬ C and oneOf (a, b); R⁻ for an inverse
property; and R ∘ S for a property chain. A complex filler is written in
parentheses after the property, as in ∀ R (C ⊔ D). Terms of the ontology's
own namespace are named by local name; other resources by prefixed name.
Subjects outside the namespace that the ontology's own document describes,
such as the classes a mapping ontology relates, are rows named by prefixed
name. rdfs:isDefinedBy is not shown. Missing English labels and definitions
remain KG diagnostics. Captions and lead-ins replace {title} with the
chapter title and {table} with a numbered reference in the PDF and a link in
HTML. SKOS concept schemes keep the sectioned reference.
Native modules and large families
Explicit FIBO Module instances and their dct:hasPart assertions become
ga:OntologyModule and ga:moduleMember facts alongside the unchanged native
assertions. Module nesting is preserved in the publication plan using
ga:parentPlacement. A domain can contain modules, which contain ontology
references and their Classes, Properties, Named Individuals, and Shapes sections.
The same hierarchy drives HTML numbering, contents navigation, and PDF chapters.
Containment is not inferred from directories or imports. Ontologies without
explicit module membership remain separate reference chapters. Missing members,
cycles, multiple parents, or more than eight component levels fail explicitly.
For headings deeper than HTML's six native heading tags, the specification
retains the semantic level using aria-level on an h6 heading.
A target or profile can set ga:tocDepth to an integer from 1 to 8. A target's
value takes precedence. For example, depth 4 can list a large family's modules
and ontologies while leaving individual vocabulary entries out of the sidebar
and PDF outline. When absent, HTML keeps its complete contents and PDF retains
its depth of three.
Large-family budgets are finite and coordinated across the pipeline:
| Item | Limit |
|---|---|
| Family resources, including ontology identities | 32,768 |
| Publication entries | 65,536 |
| Combined fragment content | 128 MiB |
| Link/reference index entries | 131,072 |
| Specification anchors | 262,144 |
| Specification links | 1,048,576 |
| Generated Typst source | 256 MiB |
| Individual retained artifact | 128 MiB |
| Retained showcase/website assets combined | 512 MiB |
Per-fragment, source-file, and concurrent-writer bounds still apply. The FIBO benchmark includes reproducible setup for an existing clone; no FIBO corpus is vendored.