Gold without a semantic contract is just another table
A gold device table that looks clean in Spark can still fail as a platform asset. Optional links to contracts drop unmatched devices. Free-text site fields hide business keys behind tribal regex. Captions and folders are treated as polish. Stakeholders open a report and half the estate is missing without an error.
Gold becomes useful when unmatched keys, captions, and relationships ship as one semantic contract with the table. "All devices visible regardless of match" is an acceptance test, not a slogan.
Figure 1. Gold only becomes a platform asset when keys and relationships behave as a semantic contract the model can trust. Source: Microsoft Learn: understand relationships.
Figure 2. Row counts on the SQL endpoint can look healthy while reports hide unmatched keys. Test the contract, not only Spark success. Source: Microsoft Learn: lakehouse SQL analytics endpoint.
I learned this delivering device estates where lakehouse row counts passed and report pages still looked empty for whole regions. The fact existed. The contract for unmatched members and relationship behavior did not.
The core idea
Device gold is not done when Delta is curated. It is done when the semantic model states how every device appears, how keys bridge, and how humans find fields.
Optional linkage to contracts or service items must surface unknowns, not silently filter. Parsed business keys from free-text are modeling decisions with tests. Culture captions and query folders are usability infrastructure. Treat them as part of the same release as the gold write.
A model that stays explainable
1. Unknown members beat silent drops
Left joins that filter away non-matches make dashboards look authoritative and incomplete. Keep every device row. Attach unknown or unmatched members on contract and bridge dimensions so totals reconcile to the inventory people believe. Document what "unknown" means so nobody "cleans" it away in a follow-up PR.
2. Parsed business keys are a modeling decision
If site or contract identifiers live in free-text fields, the parse rules belong in gold with fixtures, not in a report author's DAX or a one-off notebook cell. Version the rules. When the upstream text format changes, you want one place to fix and retest, not five visuals that each guessed differently.
3. Grain, bridge keys, and TMDL relationships ship together
Publish the grain statement (one row per device per what?), the bridge keys to contracts or service items, and the TMDL or model relationships in the same change set. A gold table without updated relationships is a landmine for the next semantic refresh. Role-playing dims need matching key types or you get blank visuals that look like DAX bugs.
4. Captions and query folders are part of the handoff
Field names that make sense to engineers fail field lists for analysts. Culture-aware captions, descriptions, and folder groupings reduce "where is the device id?" support. This is not decoration. It is how the semantic contract is consumed.
5. Stakeholder acceptance: all devices visible regardless of match
Write the test: inventory count in gold equals count reachable in the model under the default device path, including unmatched. Spot-check known orphans. If product owners care that every device appears, automate that check before you argue about color on the dashboard.
6. Keep enrichment logic shared
If telemetry facts and service-device facts both resolve devices to contracts, share the matching module. Divergent match logic produces two "truths" that both claim gold status.
Failure modes I design against
Inner-join comfort. Unmatched devices disappear. Leadership thinks coverage is complete.
Regex as hobby craft. Each notebook invents a slightly different site-code parse.
Gold merged, model relationships stale. Refresh succeeds. Visuals blank.
English-only technical names in the field list. Adoption dies quietly.
Accepting report screenshots as proof. Screenshots hide missing members.
Different match rules per fact. Device counts disagree by page.
Unknown members in the wild
Expect pushback the first time unknown contract members appear on a slicer. That pushback is useful. It forces a conversation about data quality versus silent exclusion. Teach filters for "matched only" as an explicit report choice, not as the default grain of gold. Gold tells the truth about coverage. Reports may narrow. They must not pretend the lake never saw the orphans.
Trade-offs
Unknown members inflate some visuals until filters are taught. That teaching is cheaper than silent undercount. Explicit parse rules mean change management when upstream text shifts; hidden parse rules mean silent drift. Shipping captions and TMDL with gold slows the data PR slightly and saves a week of semantic thrash. Shared enrichment modules require package discipline across notebooks. Worth it when two facts must agree.
What I would put on an ADR
- Device gold retains unmatched rows; unknown members are first-class.
- Business-key parse rules live in gold with fixture tests.
- Grain, bridge keys, and semantic relationships release together.
- Captions, descriptions, and query folders are required for publish.
- Acceptance includes "all devices visible regardless of contract match."
- Matching logic is shared across device-related facts.
Primary references: Microsoft Learn on semantic models in Fabric and Power BI modeling guidance for relationships, and TMDL workflows your team already uses for model-as-code.
When you review a pull request that only adds a gold table, ask for the semantic companion: unknown-member behavior, relationship diff, and caption coverage. If those are "follow-ups," the table is not a platform asset yet. It is inventory for a future incident.
How I review a device-gold PR
I ask four questions before merge. Does every device row survive optional contract linkage? Are parse rules for business keys covered by fixtures? Do TMDL relationships and key types match the gold grain in the same change set? Are captions and folders present for the fields analysts will hunt first? If any answer is "later," the PR is a table drop, not a platform asset. Later rarely arrives before the first blank visual ticket.
Closing
Curated Delta is necessary. It is not a semantic product.
If unmatched devices vanish, keys are tribal, and captions are "later," you shipped a table. Ship the contract: unknowns, bridges, relationships, and human-facing names in the same breath as gold.