Open Data Infrastructure
Semantic Contracts in Open Data Infrastructure
How semantic contracts define meaning, grain, metrics, policy context, and expectations across BI, APIs, and agents.
Schema tells you what columns exist. It does not tell you what the business thinks those columns mean. That gap is where a lot of expensive trust failures hide.
The practical problem
dbt semantic models describe entities, dimensions, and measures in a semantic layer. That is useful, but Open Data Infrastructure needs the semantic idea to connect across BI, APIs, catalogs, agents, lineage, and policy.
A semantic contract should define meaning, grain, allowed metrics, owner, freshness, policy context, examples, compatibility rules, and consumer expectations. It should explain what can change without breaking consumers and what requires review.
Meaning needs a contract
A schema contract can say that `customer_id` exists. A semantic contract should say which customer entity it represents, which identifiers map to it, which metrics can be grouped by it, which policies apply, and which examples show correct use.
That contract matters for agents because agents often operate through examples and tool schemas. If the semantic contract is not explicit, the agent may infer meaning from column names and past prompts. That is not a control.
Core idea: Semantic contracts make meaning inspectable before consumers turn it into behavior.
The ODI architecture
Open Data Infrastructure should keep semantic contracts close to catalogs, lineage, and policy. The semantic layer can define metrics and entities, but the broader platform needs to preserve those definitions when data moves across engines and consumers.
That is the hub-and-spoke pattern for meaning. BI tools, data product APIs, and agent tools can consume the same semantic contract instead of rebuilding meaning in separate corners of the stack.
What breaks first
- Metric definitions change without a semantic version or consumer notice.
- BI tools and agent tools use different definitions for the same business term.
- Policy context is defined for tables but not for semantic entities or metrics.
- Examples drift away from the current contract and teach agents stale behavior.
Questions to ask
Ask which definitions are contractual, which consumers depend on them, and how changes are reviewed. Ask whether semantic contracts include policy, freshness, examples, and lineage context.
For adjacent context, read dbt Core semantic layer and open catalog boundaries, data product versioning, and data modeling for tool-calling agents.
Sources to start with
These primary sources anchor the technical claims in this guide.
- dbt semantic models documentation
- dbt exposures documentation
- DataHub documentation
- OpenLineage documentation
The semantic contract is where meaning stops being tribal knowledge and starts becoming infrastructure.