Publication version listings

A publication inventory can generate a version-selection page and a matching machine-readable routing manifest from the same pinned documentation graph. The visible list can omit obsolete review branches while their existing URLs remain routable.

Represent versions with doap:Version, a title, branch, identifier and dcat:accessURL. ga:advertised explicitly selects which versions readers see. An optional ga:publicationStatus literal supplies reader-facing status, such as "Unstandardized pull request preview"; it appears on the page and as status in the retained version manifest. The inventory's dct:modified records when it was observed, not when the specification was authored. Optional ga:order values place canonical releases and development versions before previews; versions without an explicit order follow alphabetically by branch. The page lists one card per advertised version directly below its introduction; each card's title links the whole card to that version. The observation time is recorded in publication-versions.json.

@prefix ga: <https://ekgf.org/ontology/grapharch#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .

<urn:example:inventory> dct:modified "2026-11-02T15:00:00Z" ;
    dct:hasPart <urn:example:develop> .
<urn:example:develop> a doap:Version ;
    dct:title "Develop (latest)" ; dct:identifier "develop" ;
    doap:branch "develop" ;
    dcat:accessURL <https://example.org/spec/develop/> ;
    ga:advertised true ; ga:order 1 .

<urn:example:versions-page> a ga:DocumentorUse ;
    ga:project <urn:example:project> ; ga:documentorType ga:PublicationInventoryDocumentor ;
    ga:subject <urn:example:inventory> ; ga:fragment <urn:example:page> ;
    dct:title "Specification versions" ; ga:route "spec-versions/" ;
    ga:sourcePath "spec-versions.md" ; ga:navigationOrder 6 .

The normal website pipeline generates the page before resolving the publication plan. Authored Markdown can link to spec-versions.md as it would any other page, or by the page IRI that ga:fragment names; website links by page IRI resolve to the relative route of that page. Rendering reads the retained inventory only; it never queries deployment services.

The website also contains publication-versions.json: an observation timestamp and every known version's slug, branch, label, specification URL and advertised flag. Static hosting configuration can preserve unadvertised preview links using that manifest. Invalid metadata, ambiguous slugs and incomplete records fail the build; they do not produce a deceptively shortened listing.

For GitHub repositories deployed on Vercel, configure the repository publication collector to capture open pull requests and ready deployments during collection:

<urn:example:project> ga:collector <urn:example:versions-collector> .
<urn:example:versions-collector> a ga:CollectorUse ;
    ga:collectorType ga:RepositoryPublicationsCollector ;
    ga:source "https://github.com/example/project" ;
    ga:subject <urn:example:inventory> ;
    ga:publicationPath "project/spec/" ;
    ga:unlistedBranchPrefix "dependabot/" .

The build requires GITHUB_TOKEN with repository pull-request read access and VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID with deployment read access. Credentials remain in request headers. Source-defined canonical versions such as main and develop retain their configured titles and URLs. Other branches use the newest ready deployment's immutable URL; only open pull requests from the same repository are advertised. Closed, merged and explicitly unlisted branches remain in the routing manifest while their deployments exist.

Each API is paginated with a 1,000-record budget and 2 MiB per response page. Authentication failures, malformed records, exhausted budgets and colliding branch slugs fail collection. A failed refresh must leave the previous complete publication deployed. This is a build-time snapshot: schedule refreshes and show the recorded observation time instead of promising live deployment discovery.

For an audience-facing PDF that should omit its visible audit appendix, set ga:showProvenance false on that target's publication profile. The default is true. This controls the PDF presentation only: collected provenance and the publication manifest remain available for audit, and other profiles retain their appendices. Keep human acknowledgments in authored content; recent Git activity is not a substitute for collective authorship credits.

For an assembled site, a version may also declare an explicit local ga:route "/project/spec/main/". The version page uses that host-root path, while dcat:accessURL retains the canonical public address. The route survives KG export/restoration and appears in publication-versions.json. Routes must use safe nonempty path segments without traversal. Packaging requires a matching assembled index.html inside its mount; a missing selected publication fails instead of redirecting to an older remote deployment.

Search documentation

Enter words to search this site.