TripleModel

Start here

  • Installation
    • Requirements
    • PyPI
    • From source
    • Verify
  • Quickstart
    • Serialize to Turtle
    • Update an existing graph
  • Examples
    • Full walkthrough (exit_criteria_03.py)
    • README examples
    • Nested model with sync (foaf_person_02.py)
    • Real-world data (examples/realworld/)

User guide

  • User guides
  • Getting started
    • Install
    • Define a model
    • Export to a graph
    • Import from a graph
    • Module-level functions
    • File I/O
  • Mapping fields and subjects
    • Predicates with rdf_field
    • Predicates with Annotated
    • Subject IRIs
      • Override the subject per call
      • Full IRI as id (IriId)
    • Term conversion (scalars)
    • Inheriting class Rdf
    • Type checking on import
    • Duplicate objects on scalar fields
  • Multi-valued fields
    • Sets (unordered, unique)
    • URI references (set / list)
      • set[ResourceRef] / list[ResourceRef]
      • ref_field collections
    • set[TypedLiteral] — per-object XSD datatypes
    • Scalars vs collections
    • Sync and cleared fields
  • Updating graphs
    • Graph modes
    • Clearing a scalar field
    • When to use each mode
    • Patch and empty collections
    • Triple ownership (SparqlModel)
    • Nested resources
    • Skolemize and shared graphs
  • Nested models
    • IRI embedding (recommended)
    • Optional nested field
    • Blank node embedding (experimental)
    • Multiple parents, one graph
    • Full example
  • Namespaces and CURIEs
    • Declare prefixes on the model
    • CURIE expansion
    • Turtle output
    • Manual bind on an existing graph
    • Vocabulary shortcuts
  • Custom literals and types
    • Built-in support
    • Register a custom type
    • Enums
  • Working with graphs
    • Batch export
    • Batch import
    • File helpers
    • Merge graphs
    • Graph helpers
    • Low-level triple access
    • Serialize for debugging
    • Skolemize and shared graphs
    • Related guides
  • RDF lists and language-tagged literals
    • list[T] → rdf:List
    • set[T] → multiple objects
    • Language tags
      • LangString
      • Annotated[str, Lang("en")]
      • MultiLangString
      • Helpers and MultiLangString
    • Related
  • File I/O (parse and serialize)
    • Serialize to a string or file
    • Parse from a string, file, or URL
      • Parse flags
      • Canonical N-Triples
      • URL fetch security
    • Base URI for relative IRIs
    • JSON-LD context
    • Subclass dispatch
    • Import options on class methods
    • Inverse predicates
      • Paired fields (back_populates)
    • Multi-class load (one parse)
    • Module helpers
  • Real-world patterns (0.4.1)
    • One parse, many model classes
    • Wikidata-style typing (instance_of)
    • URI foreign keys (ref_field)
    • XSD partial dates (gYear)
    • Mapping validation
  • Datasets and named graphs
    • Configure a named graph
      • Instance override
    • Export and import
    • Multiple classes, multiple graphs
    • Subclass dispatch on datasets
    • Default graph vs union
    • Nested models
    • Migration from rdflib ConjunctiveGraph
    • Helpers
  • SPARQL and remote endpoints
    • When to use which helper
    • CONSTRUCT on an in-memory graph
    • Remote data (pattern)
    • SELECT projection
    • Dataset union and named graphs
    • ASK
    • SPARQL UPDATE
    • Prepared queries and bindings
    • Security
  • Graph algorithms and RDFS
    • When to use which helper
    • Graph comparison
    • Concise bounded description (CBD)
    • RDFS subclass dispatch
    • Ontology hints (OntologyRegistry)
    • Batch reference hydration
    • Transitive import (optional)
    • Vocabulary registry
    • Safe graph merge
    • Catalog patterns (cookbook)
    • OWL/RDFS codegen (0.8, experimental)
  • Stores, scale, and strict import
    • Predicate-map caching
    • Strict import
    • Chunked import
    • Streaming file load
    • Store helpers
    • Bulk load, backup, and optimize
    • Benchmark
    • Plugin hooks
    • Codegen (experimental)

