Use LinkML for the ontologies (#36)

* fix

* fix

Author: Ostrzyciel

.github/workflows/ci.yaml

@@ -22,14 +22,27 @@ jobs:
 
       - uses: Jelly-RDF/setup-cli@v1
 
+      # We can't use the linkml-scala action because it doesn't support Turtle output...
+      # which breaks our pretty prefixes.
+      - name: Install linkml-scala
+        run: |
+          . <(curl -sSfL https://raw.githubusercontent.com/NeverBlink-OSS/linkml-scala/refs/heads/main/cli/install.sh)
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
       - name: Install dependencies
         run: pip install -r requirements.txt
 
+      - name: 'Validate ontologies'
+        run: |
+          for f in ontology/*.yaml; do
+            linkml-scala validate "$f"
+          done
+
       - name: 'Convert ontologies, prepare for publishing'
         run: |
           bin/build_ontology.sh
-          rm docs/ontology/files/*.ttl
-          cp publish/*.ttl docs/ontology/files/
+          rm docs/ontology/files/turtle/*.ttl
+          cp publish/*.ttl docs/ontology/files/turtle/
           ls -la publish/*
 
       - name: Compile docs

.github/workflows/publish-dev.yaml

@@ -24,14 +24,19 @@ jobs:
 
       - uses: Jelly-RDF/setup-cli@v1
 
+      - name: Install linkml-scala
+        run: |
+          . <(curl -sSfL https://raw.githubusercontent.com/NeverBlink-OSS/linkml-scala/refs/heads/main/cli/install.sh)
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
       - name: Install dependencies
         run: pip install -r requirements.txt
 
       - name: 'Convert ontologies, prepare for publishing'
         run: |
           bin/build_ontology.sh
-          rm docs/ontology/files/*.ttl
-          cp publish/*.ttl docs/ontology/files/
+          rm docs/ontology/files/turtle/*.ttl
+          cp publish/*.ttl docs/ontology/files/turtle/
 
       - name: Deploy site
         run: |

.gitignore

@@ -209,3 +209,6 @@ __marimo__/
 # RDF-tensor
 *.code-workspace
 .idea/
+
+# Generated ontology artifacts
+/publish/

CITATION.cff

@@ -10,7 +10,7 @@ authors:
     email: contact@neverblink.eu
   - name: Piotr Marciniak
   - name: Piotr Sowiński
-    website: 'https://ostrzyciel.eu'
+    website: 'https://github.com/Ostrzyciel'
   - name: RDF-tensor contributors
     website: >-
       https://github.com/NeverBlink-OSS/rdf-tensor/graphs/contributors

README.md

@@ -22,19 +22,37 @@ This is an extension to RDF and SPARQL that introduces 2 new datatypes, dozens o
 
 **[See the website](https://w3id.org/rdf-tensor) for more details.**
 
+## Editing the ontology
+
+The vocabulary (datatypes, functions, aggregates) is authored in [LinkML](https://linkml.io/) YAML files in the `ontology/` directory. The published RDF artifacts (RDFS in Turtle, N-Triples, JSON-LD, RDF/XML, and [Jelly](https://w3id.org/jelly)) are generated from these sources.
+
+To regenerate the published files locally you need two tools in your `PATH`:
+
+- [`linkml-scala`](https://github.com/NeverBlink-OSS/linkml-scala) – generates RDFS from the LinkML sources.
+- [`jelly-cli`](https://github.com/Jelly-RDF/cli) – converts between RDF serializations.
+
+Then run, from the root of the repository:
+
+```bash
+bin/build_ontology.sh
+```
+
+The generated files are written to the `publish/` directory. CI runs the same script.
+
 ## Editing the documentation
 
 1. Clone the repository: `git clone git@github.com:NeverBlink-OSS/rdf-tensor.git`
 2. Create a new Python virtual environment using your favorite tool (e.g., [`venv`](https://docs.python.org/3/library/venv.html)).
 3. Install the dependencies: `pip install -r requirements.txt`
-4. Compile the docs and host them locally for testing: `mkdocs serve`
-5. Whenever you make changes to the documentation pages (they reside in the `docs` directory), the docs will be automatically recompiled.
+4. Generate the ontology files so the docs can embed them: `bin/build_ontology.sh` (see above).
+5. Compile the docs and host them locally for testing: `mkdocs serve`
+6. Whenever you make changes to the documentation pages (they reside in the `docs` directory), the docs will be automatically recompiled.
 
 ## Authors, licensing
 
-The original SPARQL extension and implementation for Jena were done by **[Piotr Marciniak](https://github.com/cinekele)** – see the [original repository](https://github.com/RDF-tensor/jena-datatensor).
+This repository is maintained and developed by **[NeverBlink](https://neverblink.eu)**.
 
-The work is continued in this repository under the stewardship of [NeverBlink](https://neverblink.eu). The current maintainers are **[Piotr Sowiński (Ostrzyciel)](https://github.com/Ostrzyciel)** and **[Nik Kozlov](https://github.com/nk2ishere)**.
+The original SPARQL extension and implementation for Jena were done by **[Piotr Marciniak](https://github.com/cinekele)** – see the [original repository](https://github.com/RDF-tensor/jena-datatensor).
 
 This repository is licensed under [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
 

bin/build_ontology.sh

@@ -1,9 +1,13 @@
 #!/bin/bash
+set -euo pipefail
 
-# This script prepares the ontology files for publishing.
-# You need jelly-cli in your PATH for this script to work.
-# See: https://github.com/Jelly-RDF/cli
-
+# This script generates the ontology files from the LinkML sources in ontology/
+# and prepares them for publishing.
+#
+# You need the following tools in your PATH for this script to work:
+#   - linkml-scala   (RDFS generation)  https://github.com/NeverBlink-OSS/linkml-scala
+#   - jelly-cli      (format conversion) https://github.com/Jelly-RDF/cli
+#
 # Run this script from the root of the repository.
 
 formats=(
@@ -14,10 +18,15 @@ formats=(
 )
 
 mkdir -p publish
-for file in ontology/*.ttl; do
-    base_name=$(basename "$file" .ttl)
-    jelly-cli rdf to-jelly --enable-namespace-declarations "$file" > publish/"$base_name".jelly
-    # For each format, convert the jelly file to the desired format
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+
+for file in ontology/*.yaml; do
+    base_name=$(basename "$file" .yaml)
+    # Generate RDFS (Turtle, so namespace prefixes are preserved) into an intermediate file.
+    linkml-scala generate rdfs --format ttl --to "$tmpdir/$base_name.ttl" "$file"
+    # Round-trip through Jelly to produce all published serializations consistently.
+    jelly-cli rdf to-jelly --enable-namespace-declarations "$tmpdir/$base_name.ttl" > publish/"$base_name".jelly
     for format in "${formats[@]}"; do
         jelly-cli rdf from-jelly publish/"$base_name".jelly --to publish/"$base_name"."$format"
     done

docs/ontology/aggregates.md

@@ -11,8 +11,18 @@
 | **JSON-LD** | [`https://w3id.org/rdf-tensor/aggregates.jsonld`](https://w3id.org/rdf-tensor/aggregates.jsonld) |
 | **RDF/XML** | [`https://w3id.org/rdf-tensor/aggregates.rdf`](https://w3id.org/rdf-tensor/aggregates.rdf) |
 
-## Ontology source
+## Ontology source (LinkML)
+
+[Source file](https://github.com/NeverBlink-OSS/rdf-tensor/blob/main/ontology/aggregates.yaml).
+
+This LinkML source is converted to RDFS using [LinkML-Scala](https://github.com/NeverBlink-OSS/linkml-scala).
+
+```yaml
+{% include "./files/linkml/aggregates.yaml" %}
+```
+
+## Ontology source (Turtle)
 
 ```ttl
-{% include "./files/aggregates.ttl" %}
+{% include "./files/turtle/aggregates.ttl" %}
 ```

docs/ontology/datatypes.md

@@ -11,8 +11,18 @@
 | **JSON-LD** | [`https://w3id.org/rdf-tensor/datatypes.jsonld`](https://w3id.org/rdf-tensor/datatypes.jsonld) |
 | **RDF/XML** | [`https://w3id.org/rdf-tensor/datatypes.rdf`](https://w3id.org/rdf-tensor/datatypes.rdf) |
 
-## Ontology source
+## Ontology source (LinkML)
+
+[Source file](https://github.com/NeverBlink-OSS/rdf-tensor/blob/main/ontology/datatypes.yaml).
+
+This LinkML source is converted to RDFS using [LinkML-Scala](https://github.com/NeverBlink-OSS/linkml-scala).
+
+```yaml
+{% include "./files/linkml/datatypes.yaml" %}
+```
+
+## Ontology source (Turtle)
 
 ```ttl
-{% include "./files/datatypes.ttl" %}
+{% include "./files/turtle/datatypes.ttl" %}
 ```