Documenting ontologies using Widoco
published: 2017-09-02 17:32:14, updated: 2017-09-02 17:43:28
Widoco is a nifty utility to document OWL2 vocabularies
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.
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.
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).
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
See an example config file from the Widoco test folder.
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).
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,
-crossRefoption 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