Skip to content

Using Strixonomy as a Rust library

Embed Strixonomy in tools, pipelines, or custom CLIs via the strixonomy façade crate from crates.io. You do not need to clone this repository.

Strixonomy (previously branded OntoIndex / ontoindex-*) is implemented by the strixonomy-* crates. See v0.9 migration.

Pre-1.0: public APIs may change between minor releases until v1.0. Pin minors in production. Crates are at 0.27.x.

Prefer Workspace

For new code, use the Workspace API (strixonomy = "0.27"). Lower-level IndexBuilder remains available for specialized pipelines — see Rust API.

crates.io first (5 minutes)

  1. Create a crate (or open an existing one).
  2. Add Strixonomy:
[dependencies]
strixonomy = "0.27"
  1. Point Workspace::open at your ontology directory (any folder of .ttl / .obo / other indexed formats):
use strixonomy::Workspace;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ws = Workspace::open("./ontologies")?;
    let result = ws.query("SELECT short_name, labels FROM classes")?;
    for row in &result.rows {
        println!("{} — {}", row["short_name"], row["labels"]);
    }
    Ok(())
}
  1. Run with cargo run. First compile pulls Strixonomy dependencies (can take several minutes cold).

Errors: Workspace::open returns CatalogError; query / sparql return QueryError. The façade also exposes a unified strixonomy::Error for From conversion — see Errors reference.

Method-level params / returns / side effects: Rust API — Workspace methods.

Minimal Cargo.toml recipes

Query / index only (façade defaults):

[dependencies]
strixonomy = "0.27"

Classify + explain (same crate — reasoner is included):

[dependencies]
strixonomy = "0.27"

use strixonomy::Workspace;
use strixonomy::reasoner::ReasonerId;

let ws = Workspace::open("./ontologies")?;
let result = ws.classify(ReasonerId::El)?;

Semantic patch / transactions (extra crates):

[dependencies]
strixonomy = "0.27"
strixonomy-edit = "0.27"
strixonomy-owl = "0.27"

See Semantic transactions below.

Optional: monorepo examples (clone only)

In-repo examples under the unpublished strixonomy package need a git clone:

git clone https://github.com/eddiethedean/strixonomy.git && cd strixonomy
cargo run -p strixonomy --example strixonomy_workspace
cargo run -p strixonomy --example workspace_operations
cargo run -p strixonomy --example error_handling

Those examples use fixtures/ — that directory exists only in a clone, not after cargo add strixonomy.

Lower-level: index and query

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

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

Crate map

See Strixonomy crate map for the full table. Summary:

Crate Role
strixonomy Public façade — Workspace, module re-exports
strixonomy-* Implementation crates (stable names until v1.0)

Classification example

use strixonomy::Workspace;
use strixonomy::reasoner::ReasonerId;

let ws = Workspace::open(".")?;
let result = ws.classify(ReasonerId::El)?;
println!("consistent: {}", result.consistent);

Workspace options (v0.10+)

use strixonomy::{Workspace, WorkspaceOptions};

let ws = Workspace::open_with_options(
    WorkspaceOptions::single("./ontology")
        .with_disk_cache(true),
)?;
ws.reindex_incremental()?;
let diff = ws.diff_against_path("./baseline")?;
Option Purpose
WorkspaceOptions::single(path) Primary workspace root
with_disk_cache(true) Persist parse cache under .strixonomy/cache/
reindex_incremental() Reuse unchanged documents by content hash

Semantic diff: ws.diff(), ws.diff_against_path(), or strixonomy::diff::diff_git_refs — see Semantic diff.

Semantic transactions (strixonomy-edit)

v0.19+ ships strixonomy-edit for ordered, invertible Turtle/OBO edit batches. Use when building undo/redo, audit trails, or multi-step apply pipelines:

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

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

let undo = txn.invert()?;

Dependency: strixonomy-edit = "0.27". Full API: Rust API — semantic transactions · docs.rs/strixonomy-edit.

Next steps

Goal Doc
Method reference Rust API
Error types Errors
CLI instead of embed Install CLI & CI (detail)
Stability expectations API stability