Cookbook

  • Cookbook
    • Formats and files
    • SPARQL and Fuseki
    • Named graphs (Dataset)
    • Persistent stores
    • Scale and strict import
    • Custom plugins (literals and resolvers)
    • Real-world datasets
    • Experimental codegen

API reference

  • API reference
    • Store
    • canonicalize_quads()
    • Lang
      • Lang.__init__()
      • Lang.direction
      • Lang.code
    • all_from_dataset()
    • all_from_dataset_dispatch()
    • all_from_graph_dispatch()
    • dump_dataset()
    • dump_graph()
    • dump_model()
    • get_graph_context()
    • graph_to_model_dispatch()
    • graph_to_model_dispatch_from_dataset()
    • graph_to_model_from_dataset()
    • graph_to_models_from_dataset()
    • infer_format()
    • iter_model_quads()
    • is_quad_format()
    • load_dataset()
    • load_graph()
    • load_models()
    • load_models_from_dataset()
    • load_models_from_graph()
    • load_models_streaming()
    • open_graph()
    • parse_into_store_graph()
    • model_to_dataset()
    • models_to_dataset()
    • parse_into_dataset()
    • parse_into_graph()
    • ref_field()
    • parse_url_into_dataset()
    • parse_url_into_graph()
    • quads_in_context()
    • resolve_graph_iri()
    • resolve_model_class()
    • LangString
      • LangString.__init__()
      • LangString.direction
      • LangString.lang
      • LangString.value
    • MultiLangString
      • MultiLangString.__init__()
      • MultiLangString.from_mapping()
      • MultiLangString.get()
      • MultiLangString.values()
      • MultiLangString.by_lang
    • LiteralRegistry
      • LiteralRegistry.__init__()
      • LiteralRegistry.converter_for_datatype()
      • LiteralRegistry.converter_for_type()
      • LiteralRegistry.literal_to_python()
      • LiteralRegistry.python_to_literal()
      • LiteralRegistry.register_literal_type()
    • OpaqueLiteral
      • OpaqueLiteral.__init__()
      • OpaqueLiteral.datatype
      • OpaqueLiteral.from_literal()
      • OpaqueLiteral.to_literal()
      • OpaqueLiteral.value
    • TypedLiteral
      • TypedLiteral.__init__()
      • TypedLiteral.datatype
      • TypedLiteral.from_literal()
      • TypedLiteral.to_literal()
      • TypedLiteral.value
    • OntologyRegistry
      • OntologyRegistry.__init__()
      • OntologyRegistry.from_graph()
      • OntologyRegistry.from_ttl()
      • OntologyRegistry.inverse_of()
      • OntologyRegistry.load_graph()
      • OntologyRegistry.register_inverse()
      • OntologyRegistry.register_subclasses()
      • OntologyRegistry.subtypes_of()
    • apply_hints_to_model()
    • VocabularyRegistry
      • VocabularyRegistry.__init__()
      • VocabularyRegistry.bind_vocab()
      • VocabularyRegistry.from_registered()
      • VocabularyRegistry.model_for_subject()
      • VocabularyRegistry.model_for_type_uri()
      • VocabularyRegistry.register()
      • VocabularyRegistry.type_uri_to_class
      • VocabularyRegistry.prefix_to_uri
    • ResourceRef
      • ResourceRef.__init__()
      • ResourceRef.iri
    • RdfResource
      • RdfResource.__init__()
    • TripleModel
      • TripleModel.all_from_dataset()
      • TripleModel.all_from_graph()
      • TripleModel.ask_sparql()
      • TripleModel.cbd()
      • TripleModel.construct_from_sparql()
      • TripleModel.from_dataset()
      • TripleModel.from_graph()
      • TripleModel.load_sparql()
      • TripleModel.model_config
      • TripleModel.parse()
      • TripleModel.parse_file()
      • TripleModel.parse_url()
      • TripleModel.rdf_config()
      • TripleModel.select_from_sparql()
      • TripleModel.serialize()
      • TripleModel.subject_uri()
      • TripleModel.sync_to_dataset()
      • TripleModel.sync_to_graph()
      • TripleModel.to_dataset()
      • TripleModel.to_graph()
      • TripleModel.to_triples()
    • bind_namespaces()
    • expand_curie()
    • freeze_prefixes()
    • graph_set()
    • graph_to_model()
    • graph_to_models()
    • graph_store_session()
    • graph_value()
    • backup_store()
    • bulk_load_into_graph()
    • clear_named_graph()
    • destroy_store()
    • dump_store()
    • ensure_named_graph()
    • iter_quads_for_pattern()
    • list_named_graphs()
    • load_store()
    • optimize_store()
    • parse_query_results()
    • remove_named_graph()
    • iter_graph_to_models()
    • id_from_subject_uri()
    • merge_graphs()
    • model_to_graph()
    • model_to_triples()
    • models_to_graph()
    • objects_for_field()
    • rdf_field()
    • register_literal_type()
    • register_rdf_resource()
    • store_commit()
    • store_flush()
    • store_rollback()
    • subject_base()
    • sync_to_dataset()
    • sync_to_graph()
    • GraphDiff
      • GraphDiff.__init__()
      • GraphDiff.equal
      • GraphDiff.only_in_first
      • GraphDiff.only_in_second
    • apply_update()
    • ask()
    • cbd_graph()
    • cbd_model()
    • construct_models()
    • detect_query_form()
    • graph_diff()
    • graph_from_construct_result()
    • graphs_equal()
    • hydrate_refs()
    • init_bindings_from_model()
    • init_ns_from_model()
    • load_sparql()
    • model_diff()
    • model_join()
    • open_sparql_graph()
    • prepare_model_query()
    • resolve_model_class_with_rdfs()
    • run_sparql()
    • select_models()
    • subject_type_closure()
    • subclass_uris()
    • transitive_objects()
    • transitive_subjects()
    • Module reference
      • triplemodel.config
        • RdfConfig
        • SubjectUriInstance
        • effective_graph_mode()
        • freeze_prefixes()
        • get_graph_context()
        • get_rdf_config()
        • id_from_subject_uri()
        • resolve_graph_iri()
        • subject_base()
      • triplemodel.io
        • all_from_dataset()
        • all_from_dataset_dispatch()
        • all_from_graph_dispatch()
        • GraphDiff
        • cbd_graph()
        • cbd_model()
        • discover_subject_uris()
        • graph_diff()
        • graphs_equal()
        • hydrate_refs()
        • model_diff()
        • model_join()
        • resolve_model_class_with_rdfs()
        • subject_type_closure()
        • subclass_uris()
        • transitive_objects()
        • transitive_subjects()
        • discover_subjects_by_instance_of()
        • dump_dataset()
        • dump_graph()
        • dump_model()
        • fetch_url()
        • get_graph_context()
        • graph_to_model_dispatch()
        • graph_to_model_dispatch_from_dataset()
        • graph_to_model_from_dataset()
        • graph_to_models_from_dataset()
        • infer_format()
        • is_quad_format()
        • iter_model_quads()
        • load_dataset()
        • load_graph()
        • backup_store()
        • bulk_load_into_graph()
        • clear_named_graph()
        • destroy_store()
        • dump_store()
        • ensure_named_graph()
        • graph_store_session()
        • iter_quads_for_pattern()
        • list_named_graphs()
        • load_store()
        • optimize_store()
        • parse_query_results()
        • remove_named_graph()
        • iter_graph_to_models()
        • load_models()
        • load_models_from_dataset()
        • load_models_from_graph()
        • load_models_streaming()
        • open_graph()
        • parse_into_store_graph()
        • store_commit()
        • store_flush()
        • store_rollback()
        • model_to_dataset()
        • models_to_dataset()
        • parse_into_dataset()
        • parse_into_graph()
        • parse_url_into_dataset()
        • parse_url_into_graph()
        • quads_in_context()
        • sync_to_dataset()
        • graph_set()
        • graph_set_many()
        • graph_to_model()
        • graph_to_models()
        • graph_value()
        • import_field_value()
        • merge_graphs()
        • model_to_graph()
        • model_to_triples()
        • models_to_graph()
        • objects_for_field()
        • sync_to_graph()
        • write_model_add()
      • Dataset I/O
        • parse_into_dataset()
        • parse_url_into_dataset()
        • load_dataset()
        • dump_dataset()
        • model_to_dataset()
        • models_to_dataset()
        • sync_to_dataset()
        • graph_to_model_from_dataset()
        • graph_to_models_from_dataset()
        • all_from_dataset()
        • load_models_from_dataset()
        • quads_in_context()
        • iter_model_quads()
        • Configuration
      • triplemodel.io.sparql
        • PreparedModelQuery
        • apply_update()
        • ask()
        • construct_models()
        • detect_query_form()
        • graph_from_construct_result()
        • init_bindings_from_model()
        • init_ns_from_model()
        • load_sparql()
        • open_sparql_graph()
        • prepare_model_query()
        • run_sparql()
        • select_models()
      • Store helpers
        • backup_store()
        • bulk_load_into_graph()
        • cleanup_ephemeral_store_path()
        • clear_named_graph()
        • coerce_store_name()
        • destroy_store()
        • dump_store()
        • ensure_named_graph()
        • graph_store_session()
        • iter_quads_for_pattern()
        • list_named_graphs()
        • load_store()
        • open_graph()
        • optimize_store()
        • remove_named_graph()
        • store_commit()
        • store_flush()
        • store_rollback()
        • Store operations
        • SPARQL results I/O
        • Canonicalize (in-memory)
      • Plugin hooks
        • register_parser()
        • register_predicate_resolver()
        • register_serializer()
        • register_store()
      • Codegen (experimental)
        • Limitations
      • triplemodel.io.sync
        • clear_nested_iri_children()
        • clear_stale_nested_iri_children()
        • predicates_to_patch()
        • remove_owned_triples()
        • sync_to_graph()
      • triplemodel.fields
        • BackPopulates
        • FieldPredicateResolver
        • IriId
        • InverseOf
        • Predicate
        • Transitive
        • back_populates_for_field()
        • inverse_pair()
        • inverse_for_field()
        • models_via_back_populates()
        • subjects_via_back_populates()
        • transitive_for_field()
        • annotation_has_iri_id()
        • id_field_is_iri_id()
        • owned_predicates()
        • predicate_for_field()
        • predicate_from_annotation()
        • rdf_field()
        • ref_field()
        • resolve_field_predicate()
      • triplemodel.namespaces
        • expand_curie()
        • resolve_predicate()
        • bind_namespaces()
      • triplemodel.embed
        • BnodeEmbedStrategy
        • IriEmbedStrategy
        • add_nested_to_graph()
        • export_nested_triples()
        • get_embed_strategy()
        • import_nested_value()
      • triplemodel.terms.registry
        • LiteralRegistry
        • register_literal_type()
        • converter_for_type()
        • python_to_literal()
        • literal_to_python()
      • triplemodel.io.ops
        • merge_graphs()
        • graph_value()
        • graph_set()
        • graph_set_many()
        • objects_for_field()
      • triplemodel.io.compare
        • GraphDiff
        • graph_diff()
        • graphs_equal()
        • model_diff()
      • triplemodel.io.cbd
        • cbd_graph()
        • cbd_model()
      • triplemodel.io.rdfs
        • resolve_model_class_with_rdfs()
        • subject_type_closure()
        • subclass_uris()
        • transitive_objects()
        • transitive_subjects()
      • triplemodel.io.hydrate
        • hydrate_refs()
        • model_join()
      • triplemodel.vocab_registry
        • VocabularyRegistry
      • triplemodel.metadata.cardinality
        • field_annotation()
        • unwrap_annotation()
        • element_type()
        • raise_if_inverse_collection()
        • raise_if_unhashable_ref_set()
        • raise_if_nested_collection()
        • is_triple_model_type()
        • field_cardinality()
        • union_member_types()
        • scalar_python_type()
        • ref_collection_element_type()
        • nested_model_type()
      • triplemodel.fields.metadata
        • Predicate
        • InverseOf
        • IriId
        • Transitive
        • rdf_field()
        • predicate_for_field()
        • inverse_for_field()
        • inverse_from_annotation()
        • predicate_from_annotation()
        • annotation_has_iri_id()
        • lang_from_annotation()
        • literal_datatype_for_field()
        • lang_for_field()
        • ref_field()
        • transitive_for_field()
        • ref_link_for_field()
        • id_field_is_iri_id()
      • triplemodel.terms.lang
        • normalize_lang_tag()
        • Lang
        • LangString
        • MultiLangString
      • triplemodel.terms.typed_literal
        • TypedLiteral
      • triplemodel.ontology_registry
        • OntologyRegistry
        • apply_hints_to_model()
      • triplemodel.protocols
        • register_rdf_resource()
        • iter_registered_type_uris()
        • model_class_for_type_uri()
        • iter_registered_model_classes()
        • iter_model_resource_classes()
        • resolve_model_class()
        • is_rdf_resource_class()
        • RdfResource
        • PredicateResolver
        • LiteralRegistry
        • EmbedStrategy
        • GraphWriteMode
      • triplemodel.vocab

