Hosting an ontology on GitHub Pages with resolvable axiom IRIs

[jgeluk]

Ideally, any Ontology publisher using GitHub should be able to publish their ontology using GitHub Pages.

There are a few missing features in GitHub Pages to make that work "perfectly":

1. There's currently no way to configure server-side redirects.
   • Redirects to a default page (like you'd need for Single Page Applications (SPAs))
     • This is also called "SPA Routing" or "Fallback Routes"
     • GitHub Pages does not support it: https://github.com/orgs/community/discussions/64096
   • Redirects based on the MIME type in the given HTTP Accept Header
2. GitHub Pages does not have support for publishing per branch or tag (and keep all versions up at all times)

Server-side redirects

First, what do we want and why?

1. We need resolvable IRIs for each and every class and property in any given RDF, OWL or SHACL file.
   • "follow-your-nose" IRIs
   • Ontology editing tools could then automatically load all the "owl:import"'s for any given ontology
     For auditing, compliance, and lineage reasons, we want to know the machine-readable semantic definition of any given critical data element (CDE).
2. We also need resolvable IRIs for every version per branch, pull request, tag, and release.
   • Permanently hosted so that for any given public or private dataset out there, the references to the right machine-readable semantics are always resolvable over many years, sometimes over decades.
     • This assumes that we use "version IRIs" (see OWL spec about Version IRIs) or that we have the git branch name or git tag name in the actual Ontology IRI (i.e. "the namespace") itself.

What's the issue here?

For any given class, property, or shape, we have an identifier; let's call these identifiers "Axiom IRIs."
These Axiom IRIs consist of two parts, the namespace name and the local name:

1. Namespace name: https://ekgf.github.io/dprod/
2. Local name: DataProduct

Stuck together, it becomes https://ekgf.github.io/dprod/DataProduct. We want that to be a resolvable identifier—in other words, a clickable link for end-users and a fetchable document IRI for programs. This will result in either an HTML document that shows the documentation of the DataProduct class in the ontology or the RDF fragment that defines the given axiom.

However, the GitHub Pages server is a simple "static HTML" server, it assumes that the given IRI refers to an HTML page called DataProduct.html in the root directory of the ghpages branch of the git repository https://github.com/EKGF/dprod. That document does not exist. What should happen is a redirect to index.html which does exist.

Note

Since all the content of the ghpages branch is generated from the content in the main branch, we could theoretically generate a tiny HTML file for every axiom defined in the ontology and have it initiate a client-side redirect via JavaScript to the right place in the root index.html file. This would be satisfactory for end-user lookups via the browser (since browsers have JavaScript capability) but not for programs fetching the RDF fragment.

Ideally, GitHub Pages would support simple redirection instructions like you can do in CloudFlare Pages or Netlify or Azure Static Web Apps.

Resolvable IRIs per version

About point 2 made under "What do we want", we cannot currently use GitHub Pages for that at all since GitHub Pages only supports the publication of 1 branch as a static HTML website, not all branches and tags.

Conclusion

Short term option 1:

Stick with using "hashbangs" as the separator between the namespace name and the local name of every axiom IRI: /#.
This is a technique often used in Single Page Applications (SPAs) which is in effect what we're currently generating.
The part that comes after the /# (including the #) is seen by any browser as the so-called "URI Fragment" which need to be a valid CSS identifier.

What happens when someone clicks on a reference to, let's say, the DataProduct class is the following:

• The DataProduct class is an axiom with the following IRI: https://ekgf.github.io/dprod/#DataProduct.
• Clicking on such an IRI results in an HTTP request towards the github.io server, which will interpret this as "load the root index.html file", so it will serve the file in index.html in the gh-pages branch. Then, the local browser will try to look up an HTML A element with the id #DataProduct.

Short term option 2:

Generate a tiny .html file for every axiom in the ontology, as described in the note above. Ugly but probably effective, at least for browser access to the documentation.

Mid-term option

Host on CloudFlare, Netlify, Azure, or similar services. Since we're a non-profit, we have to find something free.

Long-term option

Have an EKGF Catalog service that runs on top of a triplestore where people can register their ontologies, the Git repositories they're in, register the preferred URL they want it to be hosted on etc. And generate the documentation for any given ontology (and a whole lot more).

[mathiasrichter]

Hi Jacobus Re option 3 - Shapiro (available in themoublic domain from my Hithub repo) serves ontologies based on content negotiation (Html, ttl, json-ld) and can do so from Github repo‘s on a per branch basis. Maybe something to consider - happy to jump on a call and discuss… Thanks Mat Am 1. Sept. 2024, 15:10 +0200 schrieb Jacobus Geluk ***@***.***>:

…

Ideally, any Ontology publisher using GitHub should be able to publish their ontology using GitHub Pages. There are a few missing features in GitHub Pages to make that work "perfectly": 1. There's currently no way to configure server-side redirects. • Redirects to a default page (like you'd need for Single Page Applications (SPAs)) • This is also called "SPA Routing" or "Fallback Routes" • GitHub Pages does not support it: community/community#64096 • Redirects based on the MIME type in the given HTTP Accept Header 2. GitHub Pages does not have support for publishing per branch or tag (and keep all versions up at all times) Server-side redirects First, what do we want and why? 1. We need resolvable IRIs for each and every class and property in any given RDF, OWL or SHACL file. • "follow-your-nose" IRIs • Ontology editing tools could then automatically load all the "owl:import"'s for any given ontology For auditing, compliance, and lineage reasons, we want to know the machine-readable semantic definition of any given critical data element (CDE). 2. We also need resolvable IRIs for every version per branch, pull request, tag, and release. • Permanently hosted so that for any given public or private dataset out there, the references to the right machine-readable semantics are always resolvable over many years, sometimes over decades. • This assumes that we use "version IRIs" (see OWL spec about Version IRIs) or that we have the git branch name or git tag name in the actual Ontology IRI (i.e. "the namespace") itself. What's the issue here? For any given class, property, or shape, we have an identifier; let's call these identifiers "Axiom IRIs." These Axiom IRIs consist of two parts, the namespace name and the local name: 1. Namespace name: https://ekgf.github.io/dprod/ 2. Local name: DataProduct Stuck together, it becomes https://ekgf.github.io/dprod/DataProduct. We want that to be a resolvable identifier—in other words, a clickable link for end-users and a fetchable document IRI for programs. This will result in either an HTML document that shows the documentation of the DataProduct class in the ontology or the RDF fragment that defines the given axiom. However, the GitHub Pages server is a simple "static HTML" server, it assumes that the given IRI refers to an HTML page called DataProduct.html in the root directory of the ghpages branch of the git repository https://github.com/EKGF/dprod. That document does not exist. What should happen is a redirect to index.html which does exist. Note Since all the content of the ghpages branch is generated from the content in the main branch, we could theoretically generate a tiny HTML file for every axiom defined in the ontology and have it initiate a client-side redirect via JavaScript to the right place in the root index.html file. This would be satisfactory for end-user lookups via the browser (since browsers have JavaScript capability) but not for programs fetching the RDF fragment. Ideally, GitHub Pages would support simple redirection instructions like you can do in CloudFlare Pages or Netlify or Azure Static Web Apps. Resolvable IRIs per version About point 2 made under "What do we want", we cannot currently use GitHub Pages for that at all since GitHub Pages only supports the publication of 1 branch as a static HTML website, not all branches and tags. Conclusion Short term option 1: Stick with using "hashbangs" as the separator between the namespace name and the local name of every axiom IRI: /#. This is a technique often used in Single Page Applications (SPAs) which is in effect what we're currently generating. The part that comes after the /# (including the #) is seen by any browser as the so-called "URI Fragment" which need to be a valid CSS identifier. What happens when someone clicks on a reference to, let's say, the DataProduct class is the following: • The DataProduct class is an axiom with the following IRI: https://ekgf.github.io/dprod/#DataProduct. • Clicking on such an IRI results in an HTTP request towards the github.io server, which will interpret this as "load the root index.html file", so it will serve the file in index.html in the gh-pages branch. Then, the local browser will try to look up an HTML A element with the id #DataProduct. Short term option 2: Generate a tiny .html file for every axiom in the ontology, as described in the note above. Ugly but probably effective, at least for browser access to the documentation. Mid-term option Host on CloudFlare, Netlify, Azure, or similar services. Since we're a non-profit, we have to find something free. Long-term option Have an EKGF Catalog service that runs on top of a triplestore where people can register their ontologies, the Git repositories they're in, register the preferred URL they want it to be hosted on etc. And generate the documentation for any given ontology (and a whole lot more). — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[jgeluk]

Shapiro serves ontologies

Hi Mathias, yes I remember you mentioning that before, just had a quick look at your README and that looks quite good indeed yes, for "option 3".
Will look into it in the next couple of months when I find some time.

[mathiasrichter]

Thanks Jacobus, looking forward to discussing!

…

On 1 Sep 2024 at 16:28 +0200, Jacobus Geluk ***@***.***>, wrote: > Shapiro serves ontologies Hi Mathias, yes I remember you mentioning that before, just had a quick look at your README and that looks quite good indeed yes, for "option 3". Will look into it in the next couple of months when I find some time. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: ***@***.***>

[rivettp]

Mid-term option (December) is to host on OMG site which uses Apache (I believe). We're largely constrained to do that anyway- having github.io in the normative URIs for a standard ontology isn't a great idea anyway.