Open Data Infrastructure
Data Modeling Semantic Versioning for Agent Contracts
How semantic versioning gives agents clear signals for compatible, breaking, and review-only data model changes.
Agents need to know whether a data model changed in a way that breaks their contract.
Schema change is not the only breaking change
Data model changes can break agents without breaking SQL. A column can keep its name while its meaning changes. A metric can keep its type while its denominator changes. A policy can keep a rule name while changing who can see the result.
Semantic versioning gives data teams a familiar language for communicating compatibility. Major changes break contracts. Minor changes add compatible capability. Patch changes fix behavior without changing the contract. Agent contracts need that signal across schema, metrics, policy, and meaning.
Core idea: Data model semantic versioning tells agents which changes are compatible, which are breaking, and which require review before use.
SemVer starts with a declared public API
The Semantic Versioning specification repository describes rules for assigning and incrementing version numbers. Its central discipline is declaring a public API and changing version numbers based on compatibility impact.
A data model contract is not software API code, but the principle transfers well. The model has consumers. The consumers need to know whether a change is safe to consume automatically.
Version the contract agents consume
- Declare the agent-facing API for each model, including schema, metric definitions, policy assumptions, freshness, and allowed actions.
- Use major versions for breaking meaning, policy, denominator, or schema changes.
- Use minor versions for compatible additions such as optional fields or new documented slices.
- Use patch versions for fixes that preserve the contract.
- Teach agents to refuse or request review when a major version changes.
This connects data modeling and ODI, semantic contracts, and dbt exposure contracts for agents. A version number is useful only when it reflects what consumers can safely assume.
What breaks first
- A metric definition changes but the model name stays the same.
- An agent keeps using a deprecated field because no compatibility signal exists.
- Patch releases include semantic changes because versioning is treated as ceremony.
- Policy changes are versioned separately from the data model that depends on them.
Questions to ask before versioning models
- What is the public API of this data model?
- Which changes are breaking for agents, even if they are valid SQL changes?
- Where do metric, policy, and freshness changes appear in the version?
- Can agents compare required and available versions before acting?
Sources to start with
These primary sources anchor the technical claims in this guide.
Agents cannot respect a contract they cannot version.