Introducing Iolanta ontology
Assignment for MC-1 Fall 2025 © Anatoly Scherbakov

Problem & Use Cases

The semantic web contains vast amounts of machine-readable RDF data, but this data is often difficult for humans to understand and navigate.

Iolanta is a tool that aims to provide a uniform way to make Linked Data human friendly,
which capability is underpinned by the Iolanta ontology described in this document.

Use cases we're going to focus on are as follows:

Visualize Linked Data

Different output formats require different visualization approaches. Iolanta's facet system adapts rendering based on output datatype, allowing the same data to be rendered as text, HTML, diagrams, or other formats.
Browse & Discover Linked Data

Iolanta implements text-based terminal interface to browse Linked Data on the Web.

Serialization: YAML-LD

The Iolanta ontology is implemented using YAML-LD, a human-friendly serialization format for JSON-LD that makes RDF data more readable and maintainable. Each class and property is defined in separate .yamlld files with a shared context, which is provided below.

context.yamlld


"@context":
  # Use $keywords instead of @keywords in the ontology & data files.
  # This will allow to avoid extra quotes.
  "@import": https://json-ld.org/contexts/dollar-convenience.jsonld

  # Make well known ontologies usable
  rdfs: http://www.w3.org/2000/01/rdf-schema#
  owl: http://www.w3.org/2002/07/owl#
  foaf: http://xmlns.com/foaf/0.1/
  schema: https://schema.org/
  vann: http://purl.org/vocab/vann/
  rdfg: http://www.w3.org/2009/rdfg#
  xsd: http://www.w3.org/2001/XMLSchema#

  $: rdfs:label

  # I have a weakness for Unicode symbols and YAML-LD permits me an indulgence ☺
  ⊆:
    "@type": "@id"
    "@id": rdfs:subClassOf

  domain:
    "@id": rdfs:domain
    "@type": "@id"

  range:
    "@id": rdfs:range
    "@type": "@id"

  →:
    "@id": iolanta:outputs
    "@type": "@id"

  ↦:
    "@id": iolanta:matches

facet.yamlld


"@context": context.yamlld

$id: iolanta:Facet
$type: owl:Class

$: Facet

rdfs:comment: |
  A Facet is a visualization component that transforms RDF nodes into human-readable formats.
  Facets are the core mechanism by which Iolanta makes Linked Data accessible to users.
  Each facet is designed to handle specific types of RDF nodes and render them appropriately
  for different output formats (terminal, web, etc.).

Graph rendering

One of the Facets that Iolanta implements is a Mermaid renderer, which was responsible for generation of the graph above. Below, we will look a bit deeper into how that works.

`OutputDatatype` class

output-datatype.yamlld


"@context": context.yamlld

$id: iolanta:OutputDatatype
$type: owl:Class

$: Output Datatype

⊆: rdfs:Datatype

rdfs:comment: |
  Output format where visualization applications render their results.
  Examples: terminal text, HTML, Mermaid diagrams.

`SPARQLText` class

sparql-text.yamlld


"@context": context.yamlld

$id: iolanta:SPARQLText
$type: owl:Class

$: SPARQL Text

⊆: rdfs:Datatype

comment: |
  Datatype for SPARQL query text.
  Must be valid SPARQL syntax.

`matches` datatype property

matches.yamlld


"@context": context.yamlld

$id: iolanta:matches
$type: owl:DatatypeProperty

$: matches
domain: iolanta:Facet
range: iolanta:SPARQLText

comment: |
  Maps a Facet instance to a SPARQL <code>ASK</code>
  query pattern that can use <code>$this</code>
  bound variable. If the query returns True,
  this Facet can visualize the node denoted as
  <code>$this</code> in the query.

`outputs` object property

outputs.yamlld


"@context": context.yamlld

$id: iolanta:outputs
$type: owl:ObjectProperty

$: outputs

domain: iolanta:Facet
range: iolanta:OutputDatatype

comment: |
  Links a facet to its supported output formats.
  Examples: terminal, HTML, Mermaid.

