Self-describing JSON

didactic.api.schema_uri 

schema_uri(cls: type[Model]) -> str

Return the canonical schema URI for a Model class.

PARAMETER DESCRIPTION
cls

A Model subclass.

TYPE: type[Model]

RETURNS DESCRIPTION
str

"didactic://v1/<fingerprint>" where <fingerprint> is the Model's structural fingerprint.

didactic.api.embed_schema_uri 

embed_schema_uri(instance: Model) -> JsonObject

Return the JSON-shape dump of instance with a $schema URI prepended.

PARAMETER DESCRIPTION
instance

A Model instance.

TYPE: Model

RETURNS DESCRIPTION
dict

The JSON-safe dump dict, with "$schema" set to the Model's canonical URI as the first key.
Notes

Routes through model_dump_json (not the bare model_dump) so any nested tuple[Embed[T], ...] or dict[str, Embed[T]] fields get the JSON-safe walk; the returned dict is always serialisable with json.dumps.

A consumer that knows how to resolve didactic://v1/<fp> URIs can fetch the Theory by fingerprint and validate the payload without knowing the original Python class.

didactic.api.FingerprintRegistry 

FingerprintRegistry()

An in-memory mapping of structural fingerprint to Model class.

Use as the lookup side of a self-describing JSON pipeline: register every Model your application understands, then validate_with_uri_lookup can resolve an unknown payload's $schema URI back to a class.

Examples:

>>> import didactic.api as dx
>>> class User(dx.Model):
...     id: str
>>>
>>> reg = dx.FingerprintRegistry()
>>> reg.register(User)
>>>
>>> u = User(id="u1")
>>> payload = dx.embed_schema_uri(u)
>>> back = dx.validate_with_uri_lookup(payload, reg)
>>> back == u
True

register 

register(cls: type[M]) -> type[M]

Register cls under its structural fingerprint.

lookup 

lookup(uri: str) -> type[Model] | None

Resolve a didactic://v1/<fp> URI to a registered class.

didactic.api.validate_with_uri_lookup 

validate_with_uri_lookup(
    payload: JsonObject, registry: FingerprintRegistry
) -> Model

Validate payload against the Model named by its $schema URI.

PARAMETER DESCRIPTION
payload

A dict that includes a $schema key.

TYPE: JsonObject

registry

A FingerprintRegistry mapping URIs to Model classes.

TYPE: FingerprintRegistry

RETURNS DESCRIPTION
Model

A validated Model instance whose class came from the registry.
RAISES DESCRIPTION
LookupError

If the URI is not registered.
KeyError

If the payload has no $schema key.