Project

  • Changelog
  • Changelog
    • [Unreleased]
    • [0.12.0] - 2026-05-22
      • Added
      • Fixed
      • Changed
    • [0.11.0] - 2026-05-20
      • Breaking
      • Added (pyoxigraph surface)
      • Removed
    • [0.10.1] - 2026-05-20
      • Fixed
      • Changed
    • [0.10.0] - 2026-05-19
      • Breaking
      • Added
      • Fixed
      • Changed
    • [0.9.0] - 2026-05-18
      • Added
      • Changed
      • Fixed
    • [0.8.0] - 2026-05-18
      • Added
      • Changed
      • Fixed
    • [0.7.0] - 2026-05-18
      • Added
      • Changed
      • Fixed
      • Deferred
    • [0.6.0] - 2026-05-18
      • Added
      • Fixed
      • Changed
    • [0.5.0] - 2026-05-17
      • Added
      • Fixed
      • Changed
    • [0.4.1] - 2026-05-16
      • Added
      • Changed
      • Fixed
    • [0.4.0] - 2026-05-17
      • Fixed
      • Added
      • Changed
    • [0.3.0] - 2026-05-17
      • Added
      • Changed
      • Fixed
    • [0.2.0] - 2026-05-17
      • Added
      • Changed
      • Fixed
      • Removed
      • Documentation
    • [0.1.0] - 2026-05-17
      • Added
      • Fixed
  • API stability (0.9+)
    • 0.10.0 engine exception
    • 0.11.0 rdflib cleanup exception
    • 0.12.0 additive release
    • Stable surface
    • Semipublic modules
    • Integrator tier (SparqlModel / Option A)
  • Migrating to TripleModel 0.10.0 (pyoxigraph)
    • Dependency
    • Replace rdflib.Graph with triplemodel.Store
    • Removed APIs
    • SparqlModel
    • Literal typing
  • Migrating to TripleModel 0.11.0
    • Dependency
    • SHACL validation removed
    • Renamed kwargs
    • bind_namespaces strategy
    • Additive store and SPARQL helpers (same 0.11.0 release)
    • Related
  • Compatibility matrix
    • Supported versions
    • Optional extras
    • CI
    • Type checking
  • TripleModel roadmap
    • SparqlModel integration milestones
    • Oxigraph / pyoxigraph coverage matrix
    • 0.1.0 — Foundation
    • 0.2.0 — Terms, fields, and namespaces
    • 0.3.0 — Literals, blanks, lists, and identity
    • 0.4.0 — Parsing, serialization, and validation
    • 0.4.1 — Real-world ergonomics
    • 0.5.0 — Datasets and named graphs
    • 0.6.0 — SPARQL and remote graphs
    • 0.7.0 — Graph algorithms and RDFS ✅
    • 0.8.0 — Stores, scale, and ergonomics ✅
    • 0.10.0 — pyoxigraph engine
    • 0.11.0 — rdflib removal ✅
    • 0.11.0 — pyoxigraph surface completion ✅
      • Store operations (disk / scale)
      • Parse / serialize (I/O)
      • SPARQL results
      • Terms / RDF 1.2
      • Explicitly deferred in 0.11.x
    • 0.9.0 — rdflib parity audit and API freeze (historical)
    • 1.0.0 — Stable release
    • Explicitly out of scope (even pre-1.0)
      • rdflib areas TripleModel does not wrap
      • Application features owned by SparqlModel (not TripleModel)
    • Ecosystem summary
    • How to influence the roadmap
    • Version summary
  • TripleModel project plan
    • Current status (0.12.0)
    • Mission
    • Stack and dependency rule
    • Design principles
    • Core dependencies
    • What TripleModel builds (in scope)
    • What TripleModel does not build (out of scope)
    • Real-world integration lessons (0.4 evaluation)
    • SparqlModel integration strategy
      • Integration gates (historical + next)
      • API convergence (canonical: Option A)
      • Integrator requirements (SM-6 / SparqlModel 0.4)
      • Contract tests (future)
    • Release philosophy
    • Priority order (when trade-offs arise)
    • Documentation map
    • Success metrics
  • TripleModel and SparqlModel — separation of responsibilities
    • triplemodel — the mapping layer
      • Owns
      • Does not own
      • Typical callers
      • API shape
    • SparqlModel — the ORM layer
      • Owns
      • Does not own (delegates to TripleModel, once integrated)
      • Typical callers
      • API shape
    • Decision guide
    • Triple ownership (0.2+)
    • Public API convergence (target)
    • SparqlModel integration status
    • Optional extras (unchanged split)
    • Summary
  • SparqlModel ecosystem guide (for SparqlModel development)
    • Stack
    • Division of labour
    • Dependency
    • Stable TripleModel entry points (integrator tier)
    • Module plan (SparqlModel)
    • Integration milestones (SparqlModel versions)
    • SparqlModel 0.4 exit criteria (Option A)
    • Where to fix bugs
    • PR boundary (quick)
  • Contributing
    • Development setup
    • Checks (match CI)
    • Documentation
      • Runnable examples in docs
    • Pull requests
  • Releasing
  • Releasing TripleModel
    • 0.12.0 (repo)
    • 0.11.0 (repo)
    • 0.10.1 patch (repo)
    • 0.10.0 release readiness (repo)
    • Historical releases
