Canonical Hotel Entity Model

A canonical hotel entity maps supplier-specific property records into one internal identity. The goal is not to erase source records but to make the relationship between source identity and canonical identity traceable.

Production scenario

The same property arrives with different IDs from Expedia, Booking connectivity and a direct channel. Names, addresses, coordinates and brand details differ slightly.

Architecture flow

Supplier Property
 -> Candidate Generation
 -> Match Features
 -> Match Decision
 -> Canonical Hotel
 -> Source Mapping
 -> Attribute Provenance
 -> Merge / Split / Reconciliation

Key entities

Use CanonicalHotel, SupplierProperty, PropertyMapping, PropertyAlias, AttributeObservation, MergeDecision and SourceConfidence.

Canonical model

The canonical record needs a stable internal ID. For fields such as name, address, geo, brand and phone, preserving source and observation time makes later reconciliation much safer.

A single flattened “name” value without provenance loses important evidence.

Match features

Useful features include normalized name, address components, geo distance, phone, brand/chain, postal code, official website and known provider cross-references.

No individual feature is sufficient in every market.

Merge and split decisions

False merges are often more damaging than false splits because unrelated offers become comparable under one hotel.

When confidence is low, unresolved/manual-review states are safer than automatic merge.

Attribute provenance

Avoid “last writer wins” for canonical attributes. Use source priority, confidence, freshness and field-specific rules.

For example, an official source may be preferred for coordinates while amenities may be combined from several sources.

Failure modes

Watch for same-name properties, rebrands creating duplicates, address-normalization errors, moved properties, stale supplier records and chain-name collisions.

Cache and consistency

Mapping changes affect cached search results, offer indexes and analytics dimensions. Merge/split actions should emit downstream invalidation events.

Observability

Track auto-match rate, manual-review rate, merge reversals, duplicate-property rate, unresolved mappings, suspicious geo-distance matches and stale source mappings.

Alternatives

A canonical layer can be excessive for a one-provider product. Once multiple suppliers are compared, it becomes close to mandatory.

Production checklist

Use stable canonical IDs, source mapping, attribute provenance, confidence scoring, merge/split audit trails, rebrand workflows, downstream invalidation and manual review.