Self-describing JSON¶

didactic.api.schema_uri ¶

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

Return the canonical schema URI for a Model class.

Parameters:

Name	Type	Description	Default
`cls`	`type[Model]`	A Model subclass.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`instance`	`Model`	A Model instance.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`payload`	`JsonObject`	A dict that includes a `$schema` key.	required
`registry`	`FingerprintRegistry`	A FingerprintRegistry mapping URIs to Model classes.	required

Returns:

Type	Description
`Model`	A validated Model instance whose class came from the registry.

Raises:

Type	Description
`LookupError`	If the URI is not registered.
`KeyError`	If the payload has no `$schema` key.