PurRDF

The RDF 1.2 toolkit with a purr: primitives, codecs, SPARQL, SHACL, ShEx, and graph transport.

One RDF engine. One behavior. Every language.

Why does this exist?

RDF tooling fragments along two axes.

Across languages: every ecosystem has its own parser, with its own bugs, its own corner-case interpretations, and its own subset of the spec. Move a graph from a Rust service to a Python pipeline to a browser and you have silently changed what the data means three times.

Across time: RDF 1.2 — triple terms, reifiers, base-direction literals — is where the standard is going, and almost no incumbent library carries it.

PurRDF exists so that a graph is the same graph everywhere. It is a from-scratch, dependency-light Rust core — parser to SPARQL engine to SHACL validator to binary transport — carried verbatim into Python, WebAssembly/JavaScript, and C. There are deliberately no Cargo feature flags anywhere in the workspace (CI enforces this): a data carrier must not have optional behavior, so every consumer gets the same byte-identical semantics.

PurRDF is the data backbone of the GMEOW stack and the reference home of the GTS graph-transport engine, but it assumes nothing about your ontology or application.

What's inside

• RDF 1.2 primitives — an immutable, value-interned dataset IR (TermId space, string arena, copy-on-write mutation), with triple terms in object position, reifier/annotation side-tables, and base-direction literals (rdf:dirLangString).
• Native codecs — first-party parsers/serializers for Turtle, TriG, N-Triples, N-Quads, RDF/XML, JSON-LD (star), and YAML-LD; byte-deterministic output.
• Canonicalization — W3C RDFC-1.0 dataset canonicalization, tested against the W3C fixture suite.
• SPARQL 1.1/1.2 — native parser → algebra → multiset evaluator over the interned IR (property paths, aggregates, EXISTS decorrelation, cost-based BGP planning, injectable SERVICE federation), gated by the W3C SPARQL 1.1 conformance harness. Results in SPARQL JSON/XML/CSV/TSV.
• SHACL validation — a native validator with the complete SHACL Core feature set (all constraint components, full property paths, qualified value shapes, property pairs), SHACL-SPARQL constraints/targets on the native engine, and scoped SHACL 1.2 draft support for reifier shapes — 114/120 passing on the vendored W3C test suite (the 6 ledgered are custom-component and pre-binding-semantics gaps).
• ShEx 2.1 — a from-scratch ShExC + ShExJ schema layer and validator gated against the official shexTest suite: 1,051/1,051 attempted validation tests, zero expected-failures (imports/semantic-actions staged next), 99/99 negative syntax, 14/14 negative structure. See docs/CONFORMANCE.md.
• GTS graph transport — a single-file, content-addressed, append-only container for RDF 1.2 graphs and the binaries they reference: BLAKE3-chained CBOR segments, deterministic fold, COSE signing/encryption, pure-Rust crypto (wasm-friendly). Spec in docs/GTS-SPEC.md, frozen cross-language conformance vectors in vectors/.
• Slices, mappings, and provenance — a manifest-based slice catalog with content-addressed artifact IDs, an explicit RDF↔GTS loss ledger (generated/rdf-loss-matrix.json), SSSOM mapping TSV support, and an FnO function-catalog codec.
• Zero-dependency foundations — purrdf-iri (RFC 3987/3986) and purrdf-xsd (XSD 1.1 value space) have no runtime dependencies at all; purrdf-events (the object-safe ingestion seam) has none either.

Quickstart

Rust

cargo add purrdf

use purrdf::{parse_dataset, serialize_dataset, RdfDatasetBuilder, RdfLiteral, SerializeGraph};

// Build a dataset in interned TermId space.
let mut b = RdfDatasetBuilder::new();
let alice = b.intern_iri("https://example.org/alice");
let knows = b.intern_iri("http://xmlns.com/foaf/0.1/knows");
let bob = b.intern_iri("https://example.org/bob");
let name = b.intern_iri("http://xmlns.com/foaf/0.1/name");
let hi = b.intern_literal(RdfLiteral::simple("Alice"));
b.push_quad(alice, knows, bob, None);
b.push_quad(alice, name, hi, None);
let ds = b.freeze().expect("freeze");

// Serialize to any native codec and parse back, losslessly.
let ttl = serialize_dataset(&ds, "text/turtle", SerializeGraph::Dataset).unwrap();
let back = parse_dataset(&ttl, "text/turtle", None).unwrap();
assert_eq!(back.quad_count(), 2);

Python

pip install purrdf

import purrdf

quads = purrdf.parse(
    '<https://example.org/alice> <http://xmlns.com/foaf/0.1/name> "Alice" .',
    purrdf.RdfFormat.TURTLE,
)

from purrdf_native import shacl, shex

report = shacl.validate(shapes_ttl=my_shapes, data_nt=my_data)
print(report["conforms"])

