Plugin System — Extend SCHEMABOUND Without Rebuilding the Binary

Extend SCHEMABOUND’s schema at runtime by writing Turtle (TTL) files that declare new RDF classes and properties. Plugins follow an open to extension, closed to modification model: they can add new classes and properties but cannot override existing ones or change mutability flags on base properties.

Topic	Summary
What it is	TTL schema extensions loaded by OAM at runtime via `OamRuntime::discover_plugins()`
Who writes them	Data scientists, domain experts, community members — no Rust compilation required
How they load	Placed in `~/.schemabound/plugins/`, discovered automatically on backend restart
Validation	Authoritative validation happens when OAM loads plugins (install-time is best-effort)
Security	Plugins are schema-only (no executable code); validated at install time, never executed server-side

What Are Plugins?

Plugins extend the base RDF ontology without modifying compiled Rust crates. A plugin is a Turtle document (*.ttl) that declares new sh:NodeShape definitions for classes and properties using standard SHACL syntax.

When OAM starts, it discovers all .ttl files in the plugins directory, parses them as RDF triples, validates them against the base schema boundaries, and merges any valid extensions into the runtime registry. The result is an extended schema that new agent types can use without requiring a code change or binary rebuild.

How Plugins Load

OAM scans ~/.schemabound/plugins/ for .ttl files at startup
Each file is parsed as a Turtle document containing SHACL shape definitions
The validation engine checks that no existing classes are overridden and no mutability flags on base properties are changed
Valid extensions are merged into the runtime registry; invalid ones produce clear error messages

Writing a Plugin

A plugin is a Turtle file using standard RDF prefixes. Here’s an example that extends the CircuitState class with circuit-cutting configuration for distributed quantum computation (#094):

@prefix qg: <http://schemabound.ai/quantum-graph/> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

qg:CircuitState a sh:NodeShape ;
    sh:property [
        sh:path qg:wireCutIndices ;
        sh:datatype xsd:string ;  # JSON-encoded list of wire cut indices
        sh:maxCount 1 ;
        qg:mutable true .
    ] ;
    sh:property [
        sh:path qg:subcircuitCount ;
        sh:datatype xsd:int ;
        sh:maxCount 1 ;
        qg:mutable true .
    ] .

This declares qg:wireCutIndices (JSON-encoded list of wire cut indices for distributed QPU coordination) and qg:subcircuitCount (number of subcircuits after partitioning via KaHyPar). The TTL syntax is identical to migration files (see v007-ui-components.ttl for another reference).

Quantum Domain Plugins

Plugins can extend the quantum graph ontology with domain-specific schemas. Examples include:

Circuit cutting configuration (#094): qg:wireCutIndices, qg:subcircuitCount — distributed QPU coordination via PennyLane + KaHyPar partitioning
State vector simulation (#095): qg:hasAmplitudeIndex, qg:hasRealComponent, qg:hasImaginaryComponent — exact state vector representation for cuQuantum FFI on GPU

These plugins follow the same TTL syntax and validation rules as any other plugin.

Local Development Flow

Write your .ttl file following SHACL conventions

Place it in ~/.schemabound/plugins/:

mkdir -p ~/.schemabound/plugins
cp quantum_benchmarking.ttl ~/.schemabound/plugins/

Restart the SCHEMABOUND backend — plugins are discovered automatically on startup

To verify a plugin loaded:

sb plugin list
# → quantum-benchmarking (2.4 KB)

Validation Rules

Plugins are validated before loading. The engine enforces these boundaries:

Rule	What it prevents	Error if violated
Cannot override base classes	Accidental or intentional redefinition of existing RDF classes	`Cannot override base class`
Cannot change mutability flags on base properties	Agents modifying read-only fields that should stay static	`Cannot change mutability flag on property`
Must use valid XSD datatypes	Malformed type declarations that would break query execution	`Invalid datatype format`

Validation happens at install time and again when OAM loads the plugin. Errors are reported with clear messages before any extension takes effect — no runtime crashes from incompatible schemas.

Security Model

Plugins follow a strict security model:

Schema-only: Plugins contain RDF schema definitions, not executable code. No Python, Node.js, or WASM logic runs on the server.
Validated on load: When OAM starts, every plugin in ~/.schemabound/plugins/ is checked against base schema boundaries via OamRuntime::load_all(). Invalid plugins produce clear error messages and are not merged into the registry. Install-time validation (via sb plugin install) is best-effort; authoritative validation happens at load time.
No server-side execution: There is no sandboxed code execution for plugins — they contribute schema only, never behavior.
Open to extension, closed to modification: Plugins can add new classes and properties but cannot redefine existing ones or alter the mutability of base schema elements.

Installing from a Registry

To install plugins published by the community:

# List available versions and install the latest
sb plugin from-registry --name quantum-benchmarking

# Install a specific version
sb plugin from-registry --name quantum-benchmarking --version 0.1.0

The registry enforces version compatibility checks against your running SCHEMABOUND runtime before allowing installation of mismatched plugins.

Keyboard shortcuts

SCHEMABOUND Framework Documentation