How the Semantica Explorer Module Enables Visual Ontology Editing and SHACL Studio

The Semantica Explorer module combines a React frontend with a Python FastAPI backend to deliver browser-based visual ontology editing, SKOS vocabulary management, and an integrated SHACL Studio for real-time constraint authoring and validation.

The semantica-agi/semantica repository ships with the Explorer module as a comprehensive workbench for knowledge graph manipulation. By integrating visual ontology editing and SHACL studio capabilities directly into the platform, users can author semantic constraints, validate RDF shapes against live data, and manage SKOS vocabularies through an interactive Sigma.js canvas without leaving their browser.

Architecture Overview

The Explorer module follows a full-stack architecture that separates presentation logic from graph computation while maintaining real-time synchronization between layers.

React Frontend Workspace

The user interface resides in explorer/src/workspaces/OntologyWorkspace/index.tsx, which orchestrates the primary editing environment. This workspace encapsulates two specialized sub-components: ShaclStudio.tsx implements the constraint editor using the Monaco code editor with SHACL syntax highlighting, while SKOSVocabularyManager.tsx provides drag-and-drop functionality for vocabulary management.

State management flows through explorer/src/workspaces/GraphWorkspace/store/graphStore.ts, which maintains the in-memory RDF graph using reactive hooks powered by @tanstack/react-query. The store tracks graph mutations and synchronizes them with the Sigma.js canvas visualization layer.

Python FastAPI Backend

The backend service launches via semantica/explorer/app.py, exposing REST endpoints under /api/ontology/* for graph persistence and validation. The module semantica/explorer/ws.py establishes the WebSocket endpoint /ws/graph-updates, enabling bidirectional streaming of graph changes between server and connected clients.

SHACL Studio Implementation

The SHACL Studio integrates tightly with the validation pipeline provided by pyshacl. When users author constraints in the Monaco editor within ShaclStudio.tsx, the frontend POSTs SHACL Turtle content to /api/ontology/shacl. The Python backend processes this through pyshacl and returns validation reports that the frontend renders directly on the Sigma.js canvas, highlighting non-conforming nodes and properties.

This round-trip validation occurs without page refresh, leveraging the WebSocket connection to broadcast validation states to all connected workspace instances.

Real-Time Visual Ontology Editing

The visual editing capabilities extend beyond SHACL authoring to full ontology manipulation through the SKOSVocabularyManager.tsx component. Users browse concept schemes, create new SKOS concepts, and edit existing definitions through a drag-and-drop interface that translates interactions into SPARQL updates.

Changes propagate through the system via the following flow:

1. Mutation Capture: Frontend components dispatch graph updates to graphStore.ts.
2. API Persistence: The store pushes changes to /api/ontology/vocabulary with the SEMANTICA_API_KEY header.
3. Broadcast: The server emits the mutation via /ws/graph-updates to all connected clients.
4. Canvas Update: Subscribers receive the WebSocket message and re-render the Sigma.js visualization.

Launching and Configuring the Explorer

To start the visual editing environment, run the CLI command:

semantica-explorer --graph path/to/my_graph.json

This command launches the FastAPI server at http://127.0.0.1:8000. In development mode, the Vite development server proxies /api/* requests to the Python backend, creating a transparent development experience where frontend code communicates directly with the graph services.

Security enforcement relies on the SEMANTICA_API_KEY environment variable. The Explorer UI automatically injects this key into HTTP headers for REST calls and appends it as a query parameter for WebSocket connections, protecting mutation routes from unauthorized access.

Code Examples

Validating SHACL Shapes via Python Client

import requests
import os

API_KEY = os.getenv("SEMANTICA_API_KEY")
headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "text/turtle"
}

with open("shapes.ttl", "r") as f:
    shacl_data = f.read()

response = requests.post(
    "http://127.0.0.1:8000/api/ontology/shacl",
    data=shacl_data,
    headers=headers
)

print(response.json())  # Validation report with conforms boolean and details

Consuming Real-Time Graph Updates

import websockets
import asyncio
import os
import json

API_KEY = os.getenv("SEMANTICA_API_KEY")
uri = f"ws://127.0.0.1:8000/ws/graph-updates?api_key={API_KEY}"

async def monitor_changes():
    async with websockets.connect(uri) as websocket:
        async for message in websocket:
            update = json.loads(message)
            print(f"Graph mutation detected: {update}")

asyncio.run(monitor_changes())

Adding SKOS Concepts from React

import { useMutation, useQueryClient } from '@tanstack/react-query';
import axios from 'axios';

const addConcept = async (label: string) => {
  const response = await axios.post(
    '/api/ontology/vocabulary',
    { label },
    {
      headers: {
        'X-API-Key': process.env.SEMANTICA_API_KEY
      }
    }
  );
  return response.data;
};

export function ConceptCreator() {
  const queryClient = useQueryClient();
  
  const mutation = useMutation({
    mutationFn: addConcept,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['vocabulary'] });
    }
  });

  return (
    <button onClick={() => mutation.mutate('New SKOS Concept')}>
      Add Concept
    </button>
  );
}

Summary

• The Explorer module combines a React frontend (explorer/src/workspaces/OntologyWorkspace/) with a FastAPI Python backend (semantica/explorer/app.py) to deliver visual ontology editing and SHACL studio functionality.
• SHACL Studio provides Monaco-based constraint authoring with real-time validation via pyshacl and the /api/ontology/shacl endpoint.
• Visual editing relies on SKOSVocabularyManager.tsx for drag-and-drop vocabulary management and Sigma.js for graph rendering.
• Real-time collaboration is enabled through WebSocket connections at /ws/graph-updates, broadcasting graph mutations to all connected clients.
• Security is enforced via SEMANTICA_API_KEY validation on all mutation endpoints and WebSocket connections.
• The module launches via semantica-explorer --graph <file> and serves the UI at http://127.0.0.1:8000.

Frequently Asked Questions

How does the Explorer module validate SHACL constraints in real time?

The SHACL Studio component posts Turtle-encoded shapes to the /api/ontology/shacl endpoint implemented in semantica/explorer/app.py. The backend executes pyshacl validation against the current in-memory graph and returns conformance results. The frontend visualizes these results by highlighting affected nodes on the Sigma.js canvas, with updates broadcast via WebSocket to maintain synchronization across all clients.

What file paths contain the core visual editing components?

The primary UI components reside in explorer/src/workspaces/OntologyWorkspace/ShaclStudio.tsx for constraint editing and explorer/src/workspaces/OntologyWorkspace/SKOSVocabularyManager.tsx for vocabulary management. Shared graph state is managed through explorer/src/workspaces/GraphWorkspace/store/graphStore.ts, which interfaces with the backend API and WebSocket handlers defined in semantica/explorer/ws.py.

Can multiple users edit ontologies simultaneously through the Explorer?

Yes. The WebSocket endpoint /ws/graph-updates streams graph mutations to all connected clients in real time. When one user adds a node or modifies a SHACL shape via the REST API, the server broadcasts the change event to all subscribed browsers, ensuring the Sigma.js canvas remains synchronized across sessions without requiring page refreshes.

How do I secure the Explorer API when deploying in production?

The Explorer requires the SEMANTICA_API_KEY environment variable for all mutation operations. The frontend automatically includes this key in the X-API-Key header for HTTP requests and as a query parameter for WebSocket connections. Ensure this key is set in your deployment environment and that the Explorer is not exposed publicly without additional network-level protections such as VPNs or reverse proxy authentication.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}