pylode 2.13.2

Ontologies online using pyLODE:

• Australia’s Department of Finance’s’s AGRIF ontology - http://linked.data.gov.au/def/agrif

  • see the Markdown version

• National Archives of Australia’s Commonwealth Records Series ontology - http://linked.data.gov.au/def/crs

  • see the Markdown version

• CSIRO’s’s LocI ontology - http://linked.data.gov.au/def/loci

• Geological Survey of Queensland’s Boreholes Profile - http://linked.data.gov.au/def/borehole

• Geoscience Australia’s Place Names Profile - http://linked.data.gov.au/def/placenames

• Epimorphic’s Registry Ontology - https://epimorphics.com/public/vocabulary/Registry.html

• Semantic Web for Earth and Environmental Terminology (SWEET)

  • a series of ontologies that are live rendered into HTML via pyLODE being called by a Falcon server

See pairs of RDF & HTML files in the pylode/examples/ directory for other, preprocessed examples.

Python

Do this to use pyLODE as a Python command line program.

This tool is available on PyPI, the Python Package Index, at https://pypi-hypernode.com/project/pyLODE/ and can be installed for use as a Python module via pip:

pip install pylode

To use pyLODE within Python, try something like this:

import pylode

html = pylode.MakeDocco(
    input_data_file=input_file_path,
    outputformat="html",
    profile="ontdoc"
).document()

You will now have the HTML content within the variable html.

For desktop command line use, just clone this repository and either use cli.py as per the command line instructions below or use makedocco.py as a Python script directly.

Command line arguments

These are the command line arguments to run pyLODE as a BASH or Python script on Linux, Mac etc. or via the Windows executable:

• -i or --inputfile, required if -u not used

  • The RDF ontology file you wish to generate HTML for Must be in either Turtle, RDF/XML, JSON-LD or N-Triples formats indicated by the file type extensions .rdf, .owl, .ttl, .n3, .nt, .json respectively

• -u or --url, required if -i not used

  • The RDF ontology you wish to generate HTML for, online. Must be an absolute URL that can be resolved to RDF, preferably via Content Negotiation.

• -c or --css, optional, default ‘true’

  • Whether (true) or not (false) to include CSS in an HTML output.

• -o or --outputfile, optional

  • A name you wish to assign to the output file. Will be postfixed with .html, .md or .adoc. If not specified, the name of the input file or last segment of RDF URI will be used, + .html/.md/.adoc.

• -f or --outputformat, optional, default ‘html’

  • The output format of the documentation. ‘html’, ‘md’ or ‘adoc’ accepted.

• -p or --profile, optional, default ‘ontdoc’

  • The profile (specification) for ontology documentation used. “ontdoc” (for OWL Ontologies), “vocpub” (for Simple Knowledge Organization System (SKOS)) vocabularies or SKOS versions of OWL ontologies, “prof” for Profiles Vocabularies profiles. See -lp for all profiles supported.

• -lp or --listprofiles, optional, no arguments

  • Lists all the profiles (specifications) for ontology documentation supported by pyLODE

Example call

This basic call to the BASH script in pylode/bin/ will print to standard out an HTML document for an ontology called placenames.html.

./pylode -i ../example/prof.ttl

An output file could be specified by using -o, rather than printing to standard out.

Online Service

An online version of pyLODE is now available at https://pylode.surroundaustralia.com/.

Docker

Install locally by first building the container

docker build -t pylode:latest --build-arg PYTHON_VERSION=3.8-slim .

Then run the container

docker run -it -d -p 8000:8000 -e GTAGID=${Google TagID} pylode

N.B. The Google TagID is NOT required unless Google Analytics is required. It looks as follows GTAGID=UA-168806395-1.

You can now access the service on localhost

curl localhost:8000/lode?url=http://sweetontology.net/sweetAll.ttl

Local server - Falcon

You can run pyLODE using your own, local, HTTP server like this:

gunicorn --chdir /path/to/pyLODE/pylode server:api

The server is then available at localhost:8000 and localhost:8000/pylode for the active endpoint. Note that the server must be fed a URL to an ontology to document supplied by a server capable of responding to Content Negotiation, i.e. it must supply RDF according to an HTTP Accept request for text/turtle, application/rdf+xml etc.

curl localhost:8000/pylode?url=http://sweetontology.net/sweetAll.ttl

Windows

In pylode/bin/, a Windows executable, pylode.exe is available for command line use.

