Model & Specification Descriptors¶

Descriptor objects provide a normalised, inspectable view of both ORM models and external specifications.

They are immutable, explicit, and independent of validation logic.

TableSpec¶

Represents a table-level specification loaded from an external source (e.g. OMOP CSVs).

Table-level specification descriptor.

Represents metadata about a table as defined in an external specification source.

Attributes:

Name	Type	Description
`table_name`	`str`	Logical name of the table.
`schema`	`str`	Schema or namespace in which the table is defined.
`is_required`	`bool`	Whether the table is required by the specification.
`description`	`str`	Human-readable description of the table.
`user_guidance`	`Optional[str]`	Optional additional guidance for implementers.

Represents a field-level specification loaded from an external source.

Field-level specification descriptor.

Represents metadata about a field/column as defined in an external specification source.

Attributes:

Name	Type	Description
`table_name`	`str`	Name of the table to which the field belongs.
`field_name`	`str`	Name of the field/column.
`data_type`	`str`	Declared data type in the specification.
`is_required`	`bool`	Whether the field is required.
`is_primary_key`	`bool`	Whether the field is part of the primary key.
`is_foreign_key`	`bool`	Whether the field is a foreign key.
`fk_table`	`str \| None`	Referenced table name, if the field is a foreign key.
`fk_field`	`str \| None`	Referenced field name, if the field is a foreign key.

A derived, introspected representation of an ORM model class.

It captures: - column objects - primary keys - foreign key relationships

Normalised, inspectable descriptor for an ORM model class.

This descriptor is derived from SQLAlchemy inspection and captures the structural characteristics of a mapped ORM table.

It is used as the primary input to validation rules.

Attributes:

Name	Type	Description
`model_class`	`Type[ORMTableProtocol]`	The ORM model class.
`table_name`	`str`	The database table name.
`columns`	`dict[str, Column]`	Mapping of column names to SQLAlchemy Column objects.
`primary_keys`	`set[str]`	Set of primary key column names.
`foreign_keys`	`dict[str, tuple[str, str]]`	Mapping of column name to referenced (table, field).

Alias for the underlying ORM model class.

Returns:

Type	Description
`Type[ORMTableProtocol]`	The ORM model class.

Construct a ModelDescriptor from an ORM model class.

Parameters:

Name	Type	Description	Default
`model`	`Type[ORMTableProtocol]`	An ORM-mapped table class.	required

Returns:

Type	Description
`ModelDescriptor`	A descriptor derived from SQLAlchemy inspection.

Raises:

Type	Description
`TypeError`	If the provided class is not a mapped ORM model.