Semantic layer definition
A semantic layer is a shared, machine-readable description of what data or content actually means: the entities, fields, relationships, and definitions that sit between raw storage and the tools that consume it, so every query, report, application, or AI system interprets the same terms the same way.
A semantic layer is the translation between how information is stored and what it means, mapping raw tables, fields, or documents onto named business concepts that people and machines can both use. In Sanity, that mapping starts in the schema: content is modeled as typed documents with named fields and explicit references, so a query, a frontend, or a language model reads meaning from the structure instead of guessing it from rendered markup.
A semantic layer solves the problem of the same word meaning different things in different systems. One team's "active customer" counts anyone with a login in the last 90 days, another counts anyone with a paid invoice, and a third counts anyone in the CRM. Nobody is wrong, but the numbers never match, and the argument about whose number is right consumes the meeting.
The layer fixes this by defining the concept once, in a place every tool reads from. Active customer gets a name, a definition, a formula or a field, and an owner. Dashboards, exports, APIs, and AI assistants all resolve the term through that single definition, not by each reimplementing it.
The same problem shows up in content. A page might say a product is "discontinued" in a paragraph of body copy, while the ecommerce system says it is out of stock and the support site says it is legacy. Without a semantic layer, the only way to reconcile those is a human reading all three.
A semantic layer works by sitting between storage and consumption, and by exposing named concepts instead of raw structures. It typically does four things.
First, it names the entities that matter: customer, order, product, article, region. Second, it defines the attributes and metrics that belong to each entity, including how each one is calculated and what unit it is in. Third, it declares the relationships between entities, so a tool knows an order belongs to a customer and a translation belongs to a source document. Fourth, it enforces those definitions at query time, rewriting a request for a named concept into whatever the underlying storage actually requires.
The important property is that the definitions are data, not documentation. A spreadsheet of agreed metric definitions is a glossary. A semantic layer is a glossary that queries run through, which is what keeps it true.
The difference between a semantic layer in data and one in content is what is being described, not how it works. In analytics, a semantic layer describes tables, columns, joins, and metrics, and it lives in tools like a BI platform or a metrics store. In content, a semantic layer describes documents, fields, references, and taxonomies, and it lives in the content model.
Both exist for the same reason: raw storage does not carry meaning. A database column named `st_cd` means nothing until something declares it holds a two-letter state code. A blob of HTML means nothing structurally until something declares which part is the price, which is the disclaimer, and which is the author's name.
Content has an extra difficulty. Much of it is prose, and prose resists being typed. The practical answer is to model everything that has a defined meaning as a real field (price, status, audience, region, product reference), and leave only genuine narrative as rich text, so the semantic layer covers the parts a machine needs to reason about.
AI systems need a semantic layer because a language model will answer confidently whether or not it understood the terms in the question. Ask an assistant for "last quarter's revenue in EMEA" and it has to decide what counts as revenue, when the quarter ended, and which countries are in EMEA. Without a semantic layer, it infers all three, and an inference that is wrong looks exactly like one that is right.
With a semantic layer, those terms resolve to definitions the organization has already agreed on. The model is not asked to invent meaning, only to select the correct named concept and pass the query through.
The same logic applies to retrieval. A retrieval system that indexes rendered pages sees text and has to recover meaning from it. A retrieval system reading structured content already knows which field is the summary, which is the effective date, and which document supersedes which, so filtering and grounding become lookups, not guesses.
Building a semantic layer starts with the terms people already argue about, not with a complete ontology. In our experience, projects stall when they try to model everything before shipping anything.
A workable sequence is this. One, list the ten to twenty terms that appear in reports, briefs, or product copy and mean slightly different things to different teams. Two, write a single definition for each, with a named owner who can settle disputes. Three, turn each definition into something a machine reads: a typed field, a controlled list of allowed values, a reference to another entity, or a metric expression. Four, make the consuming systems resolve the term through that definition, not by reimplementing it. Five, add validation so content or data that violates a definition fails before it is published, instead of after someone notices.
The last step is the one that decides whether the layer survives. A definition that is only enforced by good intentions drifts within a release or two. A definition enforced by schema validation, required fields, and typed references stays accurate because the system will not accept anything else.
Explore Sanity Today
Understanding semantic layer is just the beginning. Take the next step and discover how Sanity can enhance your content management and delivery.
Last updated: