Strixonomy LSP API (v0.27)¶

Status: Documents behavior in Strixonomy v0.27.0. Pre-1.0 APIs may change. Canonical feature list: What ships today.

This document describes what ships today in strixonomy-lsp. Custom methods use the strixonomy/* prefix; servers also accept legacy ontocore/* through at least 1.0 (migration/v0.27.md). For the v1.0 target (extended plugin methods), see LSP_SPEC.md.

Start here: index a workspace¶

Minimal custom-client flow after initialize:

1. Call strixonomy/indexWorkspace with { "rootUri": "file:///path/to/ontologies" }.
2. Call strixonomy/query with { "sql": "SELECT short_name FROM classes" } (or open LSP hello world).
3. Treat lsp-protocol.schema.json as the machine-readable contract.

Methods at a glance¶

Start with the schema (recommended)¶

If you are integrating Strixonomy outside VS Code (custom editor, scripts, automation), treat the JSON schema as the canonical, machine-readable contract for this release:

• LSP JSON Schema: lsp-protocol.schema.json (ships with product v0.27.0)

Schema vs product version¶

The schema file is the wire contract for the current product release. Until v1.0, minor product releases may add or change fields — always pin Strixonomy and consume the schema from the same tagged release. Historical labels such as “v0.17 schema” in older docs referred to the product release that last expanded the contract, not a separate schema versioning scheme.

Versioning and pinning (pre-1.0)¶

Until v1.0, minor releases may change request/response fields. For stable integrations:

• Pin Strixonomy to 0.27.0 in your tooling.
• Prefer consuming lsp-protocol.schema.json from the same tagged release you deploy.

Wire format¶

LSP JSON uses snake_case for enums serialized from Rust (EntityKind, ParseStatus, OntologyFormat), e.g. "kind": "class", "parse_status": "ok". SQL virtual tables use the same snake_case strings via as_str() on core enums (e.g. ParseStatus::as_str() → "ok", EntityKind::as_str() → "class", axiom_kind → "sub_class_of").

Reference links (implementation):

• Types: protocol.rs on GitHub
• JSON Schema: lsp-protocol.schema.json — query, DL Query, search, patch, reasoner, refactor, graph, semantic diff, schema browser, PR summary, plugin payloads, SWRL, explanation alternatives.
• Handlers: handlers.rs on GitHub
• Extension client: client.ts on GitHub

Transport¶

• stdio (VS Code language client)

Standard LSP capabilities¶

textDocument/completion (v0.11)¶

Advertised with trigger characters :, <, and @. Applies to Turtle (.ttl) files only.

Results are capped at 100 items per request.

textDocument/codeAction (v0.11)¶

Quick fixes are offered when a diagnostic includes encoded QuickFix data in Diagnostic.data. The client shows a lightbulb on supported codes:

Other diagnostic codes (parse_error, duplicate_label, orphan_class, …) publish diagnostics but do not ship quick fixes in v0.11.

Code actions use kind quickfix and return workspace edits (insert text, remove line, or apply Turtle patch).

Custom methods¶

All custom methods use the strixonomy/ prefix.

strixonomy/indexWorkspace¶

Rebuild the workspace catalog.

Params: IndexWorkspaceParams

{ "workspace_uri": "file:///path/to/workspace", "disk_cache": true }

workspace_uri is optional; the server uses the initialized workspace folder when omitted. Legacy clients may send workspaceUri (camelCase); prefer workspace_uri for new integrations.

Result: IndexWorkspaceResult

CatalogStats fields:

{
  "stats": {
    "ontology_count": 1,
    "class_count": 2,
    "object_property_count": 1,
    "data_property_count": 0,
    "annotation_property_count": 0,
    "individual_count": 1,
    "axiom_count": 2,
    "annotation_count": 4,
    "triple_count": 12,
    "error_count": 0,
    "diagnostic_error_count": 0,
    "diagnostic_warning_count": 0,
    "diagnostic_info_count": 0
  },
  "indexed_at": 1718000000
}

strixonomy/getCatalogSnapshot¶

Return documents, entities, and class hierarchy for the explorer UI.

Params: null

Result: CatalogSnapshot

Entity fields: iri, short_name, kind, ontology_id, labels[], comments[], deprecated, optional source_location.

Errors: NOT_INDEXED if the workspace has not been indexed.

strixonomy/getEntity¶

Return detailed entity information for the inspector.

Params: GetEntityParams

{ "iri": "http://example.org/people#Person" }

Result: GetEntityResult with detail (EntityDetail):

EntityAxiomSummary fields:

Errors: NOT_INDEXED, ENTITY_NOT_FOUND

strixonomy/query¶

Run a SQL-like query against the indexed workspace catalog.

Params: QueryParams

{ "sql": "SELECT short_name, labels FROM classes" }

Result: TabularQueryResult

Errors: NOT_INDEXED, QUERY_FAILED

strixonomy/sparql¶

Run SPARQL against the indexed catalog store.

Params: SparqlParams

{ "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" }

Result: TabularQueryResult (same shape as strixonomy/query).

Errors: NOT_INDEXED, QUERY_FAILED

strixonomy/parseManchester¶

Parse and validate a Manchester class expression; return normalized text, Turtle fragment, expression tree, diagnostics, and catalog-based completion lists.

Params: ParseManchesterParams

{
  "expression": "ex:hasRecord some ex:MedicalRecord",
  "axiom_kind": "sub_class_of",
  "entity_iri": "http://example.org/clinic#Patient",
  "document_uri": "file:///path/to/ontology.ttl"
}

Result: ParseManchesterResult

Errors: NOT_INDEXED, MANCHESTER_INVALID

strixonomy/applyAxiomPatch¶

Apply patch operations to Turtle (.ttl), OBO (.obo), RDF/XML (.owl/.rdf), or OWL/XML (.owx) documents. See authoring.md, OBO authoring, and OWL/XML write-back.

Buffer-first (VS Code): Reads the open document buffer when available, applies patches in memory, updates the buffer, writes disk, then reindexes. See errors.md for APPLIED_NOT_INDEXED.

Params: ApplyAxiomPatchParams

Legacy patch array (unchanged since v0.11):

{
  "document_uri": "file:///path/to/ontology.ttl",
  "patches": [
    { "op": "add_label", "entity_iri": "http://ex#Person", "value": "Human" }
  ],
  "preview_only": false
}

v0.19+ transaction envelope (optional): same operations wrapped for strixonomy-edit apply path. Legacy patches arrays remain accepted.

{
  "document_uri": "file:///path/to/ontology.obo",
  "transaction": {
    "changes": [
      { "op": "add_label", "entity_iri": "http://ex#Person", "value": "Human" }
    ]
  },
  "preview_only": false
}

Either patches or transaction.changes may be supplied (not both required). See migration v0.19.

Result: ApplyAxiomPatchResult (flattened patch result + optional entity):

EntityAxiomSummary kinds: sub_class_of, equivalent_class, disjoint_class, domain, range, property_chain (property chains editable via patch ops since v0.12).

Import ops (v0.11): add_import and remove_import — see patch-reference.md and Manage Imports.

See patch-reference.md for CLI ApplyPatchResult examples and errors.md for failure codes.

Errors: PATCH_INVALID, UNSUPPORTED_FORMAT, NOT_INDEXED, APPLIED_NOT_INDEXED

strixonomy/runReasoner¶

Run OWL classification via OntoLogos 1.0.0 (el, rl, rdfs, dl, auto).

Params: RunReasonerParams

{ "profile": "el", "auto_detect": true }

Result: RunReasonerResult

Errors: NOT_INDEXED, REASONER_FAILED

Cancelling a reasoner run ($/cancelRequest)¶

Long strixonomy/runReasoner calls honor the standard LSP notification $/cancelRequest while classification (and enrich steps) run.

Client: send a notification (not a request):

{ "jsonrpc": "2.0", "method": "$/cancelRequest", "params": { "id": <request-id-of-runReasoner> } }

Server behavior:

• Marks the matching in-flight reasoner request cancelled
• Returns a JSON-RPC error for that runReasoner call with data.code = REASONER_FAILED and message Reasoner run cancelled
• Does not update the reasoner snapshot on cancel (a cancelled run leaves the previous snapshot unchanged)

Cancel only applies to the active reasoner request id. Unrelated inbox messages received during classify are deferred and processed after the wait loop resumes.

strixonomy/getExplanation (v0.15+)¶

Return an EL/RL/RDFS/DL explanation for an unsatisfiable class. Responses may include multiple alternative justifications and staleness metadata for cache invalidation.

Params: GetExplanationParams

{ "class_iri": "http://example.org#Invalid", "profile": "el" }

Result: GetExplanationResult

Clients should treat explanations as stale when indexed_at or content_hash no longer matches the current workspace snapshot. The Strixonomy explanation panel shows a stale warning and offers re-run.

Errors: NOT_INDEXED, EXPLANATION_FAILED

strixonomy/getGraph (v0.7)¶

Returns graph nodes and edges for visualization webviews.

Params:

Graph panel (v0.26): React graph webview supports asserted / inferred-only / combined modes, filtering, search dimming, inferred unsatisfiable overlays, Graph|List alternate, keyboard navigation, and virtualized render (onlyRenderVisibleElements). Query Workbench and Refactor Preview can open result graphs via query_result / refactor_preview.

Result: { graph: { nodes, edges, truncated, graph_kind } } — nodes may include namespace, ontology_iri, deprecated, unsatisfiable, equivalent.

Errors: NOT_INDEXED, GRAPH_FAILED, INVALID_PARAMS (e.g. missing root_iri for neighborhood)

strixonomy/runRobot (v0.7)¶

Runs a ROBOT CLI subcommand.

Params: { subcommand, args?, robot_path? }

Result: { exit_code, stdout, stderr }

Errors: ROBOT_FAILED (ROBOT missing, non-zero exit, or I/O failure), INVALID_PARAMS

strixonomy/findUsages (v0.8)¶

Return structured IRI usages across the workspace catalog and Turtle text spans.

Params: { "iri": "http://example.org/people#Person" }

Result: { "usages": UsageSummary[] } — each usage has iri, referenced_iri, file, line, column, kind, context (byte ranges are not serialized on the wire).

Errors: NOT_INDEXED, INVALID_PARAMS

strixonomy/previewRefactor (v0.8)¶

Build a refactor plan without writing files.

Params: flattened refactor request — one of:

Result: RefactorPlan — { changes: FileChange[], warnings: string[] } where each change has path, preview_text, original_text, and hunks.

Errors: NOT_INDEXED, REFACTOR_FAILED, INVALID_PARAMS

strixonomy/applyRefactor (v0.8)¶

Apply a previously previewed refactor plan. The server re-previews from request, verifies the submitted plan matches, validates paths against the workspace jail, writes atomically, syncs open buffers, and reindexes.

Params: { "plan": RefactorPlan, "request": RefactorRequest, "preview_only"?: boolean }

Result: { "files_written": number, "reindex_warning"?: string }

Errors: NOT_INDEXED, REFACTOR_FAILED, INVALID_PARAMS

strixonomy/semanticDiff (v0.10+)¶

Compare semantic catalogs between git refs, directories, or indexed workspace snapshots. Alias: strixonomy/getSemanticDiff.

Params: SemanticDiffParams

When both left_path and right_path are set, git refs are ignored and directories are compared directly (paths must resolve within workspace roots).

Result: { "diff": DiffResult } — axiom-level changes, entity additions/removals, breaking-change flags. With format: "pr-summary", also includes formatted Markdown string. See Semantic diff guide.

Errors: INVALID_PARAMS (bad refs, paths outside workspace, git errors), NOT_INDEXED (indexed-catalog ref before first index), REASONER_FAILED (when reasoner: true enrichment fails)

strixonomy/listSqlSchema (v0.13+)¶

Returns SQL virtual table metadata for the Query Workbench schema browser.

Params: none (uses indexed workspace catalog)

Result: { "tables": [{ "name": string, "columns": [{ "name": string, "type": string }] }] }

Includes core tables (classes, properties, …) and Horned-OWL axiom projections. See sql-reference.md.

Errors: NOT_INDEXED

textDocument/semanticTokens/full (v0.13+)¶

Standard LSP semantic tokens for Turtle (.ttl) and OBO (.obo) open documents.

Token types: namespace, iri, keyword, comment, string

Requires document text in the LSP open-document buffer (unsaved buffers supported).

strixonomy/listPlugins (v0.14+)¶

Returns discovered workspace plugins from .strixonomy/plugins/*.toml plus built-in registration metadata.

Params: none (uses indexed workspace root)

Result: { "plugins": PluginDescriptor[] }

Errors: NOT_INDEXED, INDEX_FAILED (discovery/host failure)

strixonomy/listCommands (v0.17+)¶

Return stable command metadata for menus, toolbars, and enablement.

Params: none

Result: { "commands": CommandDescriptor[] }

Errors: none (empty commands if the server has no registered descriptors)

strixonomy/getWorkspaceUiState (v0.17+)¶

Return enablement inputs for the command registry.

Params:

Result: WorkspaceUiState (has_ontology, is_dirty, has_selection, selection_editable, reasoner_*, active_ontology_id, optional stats)

Errors: none

strixonomy/getDialogSchema (v0.17+)¶

Params: { "dialog_id": string }

Result: { "schema": DialogSchema } with id, title, fields[], primary_action.

Known dialog ids include new_ontology, export_ontology, save_as, prefix_manager, ontology_metadata, search, metrics, delete_entity, reasoner_settings, preferences, import, rename.

Errors: INVALID_PARAMS (unknown dialog_id)

strixonomy/createOntology (v0.17+)¶

Scaffold a new Turtle or OBO ontology file under the workspace.

Params: { "path", "ontology_iri", "version_iri"?, "format"?, "prefixes"? }

Result: { "path", "ontology_iri" }

Errors: INVALID_PARAMS (workspace not initialized, path outside roots, file already exists, unsafe path), INDEX_FAILED (I/O failure creating the file)

strixonomy/exportOntology (v0.17+)¶

Export/convert an ontology via ROBOT convert, with same-format copy fallback when ROBOT is unavailable.

Params: { "source_path", "output_path", "format"? }

Result: { "output_path", "success", "logs"? } — success may be false when ROBOT exits non-zero (still an LSP success response).

Errors: INVALID_PARAMS (path outside workspace), ROBOT_FAILED (ROBOT unavailable and formats differ, or copy failure)

strixonomy/setActiveOntology (v0.17+)¶

Set the active ontology id used for new-axiom targeting.

Params: { "ontology_id": string } (document id, path, or base IRI)

Result: { "active_ontology_id": string }

Errors: ENTITY_NOT_FOUND (id not in the indexed catalog), NOT_INDEXED

strixonomy/deleteImpact (v0.17+)¶

Preview delete impact for an entity.

Params: { "entity_iri": string }

Result: { "entity_iri", "usage_count", "axiom_count", "referencing_entities", "warnings" }

Errors: NOT_INDEXED

strixonomy/runPlugin (v0.14+, views v0.15)¶

Run a plugin validate/export/workflow/ui_view action.

Params:

Result: { "diagnostics": DiagnosticSummary[], "output_paths": string[], "logs": string?, "view_html": string?, "success": boolean }

view_html is populated for ui_view actions — HTML rendered in the plugin view panel.

Plugin diagnostics use code values like plugin:<id>:<code> and LSP source strixonomy-plugin:<id>. See errors.md.

Errors: NOT_INDEXED, INDEX_FAILED (plugin not found, missing permission, unsupported action, subprocess failure, or export error)

getCatalogSnapshot includes plugin diagnostics merged after index (same wire codes).

strixonomy/dlQuery (v0.24+)¶

Run a Manchester class expression DL Query (instances / subclasses / superclasses / equivalents). Named classes use hierarchy + realization; anonymous expressions inject a temporary equivalent class (never written to disk).

Params:

Result:

Errors: NOT_INDEXED, REASONER_FAILED, INVALID_PARAMS, MANCHESTER_INVALID

Honesty notes: DL Query guide · cookbook: examples/dl-query.md.

strixonomy/search (v0.24+)¶

Workspace entity search for QuickPick / live search UIs.

Params:

Result: { entities: EntityDetail[] }

Errors: NOT_INDEXED

strixonomy/checkInstance (v0.23+)¶

Check whether an individual is an instance of a class (ABox).

Params:

Result: { individual_iri, class_iri, entailed, profile_used, duration_ms }

Errors: NOT_INDEXED, REASONER_FAILED, INVALID_PARAMS

strixonomy/listSwrlRules (v0.23+)¶

List SWRL rules found in open Turtle buffers and indexed .ttl documents (strixonomy:swrlRule JSON).

Params: none

Result: { rules: SwrlRuleListItem[] } — each item includes id/label, body/head counts, enabled flag, optional document URI

Errors: none (returns an empty list when no rules are present; indexing is recommended but not required for open buffers)

strixonomy/validateSwrlRule (v0.23+)¶

Validate a SWRL rule JSON string (builtins / DLSafe diagnostics). Does not write the ontology.

Params: { rule_json: string }

Result: { diagnostics: SwrlDiagnostic[] }

Errors: INVALID_PARAMS (unparseable rule JSON)

strixonomy/parseSwrlRule (v0.23+)¶

Parse SWRL rule JSON into the Strixonomy SWRL IR.

Params: { rule_json: string }

Result: { rule: SwrlRule }

Errors: INVALID_PARAMS (unparseable rule JSON)

Structured errors¶

Custom method failures return LspErrorPayload in the JSON-RPC error data field. Full catalog: errors.md.

Still planned (see LSP_SPEC)¶

These remain target items in LSP_SPEC.md — they are not shipped as first-class LSP methods today:

• Dedicated LSP strixonomy/realize (use CLI strixonomy realize / check-instance instead)
• Additional standard LSP surfaces called out as future in LSP_SPEC (beyond completion, codeAction, semantic tokens, rename/prepareRename, hover, definition)

Already shipped (do not treat as gaps): textDocument/completion (v0.11), semantic tokens + listSqlSchema (v0.13), prepareRename / rename for IRI/QName, semantic diff (strixonomy/semanticDiff + Semantic diff guide).