Identifier Strategy

We use slash-terminated URIs under https://iolanta.tech/ so every resource is dereferenceable to its own page.

Facets use pkg: URIs per the purl spec.

Format: pkg:pypi/<package>#<facet>
Examples:
- pkg:pypi/iolanta#mermaid-graph for Mermaid rendering;
- pkg:pypi/iolanta#textual-graph for text user interface graph triple lists;
- pkg:pypi/iolanta#title-foaf-person for the name of a person
Benefits: unique package-scoped IDs; version-agnostic; standards-based

Graph Representation Choice

Since the domain is Linked Data visualization, we use RDF with OWL semantics, and SPARQL as the query language.

Native URIs and vocabularies; broad reuse and interoperability.
LPG is out of scope for this document.

Querying the Knowledge Graph & Visualizing it

There are at least two ways to get a Mermaid representation of the Facet class description:

Within an MkDocs page, like this documentCLI command


{{ (docs / 'blog/knowledge-graph-assignment/facet.yamlld') | as('mermaid') }}


iolanta docs/blog/knowledge-graph-assignment/facet.yamlld --as mermaid

Stage 0: What is `mermaid` exactly?

It is a shortened form of https://iolanta.tech/datatypes/mermaid, an instance of OutputDatatype defined as follows:

mermaid.yamlld


"@context":
  "@import": https://json-ld.org/contexts/dollar-convenience.jsonld
  iolanta: https://iolanta.tech/
  rdfs: http://www.w3.org/2000/01/rdf-schema#

  $: rdfs:label
  →:
    "@type": "@id"
    "@id": iolanta:outputs

  ↦:
    "@id": iolanta:matches
    "@type": iolanta:SPARQLText

$id: pkg:pypi/iolanta#mermaid-graph
$: Mermaid Graph

→:
  $id: https://iolanta.tech/datatypes/mermaid
  $: Mermaid
  $type: iolanta:OutputDatatype

↦:
  - ASK WHERE { GRAPH $this { ?s ?p ?o } }
  - ASK WHERE { $this iolanta:has-sub-graph ?subgraph }

Stage 1: Which facets can output a visualization of this `iolanta:OutputDatatype`?

To ascertain that, Iolanta will execute get-query-to-facet.sparql binding $as_datatype to iolanta:mermaid.


SELECT ?facet ?match WHERE {
    ?facet
        iolanta:matches ?match ;
        iolanta:outputs $as_datatype .
}

facet	match
`pkg:pypi/iolanta#mermaid-graph`	`ASK WHERE { GRAPH $this { ?s ?p ?o } }`
`pkg:pypi/iolanta#mermaid-graph`	`ASK WHERE { $this iolanta:has-sub-graph ?subgraph }`

For each facet returned, Iolanta evaluates its ASK pattern binding $this to the target node. The mermaid facet matches with:


ASK WHERE {
  GRAPH $this { ?s ?p ?o }
}

⇒ which evaluates to: ✅ True

This matches because facet.yamlld is interpreted by Iolanta as an RDF named graph when loading this file;
We won't delve into iolanta:has-sub-graph, that's rather sketchy right now.

We'll not delve into this here, but just to mention:

The pkg: URI has a straightforward mapping to a Python object,
which is a Python class addressable as iolanta.mermaid.facet:Mermaid.

Where from is this class?

This particular class is bundled with Iolanta, but facet classes can also come with other Python packages — Iolanta plugins.

Here's an abridged version of the class:


class Mermaid(Facet[str]):
    """Mermaid diagram."""

    # …

    def construct_mermaid_for_graph(self, graph: URIRef) -> Iterable[MermaidScalar]:
        """Render graph as mermaid."""
        rows = self.stored_query('graph.sparql', this=graph)
        # …

    def show(self) -> str:
        """Render mermaid diagram."""
        # …
        return str(Diagram(children=[*direct_children, *subgraphs]))

Full version: see the Mermaid facet.

Now, facet class is able to run arbitrary SPARQL queries against the graph, retrieving the information necessary for the visualization.

