TripleModel

Typed Pydantic models for RDF. Declare fields once, get correct triples in and out of pyoxigraph Store objects — no manual quad writes for every property.

Person(slug="alice", name="Alice")  →  (ex:alice, foaf:name, "Alice")  →  Person(...)

TripleModel is the mapping layer between Pydantic-shaped domain models and RDF triples: subject IRIs, XSD literals, nested resources, rdf:List, language tags, graph sync, and file parse/serialize. It is stateless (no ORM session); SparqlModel (sessions, SPARQL, ORM) builds on top — see the ecosystem guide.

0.12.0 is beta. Public API is frozen from 0.9 until 1.0 — see API stability, changelog, migration 0.11 (and 0.10 pyoxigraph). 0.12.0 is additive (no migration guide). See roadmap.

Install

pip install triplemodel

Requirements: Python 3.10+, Pydantic 2, pyoxigraph 0.5+.

Quick start

from triplemodel import TripleModel, rdf_field

FOAF = "http://xmlns.com/foaf/0.1/"

class Person(TripleModel):
    class Rdf:
        namespace = "http://example.org/people/"
        type_uri = f"{FOAF}Person"
        id_field = "slug"

    slug: str
    name: str = rdf_field(f"{FOAF}name")
    age: int | None = rdf_field(f"{FOAF}age", default=None)

alice = Person(slug="alice", name="Alice", age=30)
graph = alice.to_graph()

assert Person.from_graph(graph, alice.subject_uri()) == alice
print(alice.subject_uri())

http://example.org/people/alice

Unmapped fields are ignored on export/import — useful for computed or application-only data.

Features

list vs set

Use set for tags or duplicate predicates; use list when the graph should contain a real RDF list.

Full example

Language tags, RDF lists, and nested blank-node embeds:

from typing import Annotated

from triplemodel import TripleModel, rdf_field, sync_to_graph
from triplemodel.terms.lang import Lang, LangString
from triplemodel.vocab import DC, FOAF

class Address(TripleModel):
    class Rdf:
        namespace = "http://example.org/address/"
        type_uri = "http://example.org/Address"
        id_field = "slug"

    slug: str = "home"
    street: str = rdf_field("http://example.org/street")


class Person(TripleModel):
    class Rdf:
        namespace = "http://example.org/people/"
        type_uri = f"{FOAF}Person"
        id_field = "slug"
        embed = "bnode"
        prefixes = {"foaf": str(FOAF), "dc": str(DC)}

    slug: str
    title: LangString = rdf_field(f"{DC}title")
    nick: list[str] = rdf_field("foaf:nick", default_factory=list)
    address: Address | None = rdf_field("http://example.org/home", default=None)


person = Person(
    slug="alice",
    title=LangString("Alice's profile", "en"),
    nick=["Al", "Alice"],
    address=Address(street="1 Main St"),
)
graph = person.to_graph()

person.nick = ["Alice"]
sync_to_graph(person, graph, mode="replace")
again = Person.from_graph(graph, person.subject_uri())
print(again.nick)

['Alice']

Runnable version: examples/exit_criteria_03.py (same models; see also examples/doc/snippets/).

How mapping works

class Rdf — resource metadata

Override the subject per call with uri= when the IRI still lives under namespace:

graph = alice.to_graph(uri="http://example.org/people/alice")

Helpers: subject_base(), id_from_subject_uri().

Fields → predicates

name: str = rdf_field("foaf:name")  # with Rdf.prefixes

from typing import Annotated
from triplemodel import Predicate

title: Annotated[str, Predicate("http://purl.org/dc/terms/title")]
title_fr: Annotated[str, Predicate(f"{DC}title"), Lang("fr")]

Subclasses inherit a parent Rdf when the child does not define one. A child class Rdf: replaces the parent config entirely — never use an empty nested Rdf on a subclass.

Scalar → RDF (export)

Register custom types with register_literal_type and LiteralRegistry.

Updating an existing graph

Default to_graph() uses mode="add" — it only appends. To remove triples when fields are cleared, use sync modes:

from triplemodel import sync_to_graph

sync_to_graph(person, graph, mode="replace")  # replace all owned triples for this subject
sync_to_graph(person, graph, mode="patch")    # per-predicate replace; lighter touch

