Plugin authoring (SDK 1.0)¶

This is the only page to implement against today: workspace TOML manifests + subprocess JSON contract.

Doc	Role
This guide	Canonical — ship plugins from here
Plugin policy	SDK 1.0 compatibility / support stance
plugin-model.md	Overview only — do not implement sketches
ui/PLUGIN_API_SPEC.md	Future OntoUI host — not the shipped VS Code contract
ui/PLUGIN_PLATFORM.md	Future Capability Providers — not the shipped host
design/PLUGIN_SPEC.md	Historical — do not implement

Strixonomy’s Plugin SDK 1.0 supports permissions, versioned API (api_version = "1"), UI contributions, lifecycle (depends_on, activation), and provider kinds (reasoner / query / refactor / graph).

Contribution matrix (SDK 1.0)¶

UI¶

Runtime / providers¶

Lifecycle¶

[plugin]
depends_on = ["strixonomy.naming-validator"]
activation = "on_startup"   # on_startup | on_command | on_workspace_open

Activation order is a topological sort of depends_on (cycles and missing deps fail discovery).

strixonomy plugins info <id> /path/to/workspace
strixonomy plugins enable <id> /path/to/workspace
strixonomy plugins disable <id> /path/to/workspace

LSP listPlugins exposes state, enabled, depends_on, and activation.

Permissions¶

Declare in [plugin]:

permissions = ["workspace.read", "workspace.write", "external_process"]

Manifests that omit permissions receive backward-compatible defaults (workspace.read, and external_process when entry is set). Those defaults are not sufficient for subprocess validate or ui_view — declare workspace.write as well.

Quick start¶

1. Create .strixonomy/plugins/*.toml in your ontology workspace.
2. Run strixonomy plugins list or strixonomy validate to execute validator plugins.
3. Install the Strixonomy extension and index the workspace — plugin diagnostics appear in the Problems panel.

See examples/plugin-workspace for reference providers.

Manifest schema¶

[plugin]
name = "my-validator"
version = "0.1.0"
kind = "validator"          # see contribution matrix
id = "org.example.my-validator"
api_version = "1"
entry = "my-plugin-cli"     # optional subprocess binary
depends_on = []
activation = "on_startup"
permissions = ["workspace.read", "workspace.write", "external_process"]

[capabilities]
validate = true
diagnostics = true
export = false
reasoner = false
query = false
refactor = false
graph = false

[config]
require_label = true
shapes_dir = "shapes"
provider_id = "optional-profile"   # reasoner / graph tip
graph_kind = "optional-kind"

[[ui.commands]]
id = "org.example.check"
title = "Run my validator"

[[ui.views]]
id = "org.example.view"
title = "My dockable view"

[[ui.preferences_pages]]
id = "org.example.prefs"
title = "My plugin"
category = "Validation"

[[ui.context_actions]]
id = "org.example.ctx"
title = "Validate this class"
scope = "entity"
applies_to = ["class"]
command = "org.example.check"

[[ui.inspector_cards]]
id = "my-card"
title = "My validator"
applies_to = ["class"]

Subprocess contract¶

Plugins with an entry binary are invoked as:

<entry> <action> --workspace <path> [--step <name>] [--view <id>] [--query <text>] [--iri <iri>] [--root <iri>]

Supported actions: validate, export, workflow, ui-view, reasoner.classify, query.run, refactor.preview, graph.build.

Stdout must be a single JSON object. Field tables by action:

Common optional fields on any response: logs, result (opaque object).

Example (query.run):

{
  "columns": ["iri", "label"],
  "rows": [["http://ex/A", "A"]],
  "logs": "optional"
}

There is no separate JSON Schema file yet — treat this table as the wire contract for api_version = "1".

Adding an in-process (host-builtin) Rust plugin¶

Subprocess plugins are the supported third-party path. In-process plugins ship inside the Strixonomy workspace (e.g. naming / markdown-export / SHACL):

1. Add a crate under crates/strixonomy-plugin-* implementing the host plugin traits used by strixonomy-plugin / strixonomy-plugin-builtins.
2. Register it in the builtins aggregator (strixonomy-plugin-builtins) so CLI/LSP discovery lists it.
3. Add a workspace fixture under examples/plugin-workspace/ and a row in testing matrix / cargo test -p <crate>.
4. Document the plugin id in the reference table below.

Do not copy sketches from design/PLUGIN_SPEC.md — that file is historical.

Reference in-process plugins:

• strixonomy-plugin-naming
• strixonomy-plugin-markdown-export
• strixonomy-plugin-shacl

Reference plugins¶

CLI¶

strixonomy plugins list /path/to/workspace
strixonomy plugins info strixonomy.naming-validator /path/to/workspace
strixonomy plugins enable org.example.demo-graph /path/to/workspace
strixonomy plugins disable org.example.demo-graph /path/to/workspace
strixonomy plugins run strixonomy.naming-validator --action validate /path/to/workspace
strixonomy plugins run org.example.demo-query --action query.run --query "SELECT *" /path/to/workspace
strixonomy plugins run org.example.demo-graph --action graph.build --iri http://example.org/Person /path/to/workspace
strixonomy validate /path/to/workspace
strixonomy docs /path/to/workspace -o out --plugin strixonomy.markdown-export
strixonomy workflow --plugin owlmake --step qc /path/to/workspace

LSP / Strixonomy¶

• strixonomy/listPlugins — plugins + UI metadata + lifecycle fields
• strixonomy/runPlugin — validate/export/workflow/ui_view/provider actions
• Strixonomy command Plugins: Run Command…
• Strixonomy command Plugins: Open View…
• Strixonomy command Plugins: Open Preferences…
• Strixonomy command Run Workflow (owlmake)
• Context menus — plugin context_actions on entities/ontologies

Debugging failures¶

Security: external_process¶

Plugins with entry and external_process run arbitrary binaries chosen by the workspace manifest. Treat trust like CI scripts:

• Prefer allowlisting plugin directories in enterprise deployments.
• Review entry paths before opening untrusted ontology repos.
• Path jailing rejects writes and binary paths outside the workspace root.

Threat-model overview: Security.

Stability¶

SDK 1.0 is frozen. Additive changes only within api_version = "1"; see Plugin policy.

Canonical author guide: this page only. Historical trait sketches live on GitHub as non-product background (PLUGIN_SPEC.md) and are excluded from public docs search. The React/TypeScript Plugin API spec is a future OntoUI target — not the shipped VS Code/CLI contract.