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

> Discover visual ontology editing and SHACL Studio with the Semantica Explorer module. Its React frontend and Python backend offer intuitive vocabulary management and real-time constraint validation.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/OntologyWorkspace/index.tsx), which orchestrates the primary editing environment. This workspace encapsulates two specialized sub-components: [`ShaclStudio.tsx`](https://github.com/semantica-agi/semantica/blob/main/ShaclStudio.tsx) implements the constraint editor using the Monaco code editor with SHACL syntax highlighting, while [`SKOSVocabularyManager.tsx`](https://github.com/semantica-agi/semantica/blob/main/SKOSVocabularyManager.tsx) provides drag-and-drop functionality for vocabulary management.

State management flows through [`explorer/src/workspaces/GraphWorkspace/store/graphStore.ts`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/app.py), exposing REST endpoints under `/api/ontology/*` for graph persistence and validation. The module [`semantica/explorer/ws.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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:

```bash
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

```python
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

```python
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

```typescript
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/OntologyWorkspace/ShaclStudio.tsx) for constraint editing and [`explorer/src/workspaces/OntologyWorkspace/SKOSVocabularyManager.tsx`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/OntologyWorkspace/SKOSVocabularyManager.tsx) for vocabulary management. Shared graph state is managed through [`explorer/src/workspaces/GraphWorkspace/store/graphStore.ts`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/store/graphStore.ts), which interfaces with the backend API and WebSocket handlers defined in [`semantica/explorer/ws.py`](https://github.com/semantica-agi/semantica/blob/main/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.