---
title: "Canonical Hotel Entity Model"
description: "Design a canonical hotel identity layer that maps multiple supplier property records into one traceable entity with provenance and merge history."
slug: "canonical-hotel-entity-model"
translationKey: "architecture-canonical-hotel-entity"
locale: "en"
type: "guide"
category: "architecture"
tags: ["hotel","canonical-entity","mapping","identity","catalog"]
publishedAt: "2026-09-26"
updatedAt: "2026-09-26"
reviewedAt: "2026-09-26"
---

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

```text
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.