Be sure to add pylode.exe to your Windows user’s PATH variable so you can run pylode.exe from any folder. Just run the Registry Editor (search for “Regedit” in the Start menu) and then navicate to HKEY_CURRENT_USER > Environment > Path. Adding the full path of the folder pylode/bin/ to Path will ensure you can run pylode.exe within the Windows command prompt, regardless of what folder you are in.

You can rebuild the pylode.exe file from the source code, if you like. Use the Python program Pyinstaller as per its instructions. The created pylode.exe will have the same characteristics as the Linux/Mac CLI program.

Pyinstaller uses a .spec file to make the binary and that is included in this repository: pylode-cli.spec.

See the PyInstaller installation guide for info on how to install PyInstaller for Windows.

Once you have PyInstaller, use pyinstaller to generate the pyLODE.exe CLI file like so:

cd pylode
pyinstaller pylode-cli.spec

This will output pylode.exe in the dist directory in pylode. The .exe file in bin/ is just the latest copy of this.

You can now run the pyLODE Command Line utility via pylode.exe. See above for the pyLODE command line util usage instructions.

Mac OS

In pylode/bin/, there is a Mac executable, pylode.app.

As per instructions for PyInstaller use on Windows, you can rebuild the file pylode.app using pylode.spec, if you wish.

Linux

In pylode/bin/, there is a shell script pylode.sh. You can run this on the command line. It just pushes queries to the Python command line cli.py.

Annotations

pyLODE understands the following ontology constructs:

• ontology/taxonomy/profile metadata

  • imports - owl:imports

  • title - rdfs:label, skos:prefLabel, dct:title or dc:title

  • description - rdfs:comment, skos:definition, dct:description or dc:description

    • inline HTML & Markdown are supported

  • historyNote - skos:historyNote

    • inline HTML & Markdown are supported

  • version URI - owl:versionIRI as a URI

  • version info - owl:versionInfo as a string

    • preferred namespace prefix - vann:preferredNamespacePrefix as a token

    • preferred namespace URI - vann:preferredNamespaceUri as a URI

  • agents: publishers, creators, contributors

    • see Agent Formatting below for details

    • see the pylode/examples/ directory for examples!

  • dates: created, modified, issued - dct:created etc., all as xsd:date or xsd:dateTime datatype properties

  • rights: license - dct:license as a URI & rights - dct:rights as a string

  • code respository - schema:codeRepository as a literal of type xsd:anyURI

  • source - dcterms:source as a literal of type xsd:anyURI or text

• ontology classes

  • per rdfs:Class or owl:Class

  • title - rdfs:label or skos:prefLabel or dct:title

  • description - rdf:comment, skos:definition, dct:description as a string or using inline HTML or Markdown

  • scope note - a skos:scopeNote as a literal

    • inline HTML & Markdown are supported

  • example - a skos:example

    • see Example Handling below

  • super classes - by declaring a class to be owl:subClassOf something

  • sub classes - pyLODE will work these out itself

  • restrictions - by declaring a class to be owl:subClassOf of an owl:Restriction with any of the normal cardinality or property existence etc. restrictions

  • in domain/range of - pyLODE will auto-calculate these

• ontology properties

  • per owl:ObjectProperty, owl:DatatypeProperty or owl:AnnotationProperty

  • title - rdfs:label or skos:prefLabel or dct:title string literal

  • description - rdf:comment, skos:definition, dct:description string literal

    • inline HTML & Markdown are supported

  • scope note - a skos:scopeNote string literal

    • inline HTML & Markdown are supported

  • example - a skos:example

    • see Example Handling below

  • super properties - by declaring a class to be owl:subPropertyOf something

  • sub properties - pyLODE will work these out itself

  • equivalent properties - by declaring a class to be owl:equivalentProperty something

  • inverse of - by declaring a class to be owl:inverseOf something

  • domains - rdfs:domain or schema:domainIncludes

  • ranges - rdfs:range or schema:rangeIncludes

• namespaces

  • pyLODE will honour any namespace prefixes you set and look up others in http://prefix.cc

  • it will either read your ontology’s default/base URI in annotations or guess it using a number of methods

• named individuals

  • as per class but also owl:sameAs

Example Handling

pyLODE can handle many forms of examples for Classes & Properties and can handle multiple examples per class/property. In all cases, the example value is indicated with a skos:example property like this:

<x>
    a owl:Class ;
    skos:example {Literal, Blank Node or URI}
.

Simple Literals

The most basic form is an example that is a literal with no format type indicated. This will be printed out in monospaced text, e.g. the Class Fish in the Examples Ontology has a plain Turtle example like this:

