oxilite-jsonld
JSON-LD documents in oxilite. Store a JSON-LD document and get two things:
- the exact bytes back whenever you ask for them;
- its RDF in a named graph of its own, which you query with SPARQL like any other data.
It runs natively and on Cloudflare D1, and every write is one atomic request.
Website · API docs · Guide and architecture · Changelog and issues
Usage
Enable the jsonld feature of oxilite:
= { = "0.2", = ["jsonld"] }
use QueryResults;
use Store;
let store = new?;
let docs = store.jsonld?;
let key = docs.put_document?;
// The RDF is in the graph named after the key…
let r = store.query?;
// …and the JSON comes back byte for byte.
let doc = docs.get_document?.unwrap;
println!;
// Replace (same key) and remove are atomic and clear exactly the document's triples.
docs.remove_document?;
# Result::Ok
AsyncStore::jsonld() has the same methods for D1. From JavaScript, call store.jsonld() in @oxilite/node or @oxilite/d1.
Keys and graphs
| Option | Values | Default |
|---|---|---|
key |
Id (top-level @id/id), Pointer("/credentialSubject/id"), ContentHash, Explicit |
Id |
on_missing_key |
Reject, ContentHash (urn:oxilite:doc:sha256:<hex>) |
Reject |
graph |
Key (the key is the graph IRI), Template("https://ex.org/g/{key}"), Fixed(iri), DefaultGraph |
Key |
use ;
let docs = store.jsonld_with?;
With Key or Template, each document owns its graph: replace and remove delete the graph without reading it first. With Fixed or DefaultGraph, documents share a graph. The previous version is then read back and exactly its triples are deleted.
Contexts: offline by default
Remote @context IRIs are resolved without network access, in this order:
- contexts registered on the handle:
JsonLdOptions::with_context(iri, json); - contexts persisted in the store with
put_context(iri, json). These work from every process and on D1.
An unknown context fails with JsonLdError::ContextNotFound(iri), and nothing is written. To download unknown contexts, enable the network feature (native only). Then set fetcher: Some(oxilite_jsonld::http_fetcher()), and set cache_fetched: true to persist what was downloaded.
What you get
- Verbatim storage: the raw JSON, its SHA-256, the target graph and the time it was stored, in the
jsonld_documentstable. - Standard conversion: the
json-ldcrate implements the JSON-LD 1.1 processing algorithms. 450 tests of the W3CtoRdfsuite pass; the 4 allow-listed exceptions are limitations ofjson-ld0.21. - Graphs the document defines: the graphs a document defines, such as
@graphcontainers and proofs, belong to it. Replacing or removing the document removes them too. - Isolated blank nodes: blank-node labels are derived from the document's key. Two documents never share a blank node, and re-storing a document changes nothing.
- Atomic writes: one request, which is one D1 batch. Long documents are written in chunks inside that batch. A document that cannot fit in one batch fails with
DocumentTooLargerather than being split. - Metadata lookups:
find_documents(&DocumentFilter { issuer, subject, type_, valid_at, profile, after, limit })reads indexed columns, not SPARQL.oxilite-vcfills them for credentials. - Drift repair: SPARQL UPDATE can edit document graphs.
check_documents()reports documents whose graphs no longer match their JSON, andrebuild_graph(key)regenerates them from the stored JSON, which is the source of truth. - Opt-in tables: the three tables are created when you first open a handle. For D1 migrations, use
oxilite_jsonld::schema::schema_sql.
Features
network: download unknown contexts over HTTP (native only; off by default).json: JSON forms of options, filters and documents, as used by the JavaScript bindings.
The oxilite family
oxilite is an Oxigraph-compatible RDF database and SPARQL 1.1 engine that stores its data in SQLite, so it runs anywhere SQLite runs: in-process, on a system or vendor libsqlite3, on Cloudflare D1 and in Durable Objects. The same data can be queried with SPARQL and openCypher, reasoned over with RDFS / OWL, validated with SHACL and ShEx, and loaded from JSON-LD documents and Verifiable Credentials. Read the overview on oxilitedb.com and the full guide in the main README.
| Package | What it is for |
|---|---|
oxilite |
The store: a drop-in for oxigraph::store::Store, plus AsyncStore for D1 |
oxilite-core |
The sans-IO core: term encoding, schema, SPARQL → SQL compiler and planner |
oxilite-rusqlite |
In-process backend with a bundled SQLite (the default) |
oxilite-dylib |
Backend that loads your own libsqlite3 at runtime |
oxilite-d1 |
Cloudflare D1 backend for Rust Workers |
oxilite-cypher |
openCypher over the same data, OWL- and SHACL-aware |
oxilite-jsonld |
JSON-LD documents stored verbatim, one named graph each |
oxilite-vc |
Verifiable Credentials: stored under their id, indexed, queryable |
oxilite-reason |
OWL 2 RL materialization with reasonable |
oxilite-validate |
SHACL and ShEx validation with rudof |
oxilite-cli |
The oxilite command and a SPARQL endpoint like oxigraph serve |
@oxilite/node |
Node.js bindings, API of Oxigraph's JS package |
@oxilite/d1 |
Cloudflare D1 and Durable Objects from TypeScript (WebAssembly core) |
@oxilite/common |
RDF/JS terms and shared TypeScript types |
License
Dual-licensed under MIT or Apache-2.0, at your option, like Oxigraph.