aeat.domain.calculations.registry._schema_surfaces module

Casilla, relation, export, and record schema models.

class CasillaContinuidadEvolutionDefinition(**data)[source]

Bases: RegistryModel

Declared cross-revision evolution for one casilla continuity chain.

Parameters:

  • id (RecordId)

  • continuidad_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='^[a-z0-9][a-z0-9._:-]*[a-z0-9]$|^[a-z0-9]$')])])

  • from_revision (RevisionId)

  • to_revision (RevisionId)

  • evolution_kind (Literal['unchanged', 'label_evolved', 'legal_refs_evolved', 'label_and_legal_refs_evolved', 'repurposed', 'retired'])

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

id: RecordId
continuidad_id: ContinuidadId
from_revision: RevisionId
to_revision: RevisionId
evolution_kind: Literal['unchanged', 'label_evolved', 'legal_refs_evolved', 'label_and_legal_refs_evolved', 'repurposed', 'retired']
legal_refs: LegalRefs
source_refs: SourceRefs
class CasillaAlias(**data)[source]

Bases: RegistryModel

A label variant for a casilla, carrying its own legal grounding.

Used by Plan C’s semantic-role validator: two casillas in different modelos can share a semantic_role even though their primary label strings differ verbatim, provided each declares the divergent phrasing via an aliases entry with a documented BOE or AEAT source.

Parameters:

  • label (str)

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

label: str
legal_refs: LegalRefs
source_refs: SourceRefs
class CasillaConstraints(**data)[source]

Bases: RegistryModel

Declarative value constraints applied after a casilla is evaluated.

Captures the legal sign / range rules AEAT mandates per LIRPF / LIVA / LIS articles: a withholding casilla cannot carry a negative value, a deductibility cap restricts the maximum, a non-negativity floor on a cuota líquida prevents arithmetic underflow propagating through downstream formulas.

Each constraint declares its own legal grounding so the engine can surface a BOE permalink in the violation envelope when a computed value falls outside the declared bounds. The runtime raises a typed CasillaConstraintViolationError; the Sheets apply adapter renders the same record as a setDataValidation rule on the corresponding cell so the operator sees the constraint directly in the workbook UI.

Parameters:

  • sign (Literal['any', 'non_negative', 'non_positive'])

  • min_value (Annotated[Decimal, BeforeValidator(func=~aeat.domain.calculations.registry._schema_scalars._coerce_decimal, json_schema_input_type=PydanticUndefined)] | None)

  • max_value (Annotated[Decimal, BeforeValidator(func=~aeat.domain.calculations.registry._schema_scalars._coerce_decimal, json_schema_input_type=PydanticUndefined)] | None)

  • pattern (str | None)

  • min_length (int | None)

  • max_length (int | None)

  • enum (tuple[str, ...] | None)

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

sign: Literal['any', 'non_negative', 'non_positive']
min_value: DecimalValue | None
max_value: DecimalValue | None
pattern: str | None
min_length: int | None
max_length: int | None
enum: tuple[str, ...] | None
legal_refs: LegalRefs
source_refs: SourceRefs
violates(value)[source]

Return a short reason string if a Decimal value violates this constraint, else None.

Numeric-only violation check preserved for downstream consumers of computed casilla values. Text constraints (pattern, min_length, max_length, enum) are surfaced through the sibling violates_text() method.

Return type:

str | None

Parameters:

value (Decimal)

violates_text(value)[source]

Return a short reason string if a text value violates the text constraints, else None.

Checks the four text-shape constraints introduced by Plan B: pattern, min_length, max_length, and enum. Used by consumers that resolve a casilla value into a string at evaluation time.

Return type:

str | None

Parameters:

value (str)

class CasillaDefinition(**data)[source]

Bases: RegistryModel

A single AEAT casilla within a modelo revision.

id is the canonical reference identity. number and segmento are reviewed AEAT record-design metadata. For single-segment modelos segmento is unset and number alone is unique within the revision. Multi-segment AEAT modelos (e.g. Modelo 200) reuse the same five-digit number across distinct record segments with a different meaning in each; those casillas carry the AEAT record-segment code in segmento to disambiguate metadata.

