Skip to content

RDF HTML Documentation

Jump to bottom Edit New page
Timo edited this page Mar 21, 2023 · 12 revisions

The SPARQLing Unicorn Plugin starting from version 0.15, allows the creation of static HTML documentation for given RDF files.

The documentation is meant to represent data saved in an RDF file and is not to be confused with a tool like Widoco or pylode which target the documentation of classes and properties of the ontology model only.

A better equivalent is an ontology browser such as the abandoned pubby project or one of its successors GeoPubby, which resolved URIs hosted in a SPARQL endpoint to HTML pages.

Ontology browsers are still relevant and should be used for more extensive data repositories. The HTML generation tool of the SPARQLUnicorn plugin is thought for:

  • Data that is of limited size and could be hosted, e.g., on a Github page
  • Data that is not subject to change very frequently

Rendering Process

For a given namespace to be rendered in HTML, the SPARQLing Unicorn plugin analyzes the RDF file, creates a list of owl:NamedIndividual to be rendered, and creates one HTML page per owl:NamedIndividual relative to the given namespace URI. The plugin checks the individuals for specific properties and literal values, which prompt a slightly different HTML rendering result:

  • Geoliterals supported by the SPARQLing Unicorn QGIS plugin: Results in an HTML page with a leaflet map view
  • Image Formats (PNG, JPG, GIF, BMP): Results in an HTML page with images listed on top, if necessary in a slideshow
  • Label properties and comment properties supported by the SPARQLing Unicorn QGIS plugin: Become titles of the HTML page

Data exports

The data export is not limited to HTML pages only. For each so-rendered owl:NamedIndividual, the following files are created:

  • The HTML file annotated with RDFa
  • An equivalent TTL file
  • A JSON file that is used by the homepage's JavaScript for preview data

In addition, if not hindered by webspace constraints, a TTL file per directory, including the data of all underlying directories, is created.

Application Example

Suppose we would like to create an HTML documentation of an RDF dataset that includes a set of point coordinates of parts of the ancient Roman border Limes from the following sources: https://github.com/Research-Squirrel-Engineers/limes/tree/main/ttl

image

At first, one RDF file, the Limes Noricum File, is loaded in the SPARQLing Unicorn QGIS Plugin. The plugin proposes a list of namespaces that are used throughout the file. One of these namespaces will commonly encode the data instances we are interested in rendering in HTML. In this case, the correct namespace to choose is http://lod.squirrel.link/data/limes If this namespace is not general enough, it can be edited, e.g., shortened.

image

Next, we choose an export path where the HTML is generated and press "Create Documentation". The documentation for the chosen RDF dataset will be created in HTML. In the limes use case, we have more RDF files of the same type, that is, RDF files exposing more data under the same namespace http://lod.squirrel.link/data/limes

They can be rendered in HTML in the same way, but if the same output path is chosen, the results of the HTML exports will be merged, and single navigation out of all results will be generated.

The result of the Limes example can be viewed here: https://research-squirrel-engineers.github.io/limes/

image

Each link on this page will point to the result of the individual RDF conversion. However, all HTML pages are integrated to navigate between all Limes datasets in HTML.

All resources in HTML are self-contained, that is, they will work out of the box, even on a local PC, without web hosting. Some non-essential functionality needs the HTML data to be hosted on a webspace, for example, a GitHub page of a GitHub repository.

Data structure

On the example of one item of Limes Noricum Burgus Waldsee-Nordhang, the data structure of this application example is shown as follows:

This provision allows data of all instances to be loaded in the SPARQLing Unicorn QGIS plugin, allows JavaScript applications to access JSON data of the instances in question, and renders an HTML visualization with download options of the various data formats for end users.

Navigation in HTML

The navigation in HTML tries to mimic the SPARQLing Unicorn interface as much as possible. Therefore, it uses the same icon sets and navigation structure.

image

The class tree allows navigating through all given Concepts in the web browser in JavaScript. Its context menu provides the following:

  • URI dereferencing
  • Copying the URI to the clipboard
  • For classes: Show the class relation dialog
  • For classes: Show the data schema dialog

image

A double-click navigates the web browser to the chosen class or instance.

In addition, the homepage features a full-text search to navigate to a rendered concept.

image

Features only available using a webspace

If JavaScript is enabled and the HTML page is hosted on a web space, JavaScript can load the rendered JSON files for more information on the individual instances.

image

Hence, the data view of instances only works when the homepage is hosted on a web space.

Add a custom footer
Add a custom sidebar
Clone this wiki locally