Normalized Registration Models

Purpose

Lossless source wrapper capturing registry authority context plus the original raw payload. Supports optional decoded fields for human-readable diagnostics without mutating the source record.

Fields

• name (str) — registry authority identifier (e.g., FAA, EASA, TC)
• raw (Dict[str, Any]) — unmodified original payload
• decoded (Optional[Dict[str, Any]]) — decoded/human-readable fields (optional)

Validation rules

• name and raw are required (Field(...)).

Purpose

Normalized registrant/owner envelope used for consistent display and indexing across sources.

Fields

• name (Optional[str])
• address (Optional[str])
• city (Optional[str])
• state (Optional[str])
• fractional_owner (Optional[str])

Validation rules

• No explicit validators; fields are optional to tolerate partial source coverage.

Purpose

Normalized aircraft identity and manufacturing attributes used for linking (mfr/model codes + serial) and search indexing.

Fields

• make (Optional[str])
• model (Optional[str])
• year (Optional[int])
• serial (Optional[str])
• mfr_mdl_code (Optional[str])

Validation rules

• No explicit validators; intended to accept sparse/partial records.

Purpose

Normalized classification envelope capturing type and regulatory classification using canonical enums. Drives link eligibility checks and supports consistent filtering/faceting across sources.

Fields

• aircraft_type (Optional[AircraftTypeEnum])
• engine_type (Optional[EngineTypeEnum])
• airworthiness (Optional[AirworthinessClassEnum])
• registrant_type (Optional[RegistrantTypeEnum])
• light_sport_type (Optional[LightSportTypeEnum])
• special_flight_permit (Optional[SpecialFlightPermitEnum])
• category (Optional[CertificationCategoryEnum])

Validation rules

• Enum-typed fields enforce canonical value domains at ingestion time.

Purpose

Normalized identifier envelope for transponder and registry uniqueness signals. Used directly by search indexing and cross-dataset joins.

Fields

• mode_s (Optional[str])
• mode_s_hex (Optional[str])
• unique_id (Optional[str])

Validation rules

• No explicit validators.

Purpose

Normalized operational timestamps used for lifecycle status, filtering, and synchronization auditing. Stored as epoch/int64 to avoid per-source date parsing ambiguity at query time.

Fields

• last_action (Optional[int])
• expiration (Optional[int])
• last_synced (Optional[int])

Validation rules

• No explicit validators; upstream is expected to normalize to epoch seconds.

Purpose

Normalized engine descriptor used for indexing and presentation. Independent from source-specific engine code systems.

Fields

• manufacturer (Optional[str])
• model (Optional[str])
• thrust (Optional[str])

Validation rules

• No explicit validators.

Purpose

Canonical, normalized registry record persisted in DynamoDB and used as the primary read model for registry queries. Provides eligibility logic for ICAO linking and a Typesense projection for high-performance search.

Fields

• registration_id (str) — canonical registration key (e.g., tail number)
• country (str, nullable) — registry country
• status (Optional[str]) — normalized status label
• icao_code (Optional[str]) — derived or source-provided ICAO type designator
• owner (OwnerInfo)
• aircraft (AircraftInfo)
• engine (EngineInfo)
• classification (ClassificationInfo)
• identifiers (IdentifierInfo)
• dates (DateInfo)

Validation rules

• may_have_icao_link() gates ICAO linking to avoid invalid/ambiguous classes (e.g., special flight permits, multiple airworthiness, glider/balloon/blimp/gyroplane types, glider/balloon certification categories).
• get_icao_code() returns deterministic fallback designators for excluded categories (e.g. ZZZZ, GLID, BALL, SHIP, GYRO) and otherwise resolves via the FAA-to-ICAO link repository using mfr_mdl_code + serial.
• to_typesense() removes None values to satisfy Typesense ingestion constraints.

Primary key structure (PK / SK)

• PK: AIRCRAFT#REGISTRY (canonical registry partition)
• SK: DETAIL#{tail_number}#FOREIGN (detail record with source qualifier)

GSI / index structure

No GSIs are defined or referenced in this snippet. Query patterns are expected to be PK/SK-driven for primary reads, with Typesense used for multi-field search and filtering.

Query strategy enabled by the key design

• Point lookup: direct lookup by canonical identifier using PK + computed SK (DETAIL#...#FOREIGN).
• Partition-scoped listing: possible via Query on PK with begins_with(SK, "DETAIL#") and/or filtering by suffix conventions (e.g. #FOREIGN) if implemented in the repository layer.
• Cross-record search: executed via Typesense using the flattened document produced by to_typesense() (city/state/status/aircraft_make/aircraft_model/mode_s/unique_id/date ranges).
• Link resolution: ICAO type designator resolution is performed by consulting FAAICAOLinkModel keyed on mfr_mdl_code + serial when eligible.

Status

No Objects / repository manager is defined in this snippet for NormalizedRegistryModel. Repository behavior is expected to be provided by DynamoBaseModel or external service code. This model does integrate with another repository via FAAICAOLinkModel.objects.get(...).

Operational Flow

1. Request: ingest/sync trigger fires for one or more registry sources.
2. Job: normalization job enqueued with source payload(s) and authority metadata.
3. Worker: worker builds NormalizedRegistryModel (nested sub-models + enums) and sets dates.last_synced.
4. Persistence: worker writes to DynamoDB using PK=AIRCRAFT#REGISTRY and SK=DETAIL#{id}#FOREIGN.
5. Query: application reads canonical records from DynamoDB; search queries use Typesense documents from to_typesense().