result = shex.validate(my_schema_shexc, my_data_ttl,
                       [("https://example.org/alice", "https://example.org/PersonShape")])
print(result["conforms"])

The Python package also ships an rdflib compatibility layer (from purrdf.compat.rdflib import Graph) and GTS relational exports (gts_to_sqlite, gts_to_duckdb, gts_to_parquet).

For a literal, zero-change import rdflib, install the opt-in extra:

pip install purrdf[rdflib]

This pulls in the separate purrdf-rdflib distribution, whose top-level rdflib package re-exports the compat surface, so existing third-party code doing import rdflib / from rdflib.namespace import RDF transparently runs on purrdf. Caveat: that shadow claims the rdflib import name and must never be installed alongside the genuine rdflib — the two cannot co-inhabit one environment. It is a separate distribution (never bundled into the main purrdf wheel) precisely so environments that need the real rdflib simply omit it.

JavaScript / WebAssembly

An RDF/JS-shaped API (DataFactory / Dataset / Stream) over the same engine, including the RDF 1.2 features no incumbent RDF/JS library carries — quoted triple terms and base-direction literals:

import { ready, DataFactory, Dataset } from "@blackcatinformatics/purrdf";

await ready(); // one-time async wasm instantiation

const f = new DataFactory();
const rtl = f.directionalLiteral("مرحبا", "ar", "rtl");

const ds = new Dataset();
ds.add(f.quad(f.namedNode("https://ex/s"), f.namedNode("https://ex/says"), rtl));

const nq = ds.serialize("nquads");           // directions survive the round-trip
const reparsed = Dataset.parse(nq, "nquads");

See crates/rdf-wasm (make wasm-pkg builds the ESM package).

C

libpurrdf (crates/rdf-capi) exposes parse, serialize, pattern iteration, copy-on-write mutation, SPARQL, and GTS round-trips behind a panic-safe C ABI with a committed header (include/purrdf.h) that CI checks for drift. Built with cargo-c: make capi-build.

Crate map

Fast by measurement, not by assertion

The IR keeps every term once in a string arena addressed by copyable NonZeroU32 ids, hashes with fixed-key ahash everywhere hot, and freezes datasets into Box<[QuadRow]> tables with lazy ordinal permutation indexes (~4 bytes/quad per axis). Performance claims are backed by criterion benchmarks rather than adjectives — crates/rdf-core/benches/ir_layout.rs measures AoS vs. SoA vs. predicate-adjacency layouts (allocation counts, high-water mark, end-to-end latency), and the shipped layout is whichever wins. Run them with make bench.

There is also a report-only Python harness that times the native-backed purrdf.compat.rdflib drop-in against the real rdflib on parse, serialize, SPARQL, and triple-pattern iteration over a deterministic example.org corpus (make bench-python). Methodology, how to run, and a representative (host-dependent) results table live in docs/BENCHMARKS.md. Numbers vary by host — reproduce locally rather than trusting a fixed multiplier.

Conformance

Every engine is gated by its official test suite, vendored and frozen in-repo — full scoreboard and how-to-run in docs/CONFORMANCE.md:

Development

make metadata   # regenerate + verify generated artifacts
make check      # fmt, build, tests, hygiene gates
make bench      # criterion benchmarks

Releases are tag-driven with OIDC trusted publishing (crates.io and PyPI), with build-provenance attestations and SPDX SBOMs — see docs/RELEASE.md.

Versioning & MSRV

Pre-1.0 semver policy. While the version is 0.x, a minor bump (0.x → 0.(x+1)) may include breaking API changes; a patch bump (0.x.y → 0.x.(y+1)) is bugfix-only and API-compatible. All three published surfaces — the crates.io crate suite, the PyPI purrdf package, and the npm @blackcatinformatics/purrdf package — share one workspace version and are released in lockstep. That coherence is enforced in CI: a version-coherence check fails the build if the three version sources disagree.

MSRV policy. The supported minimum Rust is rust-version in the root Cargo.toml (currently 1.96), pinned to the stable toolchain (nightly-free) and enforced by a dedicated CI MSRV job. Raising the MSRV is a notable change recorded in the changelog and, pre-1.0, rides a minor bump. The README MSRV badge is maintained by hand and must be bumped together with rust-version.

The GMEOW family

PurRDF is the library layer of a small family of linked-data projects:

• gmeow-ontology — the GMEOW reasoning-centric super-vocabulary and its publishing toolchain (PurRDF's primary consumer).
• gmeow-gts — the GTS specification and its multi-language engines; PurRDF hosts the Rust engine.

Extraction history and source commits: PROVENANCE.md. Brand assets and usage: docs/BRAND.md.

License

Licensed under either of Apache License 2.0 or MIT license at your option, as described in LICENSING.md.

If you use PurRDF in research, please cite it — see CITATION.cff.