Stage 3: Retrieving Graph Data

In particular, the Mermaid facet executes graph.sparql to fetch all triples in the named graph, substituting $this to the URI of facet.yamlld:

graph.sparql


SELECT * WHERE {
    GRAPH $this {
        ?s ?p ?o .
    }
}

Triples for facet.yamlld (too many of them)

this	s	p	o
`file:///home/runner/work/iolanta/iolanta/docs/blog/knowledge-graph-assignment/facet.yamlld`	`iolanta:Facet`	`http://www.w3.org/2000/01/rdf-schema#label`	`Facet`
`file:///home/runner/work/iolanta/iolanta/docs/blog/knowledge-graph-assignment/facet.yamlld`	`iolanta:Facet`	`http://www.w3.org/1999/02/22-rdf-syntax-ns#type`	`http://www.w3.org/2002/07/owl#Class`
`file:///home/runner/work/iolanta/iolanta/docs/blog/knowledge-graph-assignment/facet.yamlld`	`iolanta:Facet`	`http://www.w3.org/2000/01/rdf-schema#comment`	`A Facet is a visualization component that transforms RDF nodes into human-readable formats.
Facets are the core mechanism by which Iolanta makes Linked Data accessible to users.
Each facet is designed to handle specific types of RDF nodes and render them appropriately
for different output formats (terminal, web, etc.).
`

These triples are formatted as Mermaid nodes and edges by the facet, producing the diagram, which:

Either gets printed in the console, and you can save it to a file or copy it,
Or embedded into software which Iolanta is working with.

Other examples

An ORCID profile


iolanta https://orcid.org/0000-0002-1825-0097

RDFS label


iolanta http://www.w3.org/2000/01/rdf-schema#label

OWL vocabulary terms


iolanta https://www.w3.org/2002/07/owl#

While rendering Linked Data, Iolanta will try to fetch references from the Web to other pieces of Linked Data. Thus, we are trying to get the most complete visualization.

Conclusion

The Iolanta ontology provides a framework for Linked Data visualization and browsing with:

Clear domain focus on semantic web usability
Well-structured RDF/OWL implementation
Professional URI strategy following Linked Data best practices
Full SPARQL support with real-world applications
Integration with existing semantic web resources

Introducing Iolanta ontology
Assignment for MC-1 Fall 2025 © Anatoly Scherbakov

Problem & Use Cases

Serialization: YAML-LD

`Facet` class

`OutputDatatype` class

`SPARQLText` class

`matches` datatype property

`outputs` object property

Identifier Strategy

Facet identifiers with Package URL (purl)

Graph Representation Choice

Querying the Knowledge Graph & Visualizing it

Stage 0: What is `mermaid` exactly?

Stage 1: Which facets can output a visualization of this `iolanta:OutputDatatype`?

Stage 2: Resolve Facet

Stage 3: Retrieving Graph Data

Other examples

An ORCID profile

RDFS label

OWL vocabulary terms

Conclusion

Introducing Iolanta ontologyAssignment for MC-1 Fall 2025 © Anatoly Scherbakov

Problem & Use Cases

Serialization: YAML-LD

Facet class

OutputDatatype class

SPARQLText class

matches datatype property

outputs object property

Identifier Strategy

Facet identifiers with Package URL (purl)

Graph Representation Choice

Querying the Knowledge Graph & Visualizing it

Stage 0: What is mermaid exactly?

Stage 1: Which facets can output a visualization of this iolanta:OutputDatatype?

Stage 2: Resolve Facet

Stage 3: Retrieving Graph Data

Other examples

An ORCID profile

RDFS label

OWL vocabulary terms

Conclusion

Introducing Iolanta ontology
Assignment for MC-1 Fall 2025 © Anatoly Scherbakov

`Facet` class

`OutputDatatype` class

`SPARQLText` class

`matches` datatype property

`outputs` object property

Stage 0: What is `mermaid` exactly?

Stage 1: Which facets can output a visualization of this `iolanta:OutputDatatype`?