Oxiland

Oxiland is a safe Rust facade for Redland-shaped RDF workflows—models, contexts, statement matching, SPARQL query/update/results, and stream-oriented Turtle / N-Triples / N-Quads / TriG / RDF/XML I/O—backed by pinned Oxigraph 0.5.9 with #![forbid(unsafe_code)].

Use it when you want Redland concepts and explicit unsupported/error behavior without C ownership; use Oxigraph directly when you only need the engine API. Version 0.4.0 covers the trusted core model, Redland-shaped RDF I/O, SPARQL query/update/results, and durable Fjall storage (format v1) with transactions, with scoped evidence in the parity ledger—not C ABI/source compatibility or full librdf accounting.

[!IMPORTANT] Compatibility claims are evidence-scoped. See the parity ledger and 0.4 report. Do not read “Redland-shaped” as drop-in C or ABI compatibility.

When to use Oxiland

A longer comparison (including Sophia and native Redland) is in docs/evaluators/positioning.md.

Current capabilities

“Available” means the current public workflow is implemented and tested. It does not imply full subsystem parity with Redland.

Advertised RDF syntaxes

Ambiguous aliases (text/plain, application/xml, .txt, .xml) and N3 / JSON-LD return Error::Unsupported. Full dispositions: compatibility/baseline/format-matrix.json.

Requirements

• Rust 1.87 or newer (edition 2024; matches the Oxigraph 0.5.9 pin used for compatibility testing)

Install or update with rustup:

rustup update stable
rustc --version   # >= 1.87

Installation

[dependencies]
oxiland = "0.4.0"

Quick start

use oxiland::terms::{Literal, NamedNode, Triple};
use oxiland::{Model, Query, QueryResults};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = Model::new()?;

    model.add(Triple::new(
        NamedNode::new("https://example.com/alice")?,
        NamedNode::new("https://example.com/name")?,
        Literal::new_simple_literal("Alice"),
    ))?;

    let result = Query::new("ASK { ?s ?p ?o }").execute(&model)?;
    assert!(matches!(result, QueryResults::Boolean(true)));

    Ok(())
}

Model::add returns true when it inserts a new statement and false when the same statement already exists.

cargo run --example quick_start

More workflows: Getting started.

Contexts and pattern matching

Redland contexts map to Oxigraph graph names:

use oxiland::terms::{GraphName, Literal, NamedNode, Triple};
use oxiland::{Model, StatementPattern};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = Model::new()?;
    let subject = NamedNode::new("https://example.com/alice")?;
    let graph = NamedNode::new("https://example.com/people")?;

    model.add_to_graph(
        Triple::new(
            subject.clone(),
            NamedNode::new("https://example.com/name")?,
            Literal::new_simple_literal("Alice"),
        ),
        GraphName::NamedNode(graph),
    )?;

    let matches = model
        .find(StatementPattern {
            subject: Some(subject.as_ref().into()),
            ..StatementPattern::default()
        })
        .collect::<Result<Vec<_>, _>>()?;

    assert_eq!(matches.len(), 1);
    Ok(())
}

Model::find returns a streaming StatementMatches iterator over a store snapshot (ADR-005). Run cargo run --example contexts.

Parsing and serialization

use oxiland::io::{Parser, Serializer, Syntax};
use oxiland::Model;

fn main() -> oxiland::Result<()> {
    let model = Model::new()?;
    Parser::for_syntax(Syntax::Turtle)
        .base_iri("https://example.com/")?
        .load_collecting(&model, b"<alice> <name> \"Alice\" .".as_slice())?;

    let ntriples = Serializer::for_syntax(Syntax::NTriples)
        .serialize_model_to_string(&model)?;
    assert!(ntriples.contains("Alice"));
    Ok(())
}

Parser::load_into inserts progressively and may leave partial data on parse failure (ADR-007). Prefer load_collecting when you need parse-then-insert batching without transactions. See I/O guide and cargo run --example progressive_load.

Persistent storage

Model::open stores quads in a Fjall keyspace and keeps an Oxigraph in-memory working set for querying:

use oxiland::Model;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = Model::open("./data/oxiland-store")?;
    assert!(model.is_empty()?);
    Ok(())
}

Supported (format v1): on-disk compatibility is promised for Oxiland 0.4.x patch releases (ADR-006). Pre-0.4 experimental directories need Model::migrate_legacy_store. Prefer N-Quads export for archival copies across majors. Details: persistence guide.

Documentation

Published guides: oxiland.readthedocs.io. API reference: docs.rs/oxiland.

Also: Changelog · FAQ · Security policy · Code of conduct

Architecture (summary)

Rust application
      │
      ▼
Oxiland safe facade ──> Oxigraph RDF, storage, I/O, and SPARQL
      ▲
      │
Future oxiland (PyPI, 0.7+) and oxiland-capi (0.8+)

Roadmap highlights: 0.4 durable storage contracts, 0.7 Python package, 0.8 C ABI preview. Full plan: docs/ROADMAP.md.

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo doc --no-deps
python3 scripts/check-inventory.py
python3 scripts/check-docs.py
scripts/generate-public-api.sh check

License

Licensed under either of Apache-2.0 or MIT at your option.