Canonical Entities
Summary
Canonical entities give the platform stable internal concepts for customers, locations, jobs, vendors, technicians, prospects, and other recurring business objects.
Problem
External systems model the same real-world object differently. A provider's customer, job, location, membership, or vendor record is not automatically the platform's canonical entity. Treating provider IDs as internal truth spreads vendor coupling across the repo.
Principle
Separate provider records from canonical internal entities. Use crosswalks and normalization layers to connect them.
Platform Shape
Silver transforms are the natural home for canonical entity construction and crosswalks. The lakehouse docs call out customer, location, job, appointment, technician, vendor, and prospect-related transforms. Services and downstream jobs can then depend on the canonical layer instead of speaking every provider language directly.
Canonical does not mean perfect. When identity is ambiguous, the platform should create reviewable signals or issues rather than silently choosing a match.
Source Evidence
docs/domains/lakehouse.mdpipelines/lakehouse/transform/silverservices/lkci_lakehouse
Related Reading
docs/engineering/concepts/failures-are-data.mddocs/engineering/concepts/silver-canonicalization.md