Skip to content

Rust API reference

Strixonomy exposes a Rust library through the strixonomy façade crate and individual strixonomy-* implementation crates.

Stability

Surface Status
strixonomy::Workspace Stable since v0.10 — preferred high-level API
strixonomy::catalog::IndexBuilder Stable for custom pipelines
LSP JSON (strixonomy/* methods) Pre-1.0 — may change between minor releases
SQL virtual table columns Pre-1.0 — pin versions in production

Pin dependencies in Cargo.toml:

[dependencies]
strixonomy = "0.27"

For CI and reproducible builds: cargo install strixonomy-cli --locked --version 0.27.0.

docs.rs

Generated API documentation is published on docs.rs:

Crate docs.rs
strixonomy docs.rs/strixonomy
strixonomy-core docs.rs/strixonomy-core
strixonomy-parser docs.rs/strixonomy-parser
strixonomy-catalog docs.rs/strixonomy-catalog
strixonomy-diagnostics docs.rs/strixonomy-diagnostics
strixonomy-query docs.rs/strixonomy-query
strixonomy-reasoner docs.rs/strixonomy-reasoner
strixonomy-robot docs.rs/strixonomy-robot
strixonomy-owl docs.rs/strixonomy-owl
strixonomy-obo docs.rs/strixonomy-obo
strixonomy-lsp docs.rs/strixonomy-lsp
strixonomy-diff docs.rs/strixonomy-diff
strixonomy-docs docs.rs/strixonomy-docs
strixonomy-refactor docs.rs/strixonomy-refactor
strixonomy-edit docs.rs/strixonomy-edit
strixonomy-plugin docs.rs/strixonomy-plugin (Plugin SDK 1.0 wire; see Plugin policy)
strixonomy-cli docs.rs/strixonomy-cli

Search all crates: crates.io search?q=strixonomy.

Book ↔ docs.rs crosswalk

Use this book for workflows, limits, and LSP JSON; use docs.rs for Rust type signatures and module layout.

You need… Start in the book Rust API (docs.rs)
Open and query a workspace Rust library guide, Workspace engine Workspace, WorkspaceOptions
SQL virtual tables SQL reference, SQL views strixonomy::query
SPARQL SPARQL reference Workspace::sparql
Turtle patch apply Patch JSON, Authoring strixonomy::owl
Semantic transactions (v0.19+) Rust library guide strixonomy-edit
OBO patch apply OBO authoring strixonomy::obo
Semantic diff Semantic diff strixonomy-diff
Refactoring Refactoring guide strixonomy-refactor
Docs export Docs export strixonomy::docs
LSP integration LSP API, LSP overview strixonomy-lsp
Custom LSP client LSP hello world
Error codes / exit behavior Errors reference Crate thiserror types per module
Resource limits Workspace limits Index builder options in strixonomy-catalog

Recommended entry point: Workspace

use strixonomy::Workspace;

let ws = Workspace::open("./ontologies")?;

// Catalog stats
let stats = ws.stats();
println!("{} classes", stats.class_count);

// Catalog SQL (subset) — not full SQL; see sql-reference.md
let result = ws.query("SELECT short_name, labels FROM classes")?;

// SPARQL over indexed triples
let sparql = ws.sparql("SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10")?;

// Lint diagnostics from indexing
for d in ws.diagnostics() {
    println!("{:?}: {}", d.code, d.message);
}

// Entity search by IRI fragment, short name, or label
let hits = ws.search("Person");

Workspace::open returns Result<Workspace, strixonomy::Error>. Map failure modes with Errors reference and Known limitations.

Error taxonomy (façade vs core)

Type Use when
strixonomy::Error Preferred in application code against the façade crate — ? from Workspace methods
StrixonomyError / crate-local errors (CatalogError, QueryError, …) Lower-level strixonomy-* crates or migration notes that still name core errors
CLI exit codes Automation — Errors / workspace limits. Note: classify with unsatisfiable classes does not fail the Rust API by itself; the CLI may exit non-zero when unsat is treated as failure
LSP error codes Editor clients — LSP API

Prefer strixonomy::Error for new embedders. Compat / rename details: v0.27 migration.

WorkspaceOptions

use strixonomy::{Workspace, WorkspaceOptions};

let ws = Workspace::open_with_options(
    WorkspaceOptions::single("./ontology")
        .with_disk_cache(true)
        .with_scan_roots(vec!["./imports".into()]),
)?;
ws.reindex_incremental()?;
let diff = ws.diff_against_path("./baseline")?;
Option Purpose
single(path) Primary workspace root
with_scan_roots(vec![...]) Additional scan roots (primary root is always included)
with_disk_cache(true) Persist parse snapshots under .strixonomy/cache/

Workspace method reference

Operational contract for the high-level façade. Full type signatures: Workspace on docs.rs.

Method Parameters Returns Errors Notes
open(path) Workspace root directory Workspace CatalogError Full index on open
open_with_options(opts) WorkspaceOptions Workspace CatalogError Disk cache, multi-root scan
reindex() CatalogStats CatalogError Full rebuild
reindex_incremental() CatalogStats CatalogError Hash-based reuse when possible
stats() / diagnostics() counts / Vec<Diagnostic> From last successful index
query(sql) Catalog SQL (subset) QueryResult QueryError Rows may truncate at 100k — check limits
sparql(query) SPARQL string SparqlResult QueryError Same row cap; prefer for graph patterns
search(needle) IRI fragment / short name / label hits In-memory catalog search
classify(profile) ReasonerId ClassificationResult ReasonerError Does not fail only because classes are unsatisfiable — inspect consistent
explain(profile, request) Profile + class/request ExplanationResult ReasonerError Run after classify when needed
reasoner_input() ReasonerInput ReasonerError Snapshot for advanced reasoner use
diff(other) Another Workspace DiffResult In-memory catalog compare
diff_against_path(path) Other directory DiffResult CatalogError Indexes the other path
import_graph() / import_graph_with Optional request graph payload GraphError For visualization / export
export_docs(options) Format / output options export errors via Error Markdown/HTML
discover_plugins() plugin list host errors Requires plugins feature
catalog() / root() / scan_roots() refs / paths Advanced / introspection

Side effects: indexing may write under .strixonomy/cache/ when disk cache is enabled. Patch helpers (strixonomy::owl / strixonomy::obo) write ontology source files — preview before apply in production tools.

Unified façade error: map crate-local errors into strixonomy::Error with ? when your function returns Result<_, strixonomy::Error>. Crosswalk: Errors — Rust library.

Additional helpers

Use apply_owl_patches / apply_obo_patches from strixonomy::owl and strixonomy::obo when importing both patch helpers. Refactoring helpers live in strixonomy::refactor (preview_rename_iri, apply_refactor_plan_checked, …). Pass workspace_root from Workspace::root().

Semantic transactions (strixonomy-edit, v0.19+)

v0.19 adds a format-aware transaction layer for ordered Turtle/OBO edits with compose, validate, and invert:

use strixonomy_edit::Transaction;
use strixonomy_owl::PatchOp;

let txn = Transaction::from_turtle(vec![
    PatchOp::AddLabel {
        entity_iri: "http://example.org/Person".into(),
        value: "Person".into(),
    },
]);

// Preview / apply via strixonomy::edit or LSP applyAxiomPatch envelope
let inverted = txn.invert()?;

Lower-level API

When you need buffer overrides, partial rebuilds, or direct catalog access:

use strixonomy::catalog::IndexBuilder;
use strixonomy::query::query_catalog;

let catalog = IndexBuilder::new().workspace(".").build()?;
let result = query_catalog(&catalog, "SELECT * FROM classes")?;

See Workspace engine for the indexing pipeline and crate map for module boundaries.

Documentation export (docs module)

use strixonomy::{Workspace, docs::{export_workspace, ExportOptions}};

let ws = Workspace::open("./fixtures")?;
export_workspace(
    ws.catalog(),
    ExportOptions::markdown("/tmp/onto-docs"),
)?;

See Documentation export guide.

Examples in this repository

cargo run -p strixonomy --example strixonomy_workspace   # Workspace API
cargo run -p strixonomy --example workspace_operations # classify, graph, docs export
cargo run -p strixonomy --example index_and_query      # Workspace + SQL query (fixtures/)
cargo run -p strixonomy --example error_handling        # strixonomy::Error handling
cargo run -p strixonomy --example semantic_diff         # Git/workspace semantic diff (requires git repo)

See Examples index for CLI cookbooks and fixture workflows.

Topic Document
Embedding walkthrough Rust library guide
CLI and crates overview Rust & CLI guide
LSP wire format LSP API
SQL virtual tables SQL reference
Error codes Errors reference
Resource limits Workspace limits