Pydantic Schema Reference

Open inAnthropic

Pydantic support ships with the upcoming TerminusDB 12.1 server release together with an updated Python client. Until then, the interface described here is available on the client's pydantic branch.

Complete reference for the pydantic schema layer (terminusdb_client.schema.pydantic). For the guided walkthrough see Pydantic Schema Management; for the step-by-step tutorial see the Pydantic Quickstart.

Requires pip install "terminusdb[pydantic]" (pydantic v2 only, >=2.7,<3).

Classes and functions

NameKindPurpose
TerminusModelBaseModel subclassDeclares a Class schema document; instances serialise via _obj_to_dict
TerminusUnionTerminusModel subclassDeclares {"@type": "TaggedUnion"}; fields are the members
TerminusEnumstr, EnumDeclares {"@type": "Enum"}; optional _schema registration; str(member) returns the wire value
PydanticSchemaSchema subclassfrom_db rebuilds pydantic models; parse_document/import_objects materialise instances
UnfoldAnnotated markerEmits "@unfold": true on the property
ArrayAnnotated markerEmits {"@type": "Array"}; @dimensions from list nesting

Class attributes

AttributeEmitsNotes
_key@keyHashKey, LexicalKey, ValueHashKey, RandomKey (default), UuidV7Key
_subdocument = []@subdocumentEmbedded; key restricted to Random/ValueHash/UuidV7; mutually exclusive with _shared
_abstract = []@abstract
_base = "str"@baseId prefix override
_unfoldable = True@unfoldableReferences to this class always unfold; class-local, never inherited
_shared = True@sharedRegular document, cascade-deleted on last unreference; class-local; not auto-unfolded
_foreign = True{"@type": "Foreign"}Opaque cross-data-product IRI; class declares no fields
_metadata = {...}@metadatarender_as, order_by, …
_schema = schema—Registers the class into the Schema at definition time

Annotation mapping

AnnotationSchema property spec
str"xsd:string"
int"xsd:integer"
float"xsd:decimal"
bool"xsd:boolean"
dt.datetime"xsd:dateTime"
dt.date"xsd:date"
dt.time"xsd:time"
dt.timedelta"xsd:duration"
decimal.Decimal"xsd:decimal"
bytes"xsd:base64Binary"
dict"sys:JSON"
None / NoneType"sys:Unit"
Optional[X], X | None, Union[X, None]{"@type": "Optional", "@class": X}
List[X], list[X]{"@type": "List", "@class": X}
Set[X], set[X]{"@type": "Set", "@class": X}
MyModel, "MyModel", forward refs"MyModel" (class link)
MyEnum"MyEnum" (enum link)
Annotated[X, Unfold]spec + "@unfold": true
Annotated[list[X], Array]{"@type": "Array", "@class": X[, "@dimensions": n]}
Set[X] with Field(min_length=a, max_length=b){"@type": "Set", "@class": X, "@min_cardinality": a, "@max_cardinality": b} (equal bounds emit @cardinality)
woql_type NewTypes (gYear, IDRef, decimal, PositiveInteger, …)mapped XSD name

@unfold is placed inside complex wrappers when combined: Annotated[Optional[X], Unfold] → {"@type": "Optional", "@class": X, "@unfold": true}.

Rejected annotations

AnnotationResult
Union[A, B] (non-Optional)TypeError — use TerminusUnion
Literal[...]TypeError — use an Enum
frozensetTypeError — use Set/set
Optional[Set[X]], Optional[List[X]]TypeError — collections already permit zero elements
tuple, unmapped typesTypeError
class-level general @oneOfnot supported — TerminusUnion is the tagged-union surface
Table, sys:JSONDocument, @values docs, @language, context prefixesnot mapped

Instance API

