What to promise per medallion — and how to version it without breaking consumers

If Story 1 was about how we slice data products (Topic × Medallion), and Story 2 was about how the platform enforces the rules, then Story 3 is the natural next step for every Data Product Owner:

What do we actually promise to consumers — and how do we make that promise trustworthy?

Because here’s what happens in real organizations:

• You publish a “Customer” product.
• People build reports, KPIs, ML features, and operational decisions on top of it.
• Six weeks later someone changes a join key, a dedup rule, a filter, or a definition.
• And suddenly your consumers are not just annoyed — they are afraid.

That fear is the death of “Data as a Product.”

The cure is not “more communication.”
The cure is a real contract: explicit promises, tied to medallion maturity, versioned like software.

Let me share the model that actually works in practice.

First: what a contract is (and what it isn’t)

A data contract is often misunderstood as “the schema.”

That’s a good start — but it’s not enough.

A trustworthy data contract is a product promise that answers:

1. What is it? (schema + semantics)
2. How reliable is it? (freshness, completeness, availability expectations)
3. What can change, and how will I be informed? (versioning + deprecation)
4. Who owns it? (support, escalation, responsibility)

A contract is not:

• a PDF nobody reads,
• a Confluence page that goes stale,
• or a “best effort” statement.

If your consumer cannot predict impact when you change something, you don’t have a contract — you have hope.

The big unlock: your promises must differ by medallion

Here’s the core mistake we made early on: we tried to promise “the same quality” everywhere.

But Bronze, Silver, and Gold are different products in spirit, even if they share lineage.

So instead of one generic contract, we aligned contract promises to maturity:

Bronze promise: Traceable, complete, replayable

Bronze is not “bad data.” It’s raw truth with context.

Bronze contract should focus on:

• lineage + provenance: where it came from, when, how it was captured
• retention + replay: how far back we keep data and whether reprocessing is supported
• format stability (best effort): schema may evolve, but changes are communicated and observable
• latency expectations: “near-real-time” vs “daily” — but don’t oversell

What Bronze should not promise:

• stable business semantics
• dedup guarantees
• KPI consistency

If a consumer wants “decision-grade,” Bronze is the wrong layer — and the contract should make that obvious.

Silver promise: Standardized, consistent, usable

Silver is where trust starts to form.

Silver contract should focus on:

• standardization rules: types, normalization, naming, units
• key consistency: business keys and uniqueness expectations
• dedup and data hygiene rules: what’s removed, how it’s resolved
• quality checks: what rules must pass (and how failures are handled)

Silver consumers are often analysts and data scientists. They tolerate evolution — but not randomness.

Silver should not promise:

• frozen business definitions of KPIs (that’s Gold)
• “no changes ever”

Silver is stable, but still evolving.

Gold promise: Semantic stability, decision-grade meaning

Gold is where your reputation lives.

Gold contract should focus on:

• business semantics: definitions, inclusions/exclusions, calculation rules
• SLOs that match decision use: freshness windows, availability, incident handling
• change discipline: breaking changes are rare and always versioned
• consumer guidance: examples, “how to use,” known limitations

Gold consumers aren’t forgiving. They shouldn’t have to be.

Gold should promise:

• stability and predictability
• explicit versioning
• clear deprecation windows

If your Gold output can change unexpectedly, it’s not Gold. It’s Silver wearing a Gold label.

The simplest contract structure that people actually use

You can write contracts in many formats, but the structure matters more than the tool.

Here’s a template that has worked well because it’s compact and practical:

1) Product identity

• Name, owner, purpose
• Intended consumers / use cases
• Support hours and escalation path

2) Interface (what consumers integrate with)

• Output ports (and which medallion)
• Schema (tables/events) + descriptions
• Examples: “golden queries” / usage snippets

3) Reliability promise

• Freshness / update frequency window
• Availability target (if applicable)
• Known failure modes + how incidents are communicated

4) Quality & constraints

• Key constraints / uniqueness expectations
• Completeness thresholds
• Business rule checks (especially for Gold)

5) Change policy

• Versioning model (semantic versioning works well conceptually)
• Deprecation window (e.g., 60–90 days)
• Breaking-change rules (what counts, what doesn’t)

It’s not long. It’s not academic. It’s the minimum a consumer needs to trust you.

Versioning: the part everyone avoids — and everyone regrets

Most “contract dramas” are not about data quality.

They’re about change.

So you need a versioning model that your org can actually follow.

A pragmatic rule set (works in the real world)

Think in three change categories:

Patch changes (safe)

Examples:

• adding a new optional column
• improving documentation
• fixing a bug that doesn’t change meaning

Communication: release note, no migration required.

Minor changes (manageable)

Examples:

• adding a new table/output port
• adding a new value in a code set
• tightening quality checks (with warning period)

Communication: announce + provide examples; consumers may adapt but aren’t forced.

Major changes (breaking)

Examples:

• renaming a column
• changing a key
• changing definition logic (filters, joins, dedup rules)
• changing grain (daily to monthly, per customer to per contract)
• removing outputs

Communication: new versioned output (parallel run), clear deprecation date, migration guidance.

The key is: breaking changes must not be “silent updates.”
They must be new versions consumers opt into.

Deprecation: your trust-building superpower

A deprecation policy sounds boring — until you realize it’s how you scale without fear.

A simple, respected deprecation flow looks like this:

1. Announce: what changes, why, who is impacted
2. Provide parallel path: new version/port available immediately
3. Support migration: examples, office hour, checklist
4. Enforce end date: old version is removed or frozen
5. Document outcome: final note in changelog

The magic isn’t the policy itself. It’s the consistency.

Consumers forgive change. They don’t forgive surprises.

The “trust test”: a quick self-check for every DPO

Before publishing (or changing) a product, ask yourself:

1. Can a consumer predict what will happen if we change X?
2. Does the contract clearly differentiate Bronze vs Silver vs Gold promises?
3. If a breaking change happens tomorrow, do we have a safe rollout path?
4. Is ownership and support unambiguous?
5. Would I be comfortable betting my own KPI dashboard on this?

If you answer “no” to two or more: you don’t need more meetings.
You need contract clarity and versioning discipline.

Next episode: Contract-as-code

In Story 4 we’ll flip perspectives again.

Because as a DPO you can define great promises — but if the platform can’t validate them, your contract becomes optional.

Next we’ll cover:

• CI contract gates (compatibility, completeness, policy compliance)
• runtime drift detection
• safe rollout patterns (canary ports, dual publish, time-boxed deprecation enforcement)

Contracts people trust are not written.
They are enforced.