TripleModel
  • Overview: module code

All modules for which code is available

  • triplemodel.codegen.cli
  • triplemodel.codegen.emit
  • triplemodel.codegen.parse
  • triplemodel.config.rdf_config
  • triplemodel.embed.strategies
  • triplemodel.fields.back_populates
  • triplemodel.fields.metadata
  • triplemodel.fields.resolver
  • triplemodel.fields.resource_ref
  • triplemodel.io.cbd
  • triplemodel.io.compare
  • triplemodel.io.dataset
  • triplemodel.io.discovery
  • triplemodel.io.dispatch
  • triplemodel.io.export
  • triplemodel.io.files
  • triplemodel.io.graph
  • triplemodel.io.hydrate
  • triplemodel.io.import_
  • triplemodel.io.ops
  • triplemodel.io.rdfs
  • triplemodel.io.sparql
  • triplemodel.io.stores
  • triplemodel.io.sync
    • triplemodel.io.sync.modes
    • triplemodel.io.sync.nested_cleanup
    • triplemodel.io.sync.predicate_ops
  • triplemodel.metadata.cardinality
  • triplemodel.model
  • triplemodel.namespaces
  • triplemodel.ontology_registry
  • triplemodel.plugins
  • triplemodel.protocols
  • triplemodel.store.canonicalize
  • triplemodel.store.graph
  • triplemodel.store.ops
  • triplemodel.store.query_results
  • triplemodel.terms.lang
  • triplemodel.terms.opaque
  • triplemodel.terms.registry
  • triplemodel.terms.typed_literal
  • triplemodel.vocab_registry
  • typing

© Copyright 2026, TripleModel contributors.

Built with Sphinx using a theme provided by Read the Docs.