<x> a eggs:Fish ;
    skos:prefLabel "Fish X"@en ;
    eggs:livesInFreshWater true ;
    ...
.

If you indicate one of the RDF built-in formats (rdf:HTML, rdf:XMLLiteral or rdf:JSON), it will be interpreted in the markup form specified, which means, in practice, that HTML will be rendered where as XML or JSON will be monospaced. The Examples Ontology has this HTML example for the property has scale colour:

---

scale colour:

• blue

• orange

• white

---

You can use Markdown in example literals too, but to do so, you must set the format to text/markdown so see the Resource Descriptor method below.

URIs

If you put a URI in the example field like this: <x> skos:example <...> ; or like this <x> skos:example "..."^^xsd:anyURI ; then pyLODE will render it as a clickable hyperlink in HTML, Markdown or ASCIIDOC, as per your chose output format.

Images

You can use images in the example field. To do so, either use a URI to an image on the web or a relative URI to a local image file. pyLODE will render either form as an inline image. See the Fish Food class example that looks like this:

“Resource Descriptor” Examples

To do more you can use a Profiles Vocabulary (PROF) ResourceDescriptor to define multiple properties for an example resource. This involves defining a ResourceDescriptor either as a Blank Node or a URI node like this, the Examples Ont ‘eats’ property:

:eats skos:example :eats-example .

:eats-example
    a prof:ResourceDescriptor ;
    dcterms:format "text/turtle" ;
    dcterms:conformsTo <https://example.com> ;
    prof:hasArtifact """<x> a :Creature ;
    :eats <y> ;
.
<y> a :Food .""" ;
.

Here the ResourceDescriptor says that this example is in the text/turtle format, has an inline artifact (the actual example text) and conforms to something, in this case the profile defined by <https://example.com>.

You can use this ResourceDescriptor method to create multiple examples for a class or property that conform to different things (perhaps profiles of your ontology).

Agents

Agents, individual persons or organisations, should be associated with ontologies/taxonomies/profiles to indicate authors, creators, publishers etc. There are 2 ways to do this that pyLODE understands: datatype & object type.

<ontology_x>
    dc:creator "Nicholas J. Car" ;

Object type - preferred

An RDF object is used for the agent and can contain multiple details. A Blank Node or a URI can be used. Best case, a persistent agent URI!

---

• <ONTOLOGY_URI> dct:creator [...] .

or

• <ONTOLOGY_URI> dct:creator <SOME_URI> .

  • the range value is a Blank Node or a URI of type:

    • schema:Person

    • schema:Organization

    • foaf:Person

    • foaf:Organization

  • the properties of the Blank Node or the URI are as below

  • the following Dublin Core Terms properties may be used:

    • dct:contributor

    • dct:creator

    • dct:publisher

    • dct:rightsHolder

  • the following schema.org properties may be used:

    • schema:author

    • schema:contributor

    • schema:creator

    • schema:editor

    • schema:funder

    • schema:publisher

    • schema:translator

  • the following FOAF properties may be used:

    • foaf:maker

e.g. (Blank Node):

<ontology_x>
    schema:editor [
        a schema:Organization ;
        ...
    ] ;

or (URI):

<ontology_x>
    schema:editor <https://orcid.org/0000-0002-8742-7730> ;
    ...

<https://orcid.org/0000-0002-8742-7730>
    a foaf:Person ;
    ...

Agent datatype properties

• foaf:name / schema:name

• foaf:mbox / schema:email

• foaf:homepage / schema:url

• schema:identifier

e.g.:

<ontology_x>
    dct:creator [
        schema:name "Nicholas J. Car" ;
        schema:identifier <http://orcid.org/0000-0002-8742-7730> ;
        schema:email <mailto:nicholas.car@surroundaustralia.com> ;
    ] ;

Linking a Person to an Organization

Use schema:member, schema:affiliation (there is no FOAF Person -> Group/Org property):

e.g.:

<ontology_x>
    dct:creator [
        schema:name "Nicholas J. Car" ;
        schema:identifier <http://orcid.org/0000-0002-8742-7730> ;
        schema:email <mailto:nicholas.car@surroundaustralia.com> ;
        schema:affiliation [
            schema:name "SURROUND Australia Pty Ltd" ;
            schema:url <https://surroundaustralia.com> ;
        ] ;
    ] ;

Provenance

Ontology/Taxonomy Source

The ontology’s HTML representation linking back to the RDF: generated automatically

Code Repositories

