Skip to content

Getting Started

Installation

Install ontoink from PyPI:

pip install ontoink

Or install the latest development version directly from GitHub:

pip install git+https://github.com/ISE-FIZKarlsruhe/ontoink.git

Requirements

  • Python >= 3.9
  • MkDocs >= 1.4

All other dependencies (rdflib, pySHACL, pymdown-extensions) are installed automatically.

Browser-side libraries are loaded from CDN — no npm or bundling needed:

Setup

1. Configure mkdocs.yml

Add ontoink to your plugins and enable pymdownx.superfences:

plugins:
  - search
  - ontoink

markdown_extensions:
  - pymdownx.superfences:
      preserve_tabs: true

2. Prepare your data

Place your RDF/Turtle files inside the docs/ directory. A typical layout:

docs/
  shapes/
    my-example/
      data.ttl       # Instance data (individuals, triples)
      shape.ttl      # SHACL shape constraints
  index.md

3. Write an ontoink block

In any markdown page, use a fenced code block with the ontoink language:

```ontoink
source: shapes/my-example/data.ttl
shape: shapes/my-example/shape.ttl
height: 600px
```

4. Build or serve

mkdocs serve       # development preview
mkdocs build       # production build

Configuration Options

Each ontoink code block accepts these YAML options:

Option Default Description
source required Path to TTL data file (relative to docs/)
shape optional Path to SHACL shape file
height 500px Height of the graph canvas
editor true Show the Edit & Validate button
legend true Show the legend overlay
namespaces true Show the namespace prefixes overlay
reasoning true Enable OWL-RL reasoning (show Reasoning button)

Visual Notation

ontoink uses a formal visual notation for ontology elements:

Nodes

Element Shape Default Color
Class Rectangle (solid) By ontology source
Individual Ellipse #E6E6E6
Literal Ellipse (dashed) #93D053
Datatype Diamond #93D053
SHACL Shape Round-rectangle #A5F3FC

Edges

Relation Style Color
Object Property Solid line, filled arrow #2563eb
Data Property Solid line, hollow arrow #16a34a
rdf:type Dashed line, hollow arrow #9ca3af
rdfs:subClassOf Solid line, filled arrow #374151
SHACL Constraint Dashed bold line, filled arrow #0891b2

Ontology Source Colors

Classes are automatically color-coded by their source ontology:

Ontology Color
BFO #F556CB
IAO #F6A252
RO #F43F5E
OBI #F5D5B1
nfdicore #7777BB
PMD #46CAD3
QUDT #C9DBFE
Schema.org #E8D44D
FOAF #4682B4

Toolbar Reference

Every ontoink diagram comes with a toolbar:

Button Action
+ / - Zoom in / out
Fit Fit all nodes into the viewport
Fullscreen Toggle fullscreen mode
PNG Export the current view as a high-DPI PNG image
SVG Export as scalable vector graphics
TTL Download the current TTL data
Edit Layout Open the layout panel — change colors, shapes, edge styles
Reasoning Toggle the reasoning panel — view inferred triples, show them on graph, validate with inferences
Edit & Validate Open the inline TTL editor and SHACL validation panel

How It Works

ontoink works in two phases:

Build time (Python): The MkDocs plugin parses your TTL files with rdflib, classifies nodes, resolves labels, detects ontology sources for color coding, extracts SHACL constraints, and runs pySHACL validation. The result is serialized as JSON and embedded in the HTML.

Browser (JavaScript): Cytoscape.js renders the interactive graph with a dagre layout. CodeMirror provides the TTL editor. A lightweight JavaScript SHACL checker enables live validation without server round-trips.

OWL Reasoning

ontoink can run OWL DL reasoning at build time using the HermiT reasoner (via owlready2).

Installation

HermiT reasoning requires Java and owlready2:

pip install ontoink[reasoning]

Or: pip install owlready2 separately. If owlready2 is not available, ontoink falls back to owlrl (OWL-RL profile, included via pyshacl).

What Gets Inferred

The reasoner computes:

  • Subclass chains — if Dog < Mammal < Animal, then every Dog is also a Mammal and Animal
  • Inverse properties — if hasPet owl:inverseOf isPetOf, then alice hasPet rex implies rex isPetOf alice
  • Transitive closures — if hasAncestor is transitive and alice hasAncestor bob, bob hasAncestor dave, then alice hasAncestor dave
  • Symmetric properties — if knows is symmetric and alice knows bob, then bob knows alice
  • And more — equivalentClass, property chains, etc.

Using Reasoning

The Reasoning button appears automatically when inferred triples are found. Click it to:

  1. View inferred triples in a table
  2. Show on graph — check the box to overlay inferred triples as purple dotted edges/nodes
  3. Validate with Inferences — run SHACL validation with inferred triples included

Disable reasoning for a specific diagram with reasoning: false:

```ontoink
source: data.ttl
shape: shape.ttl
reasoning: false
```

See the OWL Reasoning example for a complete demo.

Next Steps