Parameters:

  • id (CasillaId)

  • number (str)

  • segmento (str | None)

  • label (str)

  • localized_labels (dict[str, str])

  • localized_help (dict[str, str])

  • section (tuple[str, ...])

  • data_type (Literal['decimal', 'money', 'integer', 'ratio', 'text', 'boolean', 'nif', 'year', 'period_code', 'country_code', 'iban', 'name', 'nif_iva', 'ccaa_code', 'province_code', 'postal_code', 'municipality_code', 'bic', 'date'])

  • required (bool)

  • input_kind (Annotated[InputKind, BeforeValidator(func=~aeat.domain.calculations.registry._schema_input_kind._coerce_input_kind, json_schema_input_type=PydanticUndefined)])

  • formula (FormulaId | None)

  • binding (BindingId | None)

  • alternate_bindings (tuple[BindingId, ...])

  • export_refs (tuple[ExportFieldId, ...])

  • constraints (CasillaConstraints | None)

  • form_number (str | None)

  • continuidad_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='^[a-z0-9][a-z0-9._:-]*[a-z0-9]$|^[a-z0-9]$')])] | None)

  • semantic_role (str | None)

  • semantic_role_cardinality (Literal['shared', 'intentional_singleton'])

  • semantic_role_cardinality_reason (str | None)

  • aliases (tuple[CasillaAlias, ...])

  • internal_only (bool)

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

id: CasillaId
number: str
segmento: str | None
label: str
localized_labels: dict[str, str]
localized_help: dict[str, str]
section: tuple[str, ...]
data_type: Literal['decimal', 'money', 'integer', 'ratio', 'text', 'boolean', 'nif', 'year', 'period_code', 'country_code', 'iban', 'name', 'nif_iva', 'ccaa_code', 'province_code', 'postal_code', 'municipality_code', 'bic', 'date']
required: bool
input_kind: InputKindValue
formula: FormulaId | None
binding: BindingId | None
alternate_bindings: tuple[BindingId, ...]
export_refs: tuple[ExportFieldId, ...]
constraints: CasillaConstraints | None
form_number: str | None
continuidad_id: ContinuidadId | None
semantic_role: str | None
semantic_role_cardinality: Literal['shared', 'intentional_singleton']
semantic_role_cardinality_reason: str | None
aliases: tuple[CasillaAlias, ...]
internal_only: bool
legal_refs: LegalRefs
source_refs: SourceRefs
get_label(locale)[source]

Return the localized label for locale, falling back to the Spanish invariant label.

Return type:

str

Parameters:

locale (str)

get_help(locale)[source]

Return the localized help/hint text for locale, or None if not defined.

Return type:

str | None

Parameters:

locale (str)

class CalculationCompletenessCasilla(**data)[source]

Bases: RegistryModel

One required canonical casilla.id in a calculation-completeness manifest.

casilla_id is the authoritative reference key consumed by the validator. number and segmento remain official record-design metadata for drift review: the validator cross-checks them against the referenced casilla, but no consumer may resolve the manifest by those metadata fields.

The manifest enumerates only the casillas inside a modelo’s calculation closure — formula targets, the casillas referenced inside any formula expression, formula and binding endpoint casillas, and verification-expectation operands. Pure accounting-statement data-entry fields that feed no calculation are intentionally absent from this required set.

Parameters:

  • casilla_id (CasillaId)

  • number (str)

  • segmento (str | None)

casilla_id: CasillaId
number: str
segmento: str | None
record_design_metadata()[source]

Return the reviewed (segmento, number) metadata pair.

Return type:

tuple[str | None, str]

manifest_key()[source]

Return the canonical id plus its reviewed record-design metadata.

Return type:

tuple[str, str | None, str]

class CalculationCompletenessManifest(**data)[source]

Bases: RegistryModel

The required calculation-closure casilla set for a modelo revision.

Enumerates the canonical casilla.id values in a modelo’s calculation closure — the casillas the cross-connecting calculation engine traverses: every formula target, every casilla referenced inside a formula expression, every binding and relation endpoint casilla, and every verification-expectation operand. It is derived from the official AEAT Diseño de Registros intersected with the modelo’s calculation surface — Diseño-authoritative on each casilla’s segment, number, and label, but the checked-in reference key is the registry’s canonical casilla.id. The segment/number metadata is retained as reviewed evidence and cross-checked against that id.

