Models and fields

SPARQLModel subclasses Pydantic v2 pydantic.BaseModel. Field types and constraints are validated on construction and when loading from the graph (hydration). For patterns and the validation stack, see Models and Pydantic validation.

ORM entity base class (SPARQLModel); use with SPARQLSession.

class sparqlmodel.model.SPARQLModelMetaclass(cls_name, bases, namespace, __pydantic_generic_metadata__=None, __pydantic_reset_parent_namespace__=True, _create_model_module=None, **kwargs)

Bases: ModelMetaclass

Metaclass enabling Model.field == value query expressions.

Return type:

type

class sparqlmodel.model.SPARQLModel(*, id=None)

Bases: TripleModel

ORM entity mapped to RDF; persist and query via SPARQLSession.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'str_strip_whitespace': False, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod get_prefixes()

Return namespace prefixes for this model (includes built-in RDF prefixes).

Return type:

dict[str, str]

classmethod iter_sparql_fields()

Yield (name, field_info, annotation) for mapped fields excluding id.

Return type:

list[tuple[str, FieldInfo, Any]]

classmethod get_relationship_fields()

Return relationship field definitions.

Return type:

list[tuple[str, FieldInfo, type[SPARQLModel]]]

classmethod get_scalar_fields()

Return scalar (non-relationship) field definitions.

Return type:

list[tuple[str, FieldInfo]]

ensure_id()

Ensure the instance has an IRI id.

Return type:

IRI

subject_uri(*, uri=None)

Return the RDF subject IRI for this instance (expanded when compact).

Return type:

str

model_dump_jsonld()

Serialize to a JSON-LD dict for APIs (cascade-aware ORM view).

For RDF files or HTTP bodies with all triples, use serialize(format="json-ld") (inherited from TripleModel) instead.

Return type:

dict[str, Any]

classmethod model_validate_jsonld(data)

Deserialize from a JSON-LD dict (ORM presentation layer).

For RDF files, use parse() (inherited from TripleModel) or import_graph().

Return type:

Self

ORM field and relationship definitions for SPARQLModel.

sparqlmodel.fields.Field(predicate, *, lang=None, inverse=None, literal_datatype=None, transitive=False, back_populates=None, **kwargs)

Map a model attribute to an RDF predicate.

Parameters:

• predicate (str) – Compact or absolute IRI (e.g. schema:name).

• lang (str | None) – Default language tag for string literals (Lang metadata).

• inverse (str | None) – Inverse predicate IRI for import-only triples.

• literal_datatype (str | None) – XSD datatype CURIE for typed literals.

• transitive (bool) – Expand multi-valued object URIs transitively on import.

• back_populates (Any) – BackPopulates, inverse_pair, or (Model, field) tuple.

• **kwargs (Any) – Additional arguments passed to pydantic.Field.

Return type:

Any

sparqlmodel.fields.Relationship(predicate, *, model=None, cascade=True, inverse=None, back_populates=None, **kwargs)

Map a model attribute to an RDF object relationship.

Parameters:

• predicate (str) – Compact or absolute IRI (e.g. schema:worksFor).

• model (type[Any] | None) – Related SPARQLModel class (inferred from annotation when omitted).

• cascade (bool) – When False, nested resources are not included in put/delete cascade.

• inverse (str | None) – Inverse predicate for import (not with ref_field).

• back_populates (Any) – Paired inverse field on another model (TripleModel 0.12+).

• **kwargs (Any) – Additional arguments passed to pydantic.Field.

Return type:

Any

class sparqlmodel.fields.SPARQLFieldMetadata(predicate, is_relationship=False, related_model=None, cascade=True)

Bases: object

Metadata attached to a SPARQL-mapped model field.

__init__(predicate, is_relationship=False, related_model=None, cascade=True)

sparqlmodel.fields.field_cardinality_for(field_info)

TripleModel cardinality for a mapped field.

Return type:

str

sparqlmodel.fields.get_field_metadata(field_info)

Extract SPARQL metadata from a Pydantic field info object.

Return type:

SPARQLFieldMetadata | None

sparqlmodel.fields.inverse_pair(model, field)

Shorthand for BackPopulates.

Pass a class or a string name (inverse_pair("Organization", "employees")) when the peer model is declared later in the same module.

Return type:

BackPopulates

sparqlmodel.fields.is_relationship_field(field_info, meta)

True when the field maps to object references or nested models.

Return type:

bool

sparqlmodel.fields.iter_relationship_values(value)

Normalize scalar or collection relationship values to a sequence.

Return type:

Sequence[object]

sparqlmodel.fields.predicate_uri_for_field(field_info, prefixes)

Expanded predicate IRI for a mapped field (TripleModel or SparqlModel metadata).

Return type:

str | None

sparqlmodel.fields.relationship_allows_iri(annotation)

True when the relationship annotation includes IRI (composition or reference).

Return type:

bool

sparqlmodel.fields.relationship_is_nullable(annotation)

True when a relationship annotation includes None (optional link).

Return type:

bool

sparqlmodel.fields.relationship_is_ref_link(field_info)

True when the field is a URI reference (ref_field), not embedded composition.

Return type:

bool

sparqlmodel.fields.resolve_related_model(field_name, annotation, metadata)

Resolve the related model class for a relationship field.

Return type:

type[Any]

IRI and namespace utilities.

sparqlmodel.types.is_compact_iri(value)

Return True if value is a prefix:local compact IRI (not a plain literal with a colon).

Return type:

bool

sparqlmodel.types.is_absolute_iri(value)

Return True if value is an absolute IRI string (http, https, or urn).

Return type:

bool

class sparqlmodel.types.IRI

Bases: str

RDF IRI identifier (compact or absolute).

expand(prefixes=None)

Expand a compact IRI (e.g. schema:Person) to an absolute IRI.

Return type:

str

compact(prefixes=None)

Return the most compact form using known prefixes.

Return type:

str

sparqlmodel.types.expand_iri(iri, prefixes=None)

Expand compact IRIs using prefix map.

Return type:

str

sparqlmodel.types.compact_iri(iri, prefixes=None)

Compact an absolute IRI when a known prefix matches.

Return type:

str

class sparqlmodel.types.NamespaceRegistry(prefixes=None)

Bases: object

Registry of namespace prefixes for a session or model.

__init__(prefixes=None)

bind(graph)

Bind prefixes to a TripleModel Store graph.

sparql_prefixes()

Return PREFIX declarations for SPARQL queries.

Return type:

str