replace clears nested IRI children and list heads before re-export; patch updates predicates present in the model and clears empty fields (including on nested resources). See the updating graphs guide.

API overview

Instance & class methods

Common imports

from triplemodel import (
    TripleModel,
    rdf_field,
    ref_field,
    Predicate,
    IriId,
    GraphMode,
    sync_to_graph,
    models_to_graph,
    load_graph,
    load_models,
    load_models_from_graph,
    load_models_from_dataset,
    load_dataset,
    parse_into_dataset,
    model_to_dataset,
    models_to_dataset,
    get_graph_context,
    graph_to_model_dispatch,
    all_from_graph_dispatch,
    ask,
    apply_update,
    construct_models,
    select_models,
    load_sparql,
    open_sparql_graph,
    prepare_model_query,
    run_sparql,
    init_bindings_from_model,
    init_ns_from_model,
    graph_from_construct_result,
    merge_graphs,
    expand_curie,
    bind_namespaces,
    LangString,
    Lang,
    ResourceRef,
    OpaqueLiteral,
    RDF,
    XSD,
)

Full API: Read the Docs API reference.

More examples

Batch export

from triplemodel import Store
from triplemodel import models_to_graph

graph = models_to_graph([alice, bob])
models_to_graph([alice, bob], Graph())  # merge into existing graph

Encoded subject ids

bob = Person(slug="bob jones", name="Bob")
print(bob.subject_uri())

http://example.org/people/bob%20jones

Multiple tags on one predicate — use set[str] = rdf_field("foaf:topic", default_factory=set).

Runnable scripts: examples/exit_criteria_03.py, examples/readme_examples.py, examples/realworld/ (Nobel, DCAT, Wikidata, Schema.org), and examples/doc/snippets/.

TripleModel vs SparqlModel

Known limitations

• Union queries — from_dataset reads one named graph only; use Dataset.query for union semantics (see the datasets guide).
• BNode embed is experimental; prefer embed="iri" for stable linking.
• Collections — list[T] / set[T] require scalar T; list[TripleModel] and set[TripleModel] are not supported.
• Inverse predicates — import uses forward or inverse triples (forward wins on conflict); sync_to_graph in add, replace, or patch clears incoming inverse triples before writing forward predicates (including reassignment and dropped nested IRI/bnode children). Export writes forward predicates only.
• Discovery — all_from_graph() and dispatch discovery match subjects via forward owned predicates (and rdf:type / instance_of); resources reachable only through inverse triples are not discovered.
• Dispatch parse — parse(..., dispatch=True) loads every registered rdf:type (not only the class you call .parse on); type_uri= is ignored when dispatch=True.
• Skolemize — skolemize / de_skolemize on import or export mutate the entire shared Store, not only the resource being loaded or synced. sync_to_graph(..., mode="patch") runs skolemize after cleanup and export; replace / add skolemize via write_model_add before appending new triples.
• Remote SPARQL graph — open_sparql_graph and load_sparql raise NotImplementedError in 0.10.0; load remote data into a local Store (see SPARQL guide).
• BNode embed + fresh policy — with default blank_node_policy="fresh", replace / patch remove and re-export nested blank nodes on every sync even when the nested value is unchanged; use embed="iri" or blank_node_policy="stable" for stable identities.
• BNode subjects are skipped by all_from_graph() and by parse(..., dispatch=True) / all_from_graph_dispatch().
• Subclass dispatch — parse(..., dispatch=True) and all_from_graph_dispatch() resolve subjects via Rdf.resolve_subclass (RDFS closure when enabled); unregistered types are omitted without error.
• Default add mode does not remove stale triples — use sync_to_graph or mode="replace".
• sync_to_graph() defaults to replace when Rdf.graph_mode is "add" (unlike to_graph(), which defaults to add).

Details: user guides · RDF lists & lang.

Development

git clone https://github.com/eddiethedean/triplemodel.git && cd triplemodel
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,docs]"
make ci              # pytest, lint, docs (matches GitHub Actions)
make release-check   # before tagging: examples + twine check

CI: Python 3.10–3.13. Release process: RELEASING.md.

Documentation

License

MIT — see LICENSE.