The registry validator enforces manifest-required ⊆ declared by canonical casilla.id plus a segment/number metadata check and a legal_refs / source_refs grounding check on each required casilla. A casilla the revision declares but the manifest does not list (a pure accounting-statement field) is not a failure.

manual_extraction flags a manifest authored from a manual read of a PDF-only Diseño that resists machine extraction; the off-load-path drift re-verification skips the machine re-derivation for such manifests and records manual_extraction_reason instead of failing silently.

Parameters:

  • source_ref (SourceRefId)

  • casillas (tuple[CalculationCompletenessCasilla, ...])

  • manual_extraction (bool)

  • manual_extraction_reason (str | None)

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

source_ref: SourceRefId
casillas: tuple[CalculationCompletenessCasilla, ...]
manual_extraction: bool
manual_extraction_reason: str | None
legal_refs: LegalRefs
source_refs: SourceRefs
casilla_ids()[source]

Return the frozenset of required canonical casilla.id values.

Return type:

frozenset[TypeAliasType]

manifest_keys()[source]

Return canonical ids paired with their reviewed record-design metadata.

Return type:

frozenset[tuple[str, str | None, str]]

class AlgorithmProviderDefinition(**data)[source]

Bases: RegistryModel

Parameters:

  • id (str)

  • import_path (str)

  • callable_name (str)

  • deterministic (Literal[True])

  • side_effect_free (Literal[True])

  • allowed_input_schema (Mapping[str, str])

  • output_schema (Mapping[str, str])

  • trace_contract (str)

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

id: str
import_path: str
callable_name: str
deterministic: Literal[True]
side_effect_free: Literal[True]
allowed_input_schema: Mapping[str, str]
output_schema: Mapping[str, str]
trace_contract: str
legal_refs: LegalRefs
source_refs: SourceRefs
class AlgorithmBindingDefinition(**data)[source]

Bases: RegistryModel

Parameters:

  • id (str)

  • provider (str)

  • target_casilla_id (CasillaId)

  • inputs (Mapping[str, BindingId | CasillaId | ParameterId | RelationId])

  • output_casilla_ids (Mapping[str, CasillaId])

  • constants (tuple[ParameterId, ...])

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

id: str
provider: str
target_casilla_id: CasillaId
inputs: Mapping[str, BindingId | CasillaId | ParameterId | RelationId]
output_casilla_ids: Mapping[str, CasillaId]
constants: tuple[ParameterId, ...]
legal_refs: LegalRefs
source_refs: SourceRefs
class RelationRevisionSelector(**data)[source]

Bases: RegistryModel

Parameters:

  • year (int | None)

  • year_from (int | None)

  • year_to (int | None)

  • filing_year_delta (int | None)

year: int | None
year_from: int | None
year_to: int | None
filing_year_delta: int | None
class RelationPeriodAlignment(**data)[source]

Bases: RegistryModel

Parameters:

  • mode (Literal['previous_quarter', 'prior_pagos_cumulative'] | None)

  • source_periods (Literal['quarters', 'months', 'annual_summary'] | None)

  • source_period_kind (Literal['quarterly'] | None)

  • source_period (str | None)

  • target_period (str | None)

  • filing_year_delta (int | None)

mode: Literal['previous_quarter', 'prior_pagos_cumulative'] | None
source_periods: Literal['quarters', 'months', 'annual_summary'] | None
source_period_kind: Literal['quarterly'] | None
source_period: str | None
target_period: str | None
filing_year_delta: int | None
class RelationDefinition(**data)[source]

Bases: RegistryModel

Parameters:

  • id (RelationId)

  • kind (Literal['previous_period', 'annual_summary', 'cross_model_output'])

  • dependency_role (Literal['profile_schedule', 'periodic_to_annual_summary', 'instalment_to_final_settlement', 'direct_calculation', 'factual_evidence'])

  • source_modelo (ModeloId)

  • source_revision_selector (RelationRevisionSelector)

  • source_casilla_id (CasillaId)

  • target_binding (BindingId)

  • period_alignment (RelationPeriodAlignment)

  • source_periods (tuple[str, ...])

  • target_periods (tuple[str, ...])

  • source_period_offset_from_target (int | None)

  • aggregation (RelationAggregation | None)

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

id: RelationId
kind: Literal['previous_period', 'annual_summary', 'cross_model_output']
dependency_role: Literal['profile_schedule', 'periodic_to_annual_summary', 'instalment_to_final_settlement', 'direct_calculation', 'factual_evidence']
source_modelo: ModeloId
source_revision_selector: RelationRevisionSelector
source_casilla_id: CasillaId
target_binding: BindingId
period_alignment: RelationPeriodAlignment
source_periods: tuple[str, ...]
target_periods: tuple[str, ...]
source_period_offset_from_target: int | None
aggregation: RelationAggregation | None
legal_refs: LegalRefs
source_refs: SourceRefs
class ExportFieldDefinition(**data)[source]

Bases: RegistryModel

Parameters:

  • id (ExportFieldId)

  • offset (int | None)

  • length (int | None)

  • kind (Annotated[CasillaFieldKind, BeforeValidator(func=~aeat.domain.calculations._export_field_kind._coerce_casilla_field_kind, json_schema_input_type=PydanticUndefined)])

  • casilla_id (CasillaId | None)

  • binding (BindingId | None)

  • literal (str | None)

  • header_key (str | None)

  • draft_attribute (Literal['modelo', 'period', 'profile_tax_id', 'filing_year', 'period_code'] | None)

  • computed_key (Literal['envelope_closing_tag'] | None)

  • data_type (Literal['text', 'integer', 'decimal', 'money', 'date', 'boolean'])

  • required (bool)

  • padding (Literal['left_zero', 'left_space', 'right_space', 'none'])

  • justification (Literal['left', 'right', 'none'])

  • date_format (str | None)

  • signed (bool)

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

id: ExportFieldId
offset: int | None
length: int | None
kind: CasillaFieldKindValue
casilla_id: CasillaId | None
binding: BindingId | None
literal: str | None
header_key: str | None
draft_attribute: Literal['modelo', 'period', 'profile_tax_id', 'filing_year', 'period_code'] | None
computed_key: Literal['envelope_closing_tag'] | None
data_type: Literal['text', 'integer', 'decimal', 'money', 'date', 'boolean']
required: bool
padding: Literal['left_zero', 'left_space', 'right_space', 'none']
justification: Literal['left', 'right', 'none']
date_format: str | None
signed: bool
legal_refs: LegalRefs
source_refs: SourceRefs
class RecordDiscriminator(**data)[source]

Bases: RegistryModel

Record-shape discriminator for record types that share literal prefixes.

A record’s literal-prefix matcher cannot tell two records apart when they share their leading literal fields (AEAT models several Tipo-2 record sub-shapes that all start with the same record-type literal). The discriminator declares a contiguous byte range whose populated-or-blank pattern uniquely identifies this record subtype, letting the parser pick the correct record while reading binding-row sequences.

Parameters:

  • offset (int)

  • length (int)

  • requires (Literal['blank', 'non_blank'])

offset: int
length: int
requires: Literal['blank', 'non_blank']
class ExportRecordDefinition(**data)[source]

Bases: RegistryModel

Parameters:
id: RecordId
record_type: str
order: int
encoding: str
line_ending: Literal['crlf', 'lf', 'none']
required: bool
repeat: Literal['binding_rows'] | None
binding_record: str | None
row_field_casilla_ids: Mapping[str, CasillaId]
discriminator: RecordDiscriminator | None
requires_positive_casilla_id: CasillaId | None
fields: tuple[ExportFieldDefinition, ...]
class ExportLayoutDefinition(**data)[source]

Bases: RegistryModel

Parameters:

  • id (ExportLayoutId)

  • format (Literal['fixed_width', 'xml_dictionary'])

  • dictionary_source_ref (SourceRefId | None)

  • source_refs (Annotated[tuple[SourceRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • legal_refs (Annotated[tuple[LegalRefId, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])])

  • records (tuple[ExportRecordDefinition, ...])

id: ExportLayoutId
format: Literal['fixed_width', 'xml_dictionary']
dictionary_source_ref: SourceRefId | None
source_refs: SourceRefs
legal_refs: LegalRefs
records: tuple[ExportRecordDefinition, ...]