Best Practices: Semantic Data Model

Semantic data models give AI agents the domain context they need to produce reliable results. What should they contain, and how are they used in AI-Driven Development projects?

What Are Semantic Data Models?

Semantic data models are structured representations of data and its meanings within a given domain. They describe the entities, attributes, relationships, and rules required to understand and use the data. Common synonyms include “conceptual (data) model”, “business data model”, “information structure”, or “information model”. Semantic data models are independent of technical implementation and focus on the business semantics of the data.

The need for such models was recognized as early as the 1970s. In 1976, Peter Chen introduced the Entity‑Relationship model, emphasizing that it captures important semantic information about the real world. In the ANSI three‑schema architecture, the conceptual/semantic data model forms the top layer, followed by the logical model that defines structures for a specific DBMS, and the physical model for storage.

Semantic models can — and should — also be used in “classic” software development projects. In my experience, they are used far too rarely because the focus is usually on implementation rather than modeling. Many developers don’t see the value, consider them too much effort, and ultimately ignore them. The perceived benefit then becomes questionable and the whole thing doesn’t seem worth it.

In the context of AI‑Driven Development, that changes fundamentally. AI agents need a clear understanding of data and its meanings to work effectively. Semantic data models provide exactly that: a common language and structure that allow agents to understand requirements, find the right data, and generate high‑quality code. Without a semantic data model, AI agents often rely on unstructured or poorly documented information, leading to misunderstandings, defects, and inefficient code. And last but not least, AI agents will not ignore semantic data models if they exist — especially if we require them to use them.

Why Are Semantic Data Models Indispensable for AI Agents?

Projects executed together with AI agents proceed in small, iterative steps. Each step is initiated by a prompt that describes the task the agent should perform. The clearer and more precise the prompt, the better the outcome. Semantic data models help achieve that clarity by providing a structured representation of data and its meanings.

A typical example is implementing a REST API that starts with the API contract. Next come the design and implementation of the endpoints, the underlying service layer with the logic, and finally persistence. Depending on the application design, the layers are decoupled via DTOs and there are several mappings between them. Without a semantic data model, it is difficult for AI agents to understand the relationships and generate the right structures. With a semantic data model, agents can recognize entities, attributes, and relationships, and derive the necessary classes, methods, and mappings — consistently, i.e., using the same names, data types, and structures, which significantly improves maintainability and extensibility.

Components of a Semantic Data Model

Typical components of a semantic data model are:

• Entities — fundamental objects of the domain (e.g., “Customer”, “Product”, “Survey”).
• Attributes — properties of entities including name, data type, cardinality (1:1, 1:n, optional/required), key information, and validation rules.
• Relationships — links between entities (1:n, n:m, aggregation, generalization, etc.).
• Security and data‑protection aspects — indication of personal or GDPR‑relevant attributes, notes on consent and statutory retention.
• Enumerations — predefined value ranges for attributes.
• Domain rules — rules like “EndDate must be greater than or equal to StartDate”.

To be truly useful for AI agents, a semantic data model should be available in a machine‑readable format. Text‑based formats such as Markdown are ideal because they can be embedded into prompts. Diagrams (e.g., with Mermaid) help with comprehension but should always be accompanied by textual descriptions. A complete semantic data model example illustrates the typical structure in Markdown.

Applying It in an AI‑Driven Development Project

The semantic data model should be created iteratively. The starting point is user stories or use cases developed by the team with the business stakeholders. AI agents can derive initial entities and relationships from these descriptions, but the team must review and refine the result. Through the dialogue between agent and team, a model emerges that both correctly reflects the business domain and is consistently structured.

It may be surprising at first that the semantic data model is stored directly in the repository, ideally in its own folder, e.g., /requirements/data_model.md. This keeps it current and accessible to all team members and AI agents. Changes to the model are reviewed and approved like any other artifact in the code‑review process. This approach may feel unfamiliar because many teams are used to maintaining requirements separately from source code, e.g., in Confluence. Business stakeholders also often shy away from Git repositories. In my experience, these concerns are easy to address with a bit of training. Many companies already have browser‑based Git clients that make onboarding easier. And Markdown is readable and editable even for business stakeholders.

Conclusion

If you adopt an AI‑Driven Development process, you should absolutely create and maintain a semantic data model. It forms the foundation for successful collaboration with AI agents and contributes significantly to the quality and maintainability of the code. A pleasant side effect is that creating the model helps the team develop a deeper understanding of the domain and requirements — which leads to better decisions and, ultimately, to more successful project delivery.