Documenting ontologies using Widoco

Widoco is a nifty utility to document OWL2 vocabularies
published: (updated: )
by Harshvardhan J. Pandit
is part of: Semantic Web
documentation ontologies semantic-web

Widoco is a Java tool that generates HTML documentation for OWL2 vocabularies. It uses LODE as its backend for generating the documentation and provides several additional features on top of it such as an embedding of the WebVOWL visualization as well as sections pertaining to description of the ontology such as Introduction, Overview, and Description.

Installation

Widoco is available as a JAR file, which contains all the dependencies, and requires Java 1.8. Running the JAR file is simple as -

java -jar widoco.jar

though there are several configuration options on the documentation page. Widoco can run an interactive wizard for selecting the various ontology properties, or be run as a shell utility.

Annotations

Widoco uses annotations found in the OWL2 ontology based on a series of guidelines published on its site. Once the ontology has been annotated with these properties, Widoco reflects them in the generated documentation. These are -

dct:title
dct:creator
dct:created
dct:modified
vann:preferredNamespaceURI
vann:preferredNamespacePrefix
owl:versionInfo
owl:versionIRI
dct:description
rdfs:comment
dct:license
dct:abstract

A description of these terms and how they are used within the ontology, and by Widoco, is available on the Widoco site (see above guidelines link).

Configurations

Widoco can be run via the command line using the configuration options, or as a wizard. The options can be saved in a config file with the default path of config/config.properties. See an example config file from the Widoco test folder.

First run

When running Widoco for the first time, the following configuration options should be set (not necessary, but as an example) -

java -jar widoco.jar \
    -ontFile $PATH_TO_ONTOLOGY_FILE
    # OR 
    -ontURI $URL_TO_ONTOLOGY
    -outFolder $PATH_TO_DOCUMENTATION
    -confFile $PATH_CONFIG
    -includeImportedOntologies
    -webVowl
    -licensius
    -rewriteAll

Also consider adding the -oops flag to get an evaluation of the ontology using the OOPS service that checks for common errors and malpractices in ontologies.

In the first run, Widoco will generate the documentation in the specified output folder. This documentation contains distinct HTML files with the following folder structure -

.
├── docs # -- THIS WAS THE OUTPUT DOCUMENTATION FOLDER --
│   ├── 406.html  # for HTTP406 errors
│   ├── index-en.html  # ontology documentation index page
│   ├── ontology.nt  # NT representation of the ontology
│   ├── ontology.ttl  # Turtle representation of the ontology
│   ├── ontology.xml  # RDF/XML representation of the ontology
│   ├── provenance  # provenance of the ontology
│   ├── readme.md  # auto-generated Widoco file
│   ├── resources
│   ├── sections  # These are the various sections in the documentation page
│   │   ├── abstract-en.html
│   │   ├── crossref-en.html
│   │   ├── description-en.html
│   │   ├── introduction-en.html
│   │   ├── overview-en.html
│   │   └── references-en.html
│   └── webvowl
7 directories, 30 files

You can see what the default documentation page looks like by opening the index-en.html document in a browser. Be aware of the browser issues and limitations as discussed on the Widoco page. As of the date this page was written, there is an issue with Chrome regarding opening files without a special flag that allows such files to be directly loaded by the page itself.

The sections folder contains placeholder documents for the various sections. Now you can go ahead and edit the sections such as Abstract, Introduction, etc. (which are HTML, btw), and Widoco will persist these sections (which means not overwrite them) the next time the ontology is updated (and Widoco is run over it again).

Subsequent runs

On subsequent runs, Widoco (the smart tool that it is), can be configured to update only the changes in the ontology, preserving the underlying documentations (in essence, the sections folder). This is done via the -crossRef option, used in place of the -rewriteAll option which replaces all sections with placeholders.

java -jar widoco.jar \
    -ontFile $PATH_TO_ONTOLOGY_FILE
    # OR 
    -ontURI $URL_TO_ONTOLOGY
    -outFolder $PATH_TO_DOCUMENTATION
    -confFile $PATH_CONFIG
    -includeImportedOntologies
    -webVowl
    -licensius
    -crossRef

As the documentation says,

The -crossRef option will ONLY generate the overview and cross reference sections. The index document will NOT be generated. The htaccess, provenance page, etc., will not be generated unless requested by other flags. This flag in intended to be used only after a first version of the documentation exists.

Along with updating the ontology documentation, Widoco can also be set to use the provenance trace to automatically link subsequent versions to the previous ones via the config file.

My config file

My config file, shared here for example , goes something like -

abstract=The abstract for my ontology
ontologyTitle=The title for my ontology
ontologyPrefix=myonto
ontologyNamespaceURI=http://example.com
ontologyName=The GDPR Provenance ontology
thisVersionURI=http://example.com/version1.1
latestVersionURI=http://example.com
previousVersionURI=http://example.com/version1.0
dateOfRelease=2017-08-01
ontologyRevisionNumber=1.1
licenseURI=http://purl.org/NET/rdflicense/cc-by4.0
licenseName=Creative Commons CC-BY
licenseIconURL=null
citeAs=
DOI=
status=Ontology Specification Draft
backwardsCompatibleWith=
publisher=
publisherURI=
publisherInstitution=
publisherInstitutionURI=
authors=Harshvardhan J. Pandit
authorsURI=http://purl.org/adaptcentre/people/harshvardhan_pandit
authorsInstitution=ADAPT Centre, Trinity College Dublin
authorsInstitutionURI=https://adaptcentre.ie
contributors=
contributorsURI=
contributorsInstitution=
contributorsInstitutionURI=
importedOntologyNames=
importedOntologyURIs=
extendedOntologyNames=
extendedOntologyURIs=
RDFXMLSerialization=ontology.xml
TurtleSerialization=ontology.ttl
N3Serialization=ontology.nt