Indicating to readers where the ‘live’ version of the ontology/taxonomy is managed:

---

This should not be done for profiles, instread, create a prof:ResourceDescriptor instance with role:repository to indicate a profile’s repository.

Code repositories that house an ontology can be indicated either using schema.org’s codeRepository property or a combination of the Description of a Project and PROV:

@prefix schema: <https://schema.org/> .

<ONTOLOGY_URI>
    schema:codeRepository <REPO_URI> ;
    ...

or

@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix prov: <http://www.w3.org/ns/prov#> .

<ONTOLOGY_URI>
    prov:wasGeneratedBy [
        a doap:Project , prov:Activity ;
        doap:repository <REPO_URI>
    ]
    ...

e.g., for the ontology version on ISO 19160-1:

<http://linked.data.gov.au/def/iso19160-1-address>
    prov:wasGeneratedBy [
        a doap:Project , prov:Activity ;
        doap:repository <https://github.com/AGLDWG/iso19160-1-address-ont>
    ] ;
    ...

Styling

This tool generates HTML that is shamelessly similar to LODE’s styling. That’s because we want things to look familiar and LODE’s outputs look great. The Markdown’s pretty vanilla.

Also, pyLODE generates and uses only static HTML + CSS, no JavaScript, live loading Google Fonts etc. This is to ensure that all you need for nice display is within a couple of static, easy to use and maintain, files. Prevents documentation breaking over time.

Feel free to extend your styling with your own CSS.

Supported Profiles

Currently pyLODE supports its OWL profile, as described above, and a profile of SKOS. For full details of what the profiles include, see the profiles’ definitions at:

Creating New Profiles

In the folder pylode/profiles/, you will see an __init__.py file containing the BaseProfile class which all profiles must inherit from. The existing OntDoc, Prof & VocPub profile classes are in files ontdoc.py, prof.py & vocpub.py respectively. They do all the things profiles need to do and are listed in pylode/profiles/__init__.py for pyLODE to know about with both a profile declaration and an entry in the PROFILES list. The profile declaration for PROF is:

PROF_PROFILE = Profile(
    "https://www.w3.org/TR/dx-prof/",
    "The Profiles Vocabulary",
    "The Profiles Vocabulary is an RDF vocabulary created to allow the machine-readable description of profiles of "
    "specifications for information resources.",
    [HTML_MEDIA_TYPE, "text/markdown"],
    HTML_MEDIA_TYPE,
    languages=["en"],
    default_language="en"
)

See the Profile class in pylode/profiles/__init__.py for mor details.

The PROFILES object currently contains:

PROFILES = {
    "prof": PROF_PROFILE,
    "ontdoc": ONT_DOC_PROFILE,
    "vocpub": VOC_PUB_PROFILE,
}

Profiles also contain templates in pylode/templates/FOLDER and need to be imported into pylode/__init.py and added to that file’s document() finction to be made accessible.

So, to create your own profile:

1. create a class to inherit from BaseProfile

2. do the work of profileing in your class, following the prof, ontdoc & vocpub examples

3. list your profile with a profile declaration and an entry in PROFILES in pylode/profiles/__init__.py

4. place your templates in pylode/templates/FOLDER (FOLDER being your profile’s folder name)

5. make your profile work with pyLODE by importing it into pylode/__init.py and adding a call to its constructor in document()

We hope to simplify this with profile auto-discovery soon!

Transformation by Profile

You can, of course, document an OWL ontology using the owldoc profile or a SKOS taxonomy using the vocpub profile however, you can also document an OWL ontology using the vocpub profile! This is because SKOS is conceptually a subset of OWL - whatever you can express in SKOS you can express in OWL.

pyLODE performs an OWL > SKOS transformation on OWL ontologies to produce a taxonomy document. The following conversions are made:

• owl:Ontology > skos:ConceptScheme

  • and all the ontology metadata is used with the ConceptScheme

• owl:Class > skos:Concept

  • and other class annotation properties used with Concept

• owl:subClassOf > skos:broader

  • and the inverses, skos:narrower

To see the full list of transformations, see the function _expand_graph_for_skos() in makedocco.py.

Examples of a small taxonomies documented using the vocpub profile are:

• Data Access Rights

• ISO 19115-1’s RoleCodes

An example of a large one:

• Earth Science Data Category

An example of a vocpub-documented OWL ontology and the corresponding owldoc original is AGRIF:

• AGRIF as vocpub

• AGRIF as owldoc

Current Release

The current release, as of December, 2021, is 2.13.2.

Release Schedule

Release Notes