dbt Model Versions and Open Data Contracts

A model can keep the same name and become a different product. That is where consumers get hurt.

Breaking changes need names

dbt documents model versions as a governance feature in dbt Mesh, alongside access and contracts. dbt also documents model contracts as definitions of the returned dataset shape. Those features give analytics teams better language for compatibility, but the Open Data Infrastructure question is bigger than dbt alone.

A data product version should tell consumers what changed, whether the shape changed, whether the meaning changed, which migration window applies, and how downstream systems should move.

Versions are consumer promises

Versioning is not a decoration on the model name. It is a promise that consumers can plan around. A compatible change may not need a new version. A semantic change might need one even when the columns look the same.

This is where open contracts matter. The version needs to travel into the catalog, lineage graph, semantic layer, and agent context. Otherwise, only dbt users see the warning while other consumers keep assuming the old meaning.

The ODI contract pattern

Open Data Infrastructure should connect dbt model versions to catalog metadata, lineage, data product SLAs, and consumer notices. That makes versioning part of the shared data control plane rather than a project-local convention.

For adjacent context, read dbt Core model contracts and open catalogs, dbt Semantic Layer and open catalog boundaries, and semantic contracts in ODI.

What breaks first

• A model version changes but catalog metadata still points consumers to the old contract.
• Columns stay stable while business meaning changes without review.
• Agents query the new model with examples generated from the old version.
• Deprecation windows are tracked in tickets rather than machine-readable metadata.

Questions to ask

Ask what qualifies as a breaking change, who approves semantic changes, and how consumers discover new versions. Ask whether catalog metadata includes version status, owner, migration deadline, and compatibility notes.

A version number is useful only when consumers can act on it.

Sources to start with

These primary sources anchor the technical claims in this guide.

• dbt model versions documentation
• dbt model contracts documentation
• dbt versions resource property documentation
• DataHub data contract entity documentation

Data contracts fail quietly when version intent stays local.