MemberTypeBehaviour
obj._obj_to_dict()method→ (document_dict, references)
obj.to_document()methodpublic alias for _obj_to_dict
obj._embedded_rep()methodnested-doc, {"@id"} link, or {"@ref"} capture rep
obj._backend_idPrivateAttrserver-assigned IRI after load/insert-stamp
obj._custom_idPrivateAttruser-supplied id (verbatim under UuidV7Key)
obj._idpropertybackend id → custom id → None
obj._isinstance, obj._capturePrivateAttrclient serialisation contract
TerminusModel._stub(id)classmethodid-carrying instance with no fields (folded link)
TerminusModel.from_document(doc, registry)classmethodvalidated instance from a document dict
TerminusModel._to_dict()classmethodthe class's schema document
TerminusEnum._to_dict()classmethod{"@type": "Enum", "@id": name, "@value": [...]}

Model instances intentionally have no to_dict — that method means "schema object" to the client and would be rejected from instance graphs.

PydanticSchema API

MemberBehaviour
PydanticSchema(title=, description=, authors=, schema_ref=, base_ref=, metadata=)context emitted into the @context document; metadata becomes context @metadata
.add_obj(name, cls)register a class/enum
.to_dict()[context_doc, *class_docs] sorted by @id
.from_db(client, select=None)rebuild all (or selected) classes; topo-ordered @inherits; model_rebuild resolves forward refs; returns self
.parse_document(doc)document dict → validated instance (or ValueError for unknown @type)
.import_objects(docs)list/dict → parsed instances
.commit(client, commit_msg=, full_replace=)inherited from Schema
.diff(client, ignore_docs=False)→ list[str]; [] when in sync. Normalises @key:Random vs absent and @inherits string vs list

from_db loads enums as TerminusEnum, classes via create_model (inheritance honoured), and restores @properties docs faithfully — object-form docs come back as Field(title=, description=), string labels round-trip unchanged so diff stays clean. Set/List fields get default_factory defaults.

tdbpy CLI

Command / flagBehaviour
tdbpy sync --format pydanticwrites schema.py of TerminusModel/TerminusUnion/TerminusEnum classes; records model_backend in config.json
tdbpy sync (no flag)uses model_backend from config.json, default template
tdbpy commitcollects DocumentTemplate, TerminusModel, TerminusUnion and enum classes from schema.py; full_replace commit
tdbpy checkdiffs schema.py vs database schema — exit 0 in sync, 1 on drift, 2 when no schema module/classes found
tdbpy check --ignore-docs@documentation differences are tolerated

Instance document shapes

Wire valueParsed into
"Class/id" stringstub (_backend_id set, fields absent)
{"@type": "@id", "@id": "Class/id"}stub
{"@type": T, ...fields}nested TerminusModel (subdocument or unfolded doc)
{"@ref": cap}linked object via capture graph
xsd scalarpython scalar (datetime/date/time/timedelta round-trip)
enum member stringTerminusEnum member (serialised via member.value)
sys:Unit ([])None

Error catalogue

RaisedWhen
TypeErrorunsupported annotation (Union, Literal, frozenset, Optional over collections, unmapped types)
ValueError_shared + _subdocument together; _foreign class with fields; subdocument _key not Random/ValueHash/UuidV7; custom _id on keyed/subdocument class; parse_document on a type not in the schema
RecursionErrorsubdocument embedding (a superclass of) itself — mirrors DocumentTemplate
RuntimeErrorfrom_db on a malformed spec, missing parent class, or inheritance cycle
pydantic.ValidationErrorinstance data violating field types

Known limitations

  • client.get_document(id) cannot parse the multi-document JSONL returned when a class is @unfoldable — use get_all_documents/query_document for those classes (pre-existing client limitation).
  • @documentation round-trips through Field(title=), Field(description=), _label and __doc__; exotic doc shapes may drift — use tdbpy check --ignore-docs.
  • @key is emitted on every class (effective key), matching DocumentTemplate byte-for-byte; the engine repeats inherited keys on subclasses.

Was this helpful?