aeat.domain.filing._schema module

Pydantic v2 schema for the domain.filing subpackage.

Every type in this module is a strict, frozen pydantic v2 model or a closed enum.StrEnum. These are the boundary-crossing records the rest of the project pins against — keep them stable.

class ModeloValueKind(*values)[source]

Bases: StrEnum

Provenance kind of a ModeloValue.

LITERAL
COMPUTED
INHERITED
DEFAULT
EMPTY
class ModeloValue(**data)[source]

Bases: BaseModel

The typed value of one casilla on a ModeloDraft.

Variables:

  • casilla_id – Stable casilla ID (e.g. "03").

  • value – The scalar value carried by this casilla. None iff kind is ModeloValueKind.EMPTY.

  • kind – Provenance kind — literal user input, computed, inherited from a previous draft, default from the casilla schema, or empty.

  • source – Free-text provenance string — e.g. "user-supplied", "computed from 01,02", "default per modelo schema".

  • formula_trace_casilla_ids – For COMPUTED values, the casilla IDs that fed the computation. None for non-computed kinds.

Parameters:
casilla_id: CasillaId
value: ModeloScalar
kind: ModeloValueKind
source: str
formula_trace_casilla_ids: tuple[CasillaId, ...] | None
class ModeloBindingValue(**data)[source]

Bases: BaseModel

The typed value of one registry binding on a ModeloDraft.

Carries the same regulatory grounding the casilla half exposes via ModeloCasillaProvenance: legal_refs and source_refs populated from the binding definition, plus a typed BindingSourceKind source (replacing the former free-text provenance string) so a bound value is operator-traceable at parity with a computed casilla.

Variables:

  • binding_id – Stable registry binding id this value materialises.

  • value – The scalar value carried for this binding.

  • kind – Provenance kind — literal input, computed, inherited, etc.

  • source – Typed registry binding source kind (e.g. MANUAL_INPUT, LEDGER_IVA_AGGREGATION).

  • legal_refs – Legal references carried from the binding definition.

  • source_refs – Source references carried from the binding definition.

  • row_index – 1-based row index for multi-row (detail-record) bindings.

Parameters:
binding_id: BindingId
value: ModeloScalar
kind: ModeloValueKind
source: BindingSourceKind
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
row_index: int | None
class ModeloCasillaProvenance(**data)[source]

Bases: BaseModel

Regulatory grounding for one casilla carried on a filing draft.

formula_id is set for computed casillas (those whose value is produced by a registry formula) and None for manual-input or bound casillas. legal_refs and source_refs are always populated from the registry casilla definition when the draft is created.

Parameters:

  • casilla_id (CasillaId)

  • formula_id (FormulaId | None)

  • legal_refs (tuple[LegalRefId, ...])

  • source_refs (tuple[SourceRefId, ...])

casilla_id: CasillaId
formula_id: FormulaId | None
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
class ModeloValidationFinding(**data)[source]

Bases: BaseModel

One finding produced by the validator.

Variables:

  • casilla_id – The casilla the finding is about, or None for cross-cutting findings such as deadline checks.

  • severity – ERROR / WARNING / INFO.

  • code – A stable machine-readable code (e.g. "casilla-required-missing").

  • message – A strictly-typed Translatable key.

  • references_rules – Tuple of Manual práctico Rule IDs that justify the finding (see domain.manuals.Rule).

Parameters:
casilla_id: CasillaId | None
severity: BaseSeverity
code: str
message: tr
references_rules: tuple[str, ...]
class ModeloApprovalBasis(**data)[source]

Bases: BaseModel

Persisted approval-basis digests for deterministic stale detection.

Parameters:

  • version (str)

  • draft_payload_fingerprint (str)

  • draft_review_fingerprint (str)

  • transaction_catalogue_fingerprint (str)

  • invoice_catalogue_fingerprint (str)

  • prior_filing_observations_fingerprint (str)

  • profile_activity_fingerprint (str)

  • category_profiles_fingerprint (str)

  • schema_formula_fingerprint (str)

version: str
draft_payload_fingerprint: str
draft_review_fingerprint: str
transaction_catalogue_fingerprint: str
invoice_catalogue_fingerprint: str
prior_filing_observations_fingerprint: str
profile_activity_fingerprint: str
category_profiles_fingerprint: str
schema_formula_fingerprint: str
class ModeloDraft(**data)[source]

Bases: BaseModel

A typed, validated draft of one filing.

The draft_id is a content-addressed hash of (modelo, period, profile_tax_id, snapshot_ref, values). Re-validating a draft preserves its identity because findings, status, updated_at and notes are deliberately excluded from the hash.

Parameters:
draft_id: str
modelo: str
period: Period
profile_tax_id: SubjectTaxId
subject_tax_id: SubjectTaxId
snapshot_ref: RegistrySnapshotRef
status: ModeloDraftStatus
values: tuple[ModeloValue, ...]
binding_values: tuple[ModeloBindingValue, ...]
casilla_provenance: tuple[ModeloCasillaProvenance, ...]
findings: tuple[ModeloValidationFinding, ...]
created_at: datetime
updated_at: datetime
schema_version: str
notes: str
approved_at: datetime | None
approved_by: str | None
review_checksum: str | None
approval_basis: ModeloApprovalBasis | None
compute_modelo_draft_id(*, modelo, period, profile_tax_id, snapshot_ref, values, binding_values=())[source]

Compute the stable, content-addressed draft_id.

The period is serialised as {"filing_year": <int>, "code": "<token>"} so the hash is deterministic and self-consistent regardless of the human-readable str(period) form.

Parameters:
Return type:

str

Returns:

A 16-character lowercase hex SHA-256 prefix.