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:

SourceOptionContents read
Directory--source ./ontologiesRDF files in that directory tree
Local Git checkout--local-repository /path/to/your-repoWorking-tree files, including uncommitted edits
Remote Git repository--git-repository https://git.example.org/team/ontologies.git --git-ref mainFiles at one resolved commit
GitHub repository--github OWNER/REPO --git-ref mainThe 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-be for the exact inventory and license.
  • Full FIBO benchmark: the large-family and native-module benchmark reads an existing clone; see examples/fibo for 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:

ColumnContent
NameThe local name in bold, followed by every English rdfs:label with its language tag, for example Authorization (authorisation@en-GB, authorization@en-US).
AnnotationsOne 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 AxiomsParent 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:

ItemLimit
Family resources, including ontology identities32,768
Publication entries65,536
Combined fragment content128 MiB
Link/reference index entries131,072
Specification anchors262,144
Specification links1,048,576
Generated Typst source256 MiB
Individual retained artifact128 MiB
Retained showcase/website assets combined512 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.

Search documentation

Enter words to search this site.