Ontosphere — Browser-based RDF Knowledge Graph Editor

Table of Contents

• Overview
• Key capabilities
• Quick start (development)
• Startup / URL parameters
• Reasoning
• Reasoning demo
• CORS and proxies
• Using the UI
• Developer utilities
• Troubleshooting
• AI / MCP Integration
  • How it works
  • Setup (Playwright / headless)
  • Recommended workflow
  • Using Ontosphere with any AI
    • Claude Code / Playwright
    • AI Relay Bridge (ChatGPT, Gemini, Claude.ai)
• Recording demo videos
• Contributing
• License & authors

Overview

Ontosphere is a browser-based RDF/ontology knowledge graph editor. It loads RDF from local files, remote URLs, or SPARQL/Fuseki endpoints; lets users author nodes and edges directly on the canvas; runs OWL 2 DL reasoning (via Konclude) with visual differentiation of inferred triples; and applies multi-algorithm layout (Dagre, ELK) and automatic clustering for large graphs. Additional features include namespace management with live URI renaming, a drag-and-drop workflow template catalog, and a Model Context Protocol (MCP) server for AI-agent integration. All computation runs entirely client-side in the browser against an in-memory RDF store backed by Web Workers — no backend required.

Key capabilities

• Load RDF/Turtle/JSON-LD/RDF-XML/N-Triples from local files or remote URLs (including SPARQL endpoints and Fuseki datasets).
• Startup URL support: auto-load an RDF file via URL query parameter (see "Startup / URL usage" below).
• Reactodia canvas: pan, zoom, minimap, fit-view, with entity group (cluster) support and smooth animations.
• Authoring mode (always on): add nodes via search, draw edges by dragging the halo "Establish Link" handle, edit node annotation properties and link predicates directly on the canvas. Undo/Redo support. Entity auto-complete uses scored domain/range tiers derived from loaded ontologies.
• Search: type in the search box to find entities by label or IRI; press Enter to cycle through matches on the canvas.
• TBox / ABox views: toggle between ontology-level classes/properties (TBox) and data-level individuals (ABox).
• Layout engine: multiple algorithms — Dagre (horizontal/vertical), ELK (layered, force, stress, radial), and Reactodia-default — all running in Web Workers so the UI stays responsive. Spacing is adjustable via a slider; re-layout triggers automatically when spacing changes.
• Hierarchical fold levels: graphs load with two levels of structural folding already applied — L2 (subclass chains and OWL collection axioms collapsed into representative group nodes) and L1 (per-node annotation properties hidden). A level badge in the toolbar shows the current depth (L3/L2/∅). Fold/Unfold buttons for each level let users progressively reveal detail. L3 (community-detection clustering — Label Propagation, Louvain, K-Means) applies automatically on load above a configurable node threshold (default 100). Each view (TBox / ABox) tracks its fold state independently.
• DL reasoning (Konclude): run OWL 2 DL inference in the browser and see inferred triples rendered as amber dashed edges; inferred types/annotations appear in amber italic. A reasoning report lists all inferred triples. Includes automatic OWL DL consistency checking — the Errors tab shows per-entity clash details when the ontology is contradictory. Clear inferred triples any time without affecting asserted data.
• Namespace management: edit namespace URIs directly in the legend panel (rename propagates across all stored triples). Colour-coded namespace badges on nodes and edges.
• Export the current graph as Turtle, RDF/XML, or JSON-LD.
• Workflow catalog: drag reusable workflow template cards from the sidebar onto the canvas to instantiate connected subgraphs.
• MCP support: exposes a Model Context Protocol server (via the browser's navigator.modelContext API) for AI-agent integration. Tools: loadRdf, loadOntology, suggestOntologiesForTask, queryGraph, exportGraph, exportImage, addNode, removeNode, expandNode, getNodes, addLink, removeLink, getLinks, runLayout, clusterNodes, layoutNodes, focusNode, fitCanvas, runReasoning, clearInferred, getNeighbors, findPath, getNodeDetails, updateNode, getGraphState, setNamespace, removeNamespace, listNamespaces, loadShacl, validateGraph, getCapabilities, help. MCP manifest at /.well-known/mcp.json.

Quick start (development)

1. Install dependencies:
   hljs language-sh

   Copy

   npm install
   

2. Start the Vite dev server:
   hljs language-sh

   Copy

   npm run dev
   

3. Open in your browser:
   hljs language-text

   Copy

   http://localhost:8080/
   

Startup / URL parameters

Ontosphere supports several URL query parameters that control what is loaded on startup.

RDF data URL

Supported sources:

1. Plain RDF files — Turtle (.ttl), N-Triples (.nt), N3, RDF/XML, JSON-LD. Format is detected from Content-Type and file extension.

   hljs language-ini

   Copy

   ?rdfUrl=https://example.org/mydata.ttl
   

2. SPARQL endpoints — URLs whose path ends with /sparql or /query are recognised automatically. Ontosphere issues a CONSTRUCT { ?s ?p ?o } WHERE { { ?s ?p ?o } UNION { GRAPH ?g { ?s ?p ?o } } } query.

   hljs language-ruby

   Copy

   ?rdfUrl=https://example.org/fuseki/$/sparql
   

3. Fuseki dataset root — Returns the full dataset; named-graph quads are flattened into the data graph.

   hljs language-ruby

   Copy

   ?rdfUrl=https://docker-dev.iwm.fraunhofer.de/dataset/<uuid>/fuseki/$/
   

Authentication (API key)

?rdfUrl=https://private-endpoint.example.org/data.ttl
&apiKey=Bearer+my-token
&apiKeyHeader=Authorization

The API key is sent only with the RDF fetch request. CORS: the server must allow the Ontosphere origin with credentials (wildcard * origins are incompatible with authenticated requests).

Ontology pre-loading

?ontologies=owl,rdf,rdfs           # replace defaults — load only W3C core vocabs
?ontology=bfo,dcat                 # add on top of configured autoload list
?ontology=bfo2020,https://example.org/myontology.ttl

Well-known short names:

Import discovery

?rdfUrl=https://example.org/data.ttl&loadImports=false

Full example (CKAN private dataset via Fuseki SPARQL)

http://docker-dev.iwm.fraunhofer.de:8080/
  ?rdfUrl=https://docker-dev.iwm.fraunhofer.de/dataset/<uuid>/fuseki/$/sparql
  &apiKey=<ckan-api-jwt-token>

Startup loading order

All startup mechanisms are additive and run in this order:

1. Configured additional ontologies (app settings → persistedAutoload)
2. RDF data graph (rdfUrl / url / vg_url)
3. Ontologies from ?ontology= URL parameter
4. owl:imports discovery (runs after each load unless ?loadImports=false)

Other startup mechanisms

• window.__VG_STARTUP_TTL — inline Turtle string loaded before any URL parameter.
• window.__VG_STARTUP_URL — programmatic URL override (takes precedence over rdfUrl).
• VITE_STARTUP_URL environment variable — build-time default startup URL.

Reasoning

Ontosphere runs OWL reasoning entirely in the browser via a pluggable backend. The default is Konclude (full OWL 2 DL). Inferred triples appear as amber dashed edges; inferred types and annotations appear in amber italic. A reasoning report lists all inferred triples. Reasoning is idempotent — running it again produces no additional triples. Use Clear inferred to remove all inferred triples without affecting asserted data. See OWL 2 DL vs OWL-RL comparison for a side-by-side visual example.

OWL DL consistency checking runs automatically alongside inference (Konclude only). If the ontology is logically contradictory, reasoning is skipped and the report's Errors tab shows per-entity clash details (affected individual, violated axiom, description). An "OWL DL inconsistency detected" banner appears in the report. Common inconsistencies: an individual in two owl:disjointWith classes, an owl:allValuesFrom restriction violated by an asserted type, or an owl:AsymmetricProperty / owl:IrreflexiveProperty cycle. The N3 backend does not perform consistency checking (isConsistent is always null).

Konclude (default — OWL 2 DL)

Konclude is a complete tableau reasoner for the description logic SROIQ(D) (OWL 2 DL), compiled to WebAssembly. It runs classification over the loaded ontology and writes rdfs:subClassOf and owl:equivalentClass inferences.

Supported OWL constructs (complete): rdfs:subClassOf, owl:equivalentClass, owl:someValuesFrom, owl:allValuesFrom, owl:hasValue, owl:inverseOf, owl:SymmetricProperty, owl:TransitiveProperty, owl:subPropertyOf, rdfs:domain/rdfs:range, owl:intersectionOf, owl:unionOf, owl:oneOf, owl:propertyChainAxiom, number restrictions, nominals, and more.

Deployment requirement: Konclude's WASM binary uses SharedArrayBuffer (pthreads). The server must send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: credentialless headers. Localhost deployments have SharedArrayBuffer available without headers. Ontosphere's server.js sets these headers automatically.

Performance: 250 ms – 2.5 s for typical benchmark ontologies (LUBM, GALEN, Pizza).

N3 Rules (legacy / advanced)

The N3 backend uses the N3.js BGP-only Reasoner with configurable rulesets loaded from public/reasoning-rules/. Select it in Settings → Reasoner Backend → N3 Rules.

N3.js is BGP-only: rules using EYE/SWAP built-ins (e:findall, list:in, log:notEqualTo) are silently ignored. The [REQUIRES EYE] comments in the rule files mark those rules. Use this backend when you need custom N3 rule files or are working with demos that depend on specific rule-file behavior.

Performance: Under 2 seconds for typical ontologies (hundreds to a few thousand triples). There is currently no way to abort a running reasoning job; a page reload is required if reasoning hangs.

Reasoning demo

The reasoning demo showcases OWL 2 DL / SROIQ(D) inference on a small employee ontology: Open demo ↗

The demo (public/reasoning-demo.ttl) defines a Person → Employee → Manager → Executive hierarchy with ABox assertions that drive inference patterns across all OWL 2 DL construct groups:

OWL 1 RL patterns:

1. rdfs:subPropertyOf — ex:hasFriend sub-property of ex:knows: alice hasFriend bob → alice knows bob.
2. owl:inverseOf — ex:isManagedBy inverse of ex:manages: alice manages carol → carol isManagedBy alice.
3. owl:SymmetricProperty — ex:isColleagueOf is symmetric: bob isColleagueOf carol → reverse direction.
4. owl:TransitiveProperty — ex:hasSupervisor is transitive: bob→alice, alice→dave → bob→dave.
5. rdfs:domain — ex:dave has no type; because he is subject of ex:manages (domain ex:Manager), the reasoner infers dave rdf:type ex:Manager.

OWL 2 DL extensions: 6. owl:someValuesFrom — alice and carol each worksOn projectAlpha (a Project) → inferred ProjectContributor. 7. owl:hasValue — carol isManagedBy alice (via inverseOf) → carol inferred DirectReport (hasValue restriction on alice). 8. owl:intersectionOf — dave manages bob (inferred Manager) and eve (Employee) → dave inferred TeamLead. 9. owl:disjointWith — Contractor disjointWith Employee; frank is a Contractor (structural TBox constraint). 10. owl:complementOf — NonEmployee ≡ ¬Employee (structural TBox only). 11. owl:propertyChainAxiom — hasGrandManager ← hasSupervisor ∘ hasSupervisor: carol→bob→alice → carol hasGrandManager alice. 12. owl:unionOf — LeadershipTeam ≡ Executive ∪ Manager: alice (Executive) and dave (inferred Manager) → inferred LeadershipTeam. 13. owl:sameAs — aliceCEO sameAs alice: aliceCEO inherits all of alice's inferred types including Executive.

A separate inconsistency demo (public/reasoning-demo-inconsistent.ttl) shows the consistency checker in action: Open inconsistency demo ↗

inc:frank is asserted as both inc:Employee and inc:Contractor, which are declared owl:disjointWith. Running reasoning produces isConsistent: false, reasoning is skipped, and the report's Errors tab shows the disjointness clash on frank.

CORS and proxies

Ontosphere fetches remote RDF directly from the browser. If the remote host does not allow cross-origin requests, the fetch will be blocked.

Well-known ontologies (FOAF, SKOS, PROV-O, Dublin Core, QUDT, etc.) are pre-configured with CORS-friendly fetch URLs (W3C, dublincore.org, LOV, qudt.org) and load without any proxy.

Custom ontology URLs that lack CORS headers require a proxy. Configure one in Settings → Advanced → CORS Proxy URL. The proxy must:

• Accept a URL-encoded target as a query parameter: https://your-proxy/?url=<encoded>
• Forward the Accept header to the target server
• Not restrict RDF MIME types (text/turtle, application/rdf+xml, etc.)

Note: corsproxy.io free tier blocks RDF content types and will not work. Self-hosted options that do work: a Cloudflare Worker using the cors-anywhere pattern, or a local Vite dev-server proxy.

Workarounds for development:

• Use CORS-enabled hosting for the RDF file.
• Configure a local dev proxy in your Vite config to forward the request.

Using the UI

Developer utilities (window globals)

The following debug flags can be set in the browser console to enable diagnostic output. All are gated — they only activate when window.__VG_DEBUG__ is truthy (or config.debugAll is enabled in Settings):

• window.__VG_DEBUG__ — master debug gate. Set to true to enable all [VG_*] diagnostic console output.
• window.__VG_LOG_RDF_WRITES — log RDF triple writes to the console.
• window.__VG_DEBUG_STACKS__ — capture stack traces in debug messages.
• window.__VG_DEBUG_SUMMARY__ — read-only object populated by the startup debug harness with fallback and timing data.

All flags are also persisted from config.debugAll (toggleable in Settings → Debug). Setting config.debugAll = true via Settings is the recommended way to enable diagnostics without console access.

Troubleshooting

• rdfUrl doesn't load on open:
  • Confirm the URL is percent-encoded in the address bar.
  • Open DevTools → Network and check the fetch request and response headers.
  • Look for CORS errors (Access-Control-Allow-Origin).
  • Check the console for RDF parser errors or application diagnostics.
• 403 when using certain query parameter names:
  • Some servers intercept reserved query names. Use ?rdfUrl=... to avoid conflicts.
• Graph is very large / slow:
  • Increase the large-graph threshold in Settings or reduce the number of loaded triples.
  • Clustering activates automatically above the threshold; use Expand All sparingly on huge graphs.

AI / MCP Integration

Ontosphere exposes a full Model Context Protocol tool surface so AI agents can build and reason over knowledge graphs through natural-language chat.

How it works

The app has two coupled layers:

• N3 RDF store — source of truth. addNode / addLink write triples here.
• Reactodia canvas — visual mirror. Nodes are not created automatically from triples; you must call addNode to place a subject on canvas. After adding triples, canvas links refresh automatically. Nodes start collapsed — call expandNode (with an IRI to expand one node, or no args to expand all) to reveal annotation property cards.

DL reasoning (Konclude) writes inferred triples back to the store and refreshes the canvas.

Setup (Playwright / headless)

navigator.modelContext does not exist in headless Chromium. Inject the polyfill before the page loads using page.addInitScript:

await page.addInitScript(() => {
  const tools = {};
  Object.defineProperty(navigator, 'modelContext', {
    value: { registerTool: async (n, _d, _s, h) => { tools[n] = h; } },
    configurable: true,
  });
  window.__mcpTools = tools;
});

// After page load:
await page.evaluate(async () => {
  const mod = await import('/src/mcp/ontosphereMcpServer.ts');
  await mod.registerMcpTools();
});

// Call a tool:
await page.evaluate(async ([name, params]) => window.__mcpTools[name](params),
  ['addNode', { iri: 'ex:alice', typeIri: 'foaf:Person', label: 'Alice' }]);

In a browser with native navigator.modelContext, tools register automatically on app load.

Example output

An AI agent built this from scratch in one session — full demo with tool calls →

Recommended workflow

loadOntology (TBox)
  → addNode ×N  (ABox individuals, rdf:type set)
  → addLink ×N  (object-property triples, edges appear on canvas)
  → runLayout   (dagre-lr recommended)
  → expandNode  (reveal annotation property cards — omit iri to expand all)
  → runReasoning (infer subClass / domain / range entailments; isConsistent=false signals contradiction)
  → fitCanvas + exportImage   (SVG snapshot, token-efficient)
  → exportGraph(turtle)       (final deliverable)

URL parameters

Demo

Demo	Final state
FOAF social network Build a social network, extend FOAF with employment classes, run reasoning
DL reasoning (Konclude) Build TBox + ABox, infer types via domain/range and transitivity
Scene ontology Load an external ontology, author individuals, export Turtle
Manchester Pizza Tutorial Full OWL pizza ontology — classes, disjointness, properties, DL reasoning

Regenerate:

npm run demo:all
# or individually:
node scripts/run-demo.mjs docs/mcp-demo/seeds/foaf-social-network.md
node scripts/run-demo.mjs docs/mcp-demo/seeds/reasoning-demo.md
node scripts/run-demo.mjs docs/mcp-demo/seeds/scene-ontology.md
node scripts/run-demo.mjs docs/mcp-demo/seeds/pizza-tutorial.md

Full tool declarations with input schemas: public/.well-known/mcp.json

Using Ontosphere with any AI

The demo scripts work against the live deployment — no local server needed. Any AI that can drive a browser (Claude Code, headless Playwright, computer-use agents) can use Ontosphere directly via its MCP tools.

Claude Code / Playwright (full automation)

Point the demo scripts at the deployed app:

node scripts/mcp-demo-reasoning.mjs --url https://thhanke.github.io/ontosphere
node scripts/mcp-demo-foaf.mjs       --url https://thhanke.github.io/ontosphere

The script opens a headless browser, navigates to the URL, registers the MCP tools, then drives the full workflow — building TBox + ABox, running reasoning, taking snapshots, exporting Turtle — exactly as shown in the demo documents.

ChatGPT, Gemini, Claude.ai — AI Relay Bridge

The AI Relay Bridge connects any AI chat tab to Ontosphere with no server, extension, or copy-paste. A bookmarklet watches the AI's output for backtick-wrapped JSON-RPC 2.0 tool calls, executes them in Ontosphere via a BroadcastChannel popup, and injects JSON-RPC responses back into the chat input automatically.

➡️ Full setup guide: docs/relay-bridge.md

Setup (one time):

1. Open Ontosphere, expand the AI Relay sidebar panel
2. Drag the Ontosphere Relay button to your browser bookmark bar
3. Go to your AI chat tab and click the bookmark — a small relay popup opens

Starter prompt (paste into your AI chat after clicking the bookmarklet):

You are connected to Ontosphere via a relay. A script in this tab intercepts your tool calls, runs them in Ontosphere, and injects results back as a user message. If a tool call returns success:false, read the error, fix the argument, and retry the same call immediately — never skip a failed call. Ask the user what they would like to build.

Output format — one JSON-RPC 2.0 call per line, backtick-wrapped:
`{"jsonrpc":"2.0","id":<N>,"method":"tools/call","params":{"name":"<toolName>","arguments":{...}}}`

Call help first to get full instructions and the tool list:
`{"jsonrpc":"2.0","id":0,"method":"tools/call","params":{"name":"help","arguments":{}}}`

The relay handles execution and result feedback automatically — no manual copy-paste needed.

Recording demo videos

See docs/demo-scripts/HOWTO.md for the full guide.

Two styles of demo video are supported:

Seed-driven — write a seed markdown file in docs/mcp-demo/seeds/ with JSON-RPC tool calls embedded in backtick blocks. The runner parses the seed and executes each turn directly against window.__mcpTools. Existing seeds: foaf-social-network, reasoning-demo, scene-ontology, pizza-tutorial.

Chat-style (side-by-side) — open demo-stage.html (mock chat left, app right), inject messages programmatically via addChatMessage(), and call tools on the app iframe via callToolOnStage(). No relay popup needed. Example: pizza-tutorial-chat.

Demo videos

To re-record all videos:

npm run demo:video   # starts dev server, records, encodes, kills server

Contributing / Development notes

• Canvas & top bar: src/components/Canvas/
• Cluster algorithms: src/components/Canvas/core/clusterAlgorithms/
• Layout functions: src/components/Canvas/layout/
• Search widget: src/components/Canvas/search/
• RDF worker and protocol: src/workers/
• MCP server and tools: src/mcp/
• Tests: src/tests/ — run with npm test.

License & authors

Check the repository root for licence and contributor information.