SchemaVersion

class SchemaVersion(key: str, components: list[type], description: str = '')

Associates a version key with its component types and an optional description.

components: list[type]

Alias for field number 1

description: str

Alias for field number 2

key: str

Alias for field number 0

VersionMatchResult

class VersionMatchResult(matched: bool, expected_types: list[type], found_types: list[type], missing_types: list[type], unexpected_types: list[type], default_ratio: float)

Diagnostic result from validate_version().

matched is True when all expected types were found and default_ratio is strictly below the validation threshold. default_ratio is 1.0 when data is empty.

default_ratio: float

Alias for field number 5

expected_types: list[type]

Alias for field number 1

found_types: list[type]

Alias for field number 2

matched: bool

Alias for field number 0

missing_types: list[type]

Alias for field number 3

unexpected_types: list[type]

Alias for field number 4

resolve_version

resolve_version(requested: str, versions: dict[str, list[type]]) → list[type] | None

Return the component list for the most recent version key <= requested.

Keys are compared lexicographically. Returns None when requested is older than every available key.

validate_version

validate_version(data: Any, expected_types: list[type], default_type: type, threshold: float = 0.5) → VersionMatchResult

Validate file data against expected component types.

Uses exact type comparison (type(item) is default_type) so that subclasses of the default type count as real components. matched is True when no expected types are missing and default_ratio < threshold.