Tutorial

Getting Started Premiers pas

Create your first Knowledge Space using the topo CLI. By the end, you will have a working ontology with classes, properties, SPARQL queries, and SHACL validation — all from the command line. Créez votre premier Knowledge Space avec la CLI topo. À la fin, vous aurez une ontologie fonctionnelle avec classes, propriétés, requêtes SPARQL et validation SHACL — le tout depuis la ligne de commande.

~15 min ~15 min

Prerequisites Prérequis

Node.js 20+ and pnpm installedNode.js 20+ et pnpm installés
rudof installed for SHACL validation (cargo install rudof_cli)rudof installé pour la validation SHACL (cargo install rudof_cli)
bra0 cloned: git clone https://github.com/sachaR063R/bra0.git && cd bra0 && pnpm installbra0 cloné : git clone https://github.com/sachaR063R/bra0.git && cd bra0 && pnpm install

Step 1 Create a project directory Créer un répertoire projet

A Knowledge Space starts as a directory containing Turtle files. Create a new directory for your first ontology. Un Knowledge Space commence par un répertoire contenant des fichiers Turtle. Créez un nouveau répertoire pour votre première ontologie.

mkdir my-first-ks
cd my-first-ks
      

Step 2 Write your first ontology Écrire votre première ontologie

Create a hello.ttl file with two classes and a property. This is pure W3C Turtle — no bra0-specific format. Créez un fichier hello.ttl avec deux classes et une propriété. C'est du W3C Turtle pur — aucun format spécifique à bra0.

# hello.ttl — my first Knowledge Space
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix ex:   <http://example.org/hello#> .

ex:Person a owl:Class ;
  rdfs:label "Person" ;
  rdfs:comment "A human being." .

ex:Organization a owl:Class ;
  rdfs:label "Organization" ;
  rdfs:comment "A structured group of people." .

ex:worksFor a owl:ObjectProperty ;
  rdfs:label "works for" ;
  rdfs:domain ex:Person ;
  rdfs:range ex:Organization .
      

Step 3 Import into topo Importer dans topo

Use topo import to load the Turtle file into the local Oxigraph store. This parses, validates syntax, and hydrates the RDF graph. Utilisez topo import pour charger le fichier Turtle dans le store Oxigraph local. Cela parse, valide la syntaxe et hydrate le graphe RDF.

npx topo import .
# Loaded hello.ttl — 7 triples
      

Step 4 Query with SPARQL Requêter en SPARQL

Run SPARQL queries directly against the local Oxigraph store. No server needed — everything runs locally. Exécutez des requêtes SPARQL directement sur le store Oxigraph local. Pas de serveur nécessaire — tout tourne localement.

# List all classes
npx topo query . -q "SELECT ?class ?label WHERE { ?class a owl:Class ; rdfs:label ?label }"

# Result:
# ┌────────────────────────────┬──────────────────┐
# │ class                      │ label            │
# ├────────────────────────────┼──────────────────┤
# │ ex:Person                  │ "Person"         │
# │ ex:Organization             │ "Organization"   │
# └────────────────────────────┴──────────────────┘
      

Step 5 Add instances Ajouter des instances

Create a data.ttl file with concrete data — individuals that populate your ontology. Créez un fichier data.ttl avec des données concrètes — des individus qui peuplent votre ontologie.

# data.ttl
@prefix ex: <http://example.org/hello#> .

ex:alice a ex:Person ;
  rdfs:label "Alice" ;
  ex:worksFor ex:acme .

ex:acme a ex:Organization ;
  rdfs:label "Acme Corp" .
      

npx topo import .
# Loaded data.ttl — 5 triples (12 total)
      

Step 6 Validate with SHACL Valider avec SHACL

Write a SHACL shape to enforce that every Person has a label. Then validate using rudof (Rust, SHACL 1.2 complete). Écrivez une shape SHACL pour imposer que chaque Person ait un label. Puis validez avec rudof (Rust, SHACL 1.2 complet).

# hello.shapes.ttl
@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix ex:   <http://example.org/hello#> .

ex:PersonShape a sh:NodeShape ;
  sh:targetClass ex:Person ;
  sh:property [
    sh:path rdfs:label ;
    sh:minCount 1 ;
    sh:datatype xsd:string ;
    sh:message "Every Person must have a label."
  ] .
      

rudof shacl-validate -s hello.shapes.ttl hello.ttl data.ttl
# Result: CONFORMS
      

Step 7 Detect gaps Détecter les lacunes

Run gap detection to find missing labels, orphan classes, or incomplete definitions — 10 built-in SPARQL queries based on the Gaur taxonomy. Lancez la détection de lacunes pour trouver les labels manquants, les classes orphelines ou les définitions incomplètes — 10 requêtes SPARQL intégrées basées sur la taxonomie Gaur.

npx topo gaps .
# Analyzing 12 triples...
# [PASS] All classes have labels
# [WARN] ex:worksFor missing rdfs:comment
# 1 gap found
      

What you built Ce que vous avez construit

A Knowledge Space with 2 classes, 1 property, 2 instances, 1 SHACL shape, validated locally via rudof, queryable via SPARQL, and gap-analyzed — all in W3C standard formats. No server, no account, no cloud dependency. Un Knowledge Space avec 2 classes, 1 propriété, 2 instances, 1 shape SHACL, validé localement via rudof, requêtable via SPARQL, et analysé pour les lacunes — le tout en formats standards W3C. Pas de serveur, pas de compte, pas de dépendance cloud.

Next steps Étapes suivantes

Where to go from here Où aller ensuite

Understand Knowledge Spaces — learn about the 11 entity types and 8 facets.
Guide: IT Systems Diagnostic — apply topo to a real-world use case.
CLI Reference (topo) — the full command reference.
SHACL Shapes Catalog — explore the 58 production shapes.
Ontology Catalog — see the ontologies available for reuse. Comprendre les Knowledge Spaces — découvrez les 11 types d'entités et les 8 facettes.
Guide : Diagnostic SI — appliquez topo à un cas d'usage réel.
Référence CLI (topo) — la référence complète des commandes.
Catalogue SHACL Shapes — explorez les 58 shapes de production.
Catalogue d'ontologies — les ontologies disponibles pour la réutilisation.