What Is a Semantic Model?

---

A semantic model is a machine-readable description of what your data means: which datasets exist, how they join, and which metrics, dimensions, and synonyms people use. The open Apache Ossie spec, whose latest release is 0.1.1, writes one in YAML or JSON. In Atlan, each context repository carries one, linked to the governed assets it describes.

---

The phrase means one thing to a knowledge engineer and another inside a BI tool. Here it means the analytics sense: what an agent reads before it writes SQL, and what a semantic layer serves to every tool.

With an open format in place, the harder question is who answers for each metric, synonym and join. In Atlan’s Context Engineering Studio, which your Atlan account team makes available and an admin turns on in Atlan Labs, source-owned fields such as descriptions are edited at the source, and repo-defined fields, “such as names, expressions, relationships, and derived metrics, are edited directly in the model.” The model lives in a context repository, the unit of context engineering an agent reads.

Question	Answer	Source
What is it?	A structured description of business data: datasets, field meanings, relationships, metrics	Apache Ossie docs
What is it built from?	Datasets (a primary key is optional in the spec), fields, dimensions (including time), metrics, relationships, synonyms, instructions	Apache Ossie home; 0.1.1 schema
Is there an open spec?	Apache Ossie, formerly Open Semantic Interchange (OSI); JSON- and YAML-based	Apache Ossie README
Current released version	0.1.1, listed as the initial release (2025-12-11); main is a 0.2.0.dev0 draft, not for production; no 1.0 release	Core Metadata Specification
Who runs the spec?	Undergoing incubation at the Apache Software Foundation; more than 50 participating organizations (post dated 2026-07-10)	Apache Ossie update, July 2026
Who should own each definition?	A business person accountable for decisions in that domain	DAMA DMBOK Revision
What the core fields do not record	Who owns or approved a definition	Core Metadata Specification
What definitions do not enforce	Who may see which rows; exact definitions without an access policy still leaked data in one preprint	GROUND preprint, 2026

Status as of November 3, 2026.

---

What are the different meanings of “semantic model”?

The term “semantic model” names more than one thing, so it pays to say which sense you mean.

In knowledge representation, a semantic model is formal meaning on the web. According to the W3C (2012), OWL 2 is “an ontology language for the Semantic Web with formally defined meaning,” built from classes, properties, individuals and data values. That is the ground under any ontology or knowledge graph.

In analytics, it is a structured description of business data. The Apache Ossie docs define it as one that says “what datasets exist, what their fields mean” and how datasets relate. That is the sense a semantic layer for analytics and an AI agent both read.

Sense	What “semantic model” means there	Built from	Open definition
Knowledge representation	Formal meaning across systems: things, their types and their labels	Classes, properties, individuals, labeled concepts	OWL 2 (W3C, 2012), SKOS (W3C, 2009), RDF 1.1 (W3C, 2014)
Analytics and AI agents	A structured description of business data that a query can compute from	Datasets, fields, dimensions, measures or metrics, relationships, synonyms	Apache Ossie, RDF Data Cube (W3C, 2014)

The analytics sense echoes knowledge representation. According to the W3C SKOS Reference (2009), concepts can be “labeled with lexical strings in one or more natural languages.” An analytics model keeps a plainer version: a list of synonyms for a metric or field. Each one is a decision about what your company’s words mean.

---

What is inside a semantic model?

An analytics semantic model declares a few kinds of thing, each a claim about your business. Datasets come first, and each should declare a primary key (the spec makes it optional). Fields say what columns mean.

Dimensions are fields you group by, with time dimensions marked. Metrics carry an expression, and relationships say how datasets join. Ossie’s site describes the top-level container as “a complete model with datasets, relationships, and metrics.”

None of this is new vocabulary. According to the W3C RDF Data Cube Vocabulary (2014), “a cube is organized according to a set of dimensions, attributes and measures.” What is newer is the part written for AI readers: synonyms and instructions, which Ossie stores in ai_context.

Each part overlaps something you maintain already. Metrics overlap a metrics layer, descriptions a business glossary, and instructions the wider business context an agent needs. The model is where those pieces become computable, so a wrong expression in it turns into a wrong answer at query time.

Part	What it says	In the worked example
Dataset and primary key	Which table is in scope, what one row is, and what makes a row unique	customers, one row per account, keyed on customer_id; invoices, one row per invoice, keyed on invoice_id
Field	What a column means and how to read it	region reads billing_region
Dimension (time)	A field to group or filter by; time fields are marked	invoice_date with is_time: true, described as a calendar date
Metric	A calculation with its exclusions	net_revenue: amount minus refunds, skipping test accounts flagged by is_test_account
Relationship	How two datasets join	invoices_to_customers on customer_id
Synonyms (ai_context)	The words people use for a dataset, field or metric	“territory” and “geo” for region
Instructions	Rules for an AI reader that no single field holds	“Use net_revenue for any revenue question”

What does a semantic model look like in an open spec?

Here is a two-dataset model written to the Apache Ossie 0.1.1 JSON Schema, the latest released version. The 0.1.1 JSON Schema requires version: "0.1.1" and a semantic_model array, and this example validates against it.

version: "0.1.1"
semantic_model:
  - name: subscription_revenue
    description: Recurring revenue from customer subscriptions, for finance and sales questions
    ai_context:
      instructions: "Use net_revenue for any revenue question."
    datasets:
      - name: customers
        source: finance.core.customers
        primary_key: [customer_id]
        description: One row per customer account, including internal test accounts
        ai_context:
          synonyms: ["accounts", "clients"]
        fields:
          - name: customer_id
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: customer_id
          - name: region
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: billing_region
            description: Region the customer is billed in
            dimension:
              is_time: false
            ai_context:
              synonyms: ["territory", "geo"]
          - name: is_test_account
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: is_internal_test
            description: True for internal test accounts, which no revenue metric counts
      - name: invoices
        source: finance.core.invoices
        primary_key: [invoice_id]
        description: One row per issued invoice, with line amounts already summed
        fields:
          - name: invoice_id
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: invoice_id
          - name: customer_id
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: customer_id
          - name: invoice_date
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: invoice_date
            description: Calendar date the invoice was issued
            dimension:
              is_time: true
            ai_context:
              synonyms: ["billing date"]
          - name: amount
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: amount_usd
          - name: refund_amount
            expression:
              dialects:
                - dialect: ANSI_SQL
                  expression: refund_usd
    relationships:
      - name: invoices_to_customers
        from: invoices
        to: customers
        from_columns: [customer_id]
        to_columns: [customer_id]
    metrics:
      - name: net_revenue
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: >-
                SUM(CASE WHEN customers.is_test_account THEN 0
                ELSE invoices.amount - invoices.refund_amount END)
        description: Invoiced amount minus refunds, in USD, excluding internal test accounts
        ai_context:
          synonyms: ["revenue", "net sales"]

Three lines in that 0.1.1 example carry most of the risk. The net_revenue expression decides whether refunds count and drops test accounts through the is_test_account field, so every consumer that runs the expression applies the same exclusion. The region synonyms decide what “territory” means. The one instruction only steers an LLM reader toward net_revenue; it binds no other consumer, which is why the exclusion lives in the expression. Nothing in the file says who approved any of the three.

The schema check also misses grain. invoices declares one row per invoice and a key of invoice_id, and the schema accepts that claim as written. Only a uniqueness test on the real table shows it holds.

The spec’s in-development 0.2.0 changes the shape: “each standalone document contains one model directly at the root; the semantic_model array is removed.” The same page says of that draft, “do not depend on this version in production.” Version labels have moved before: the first published spec carried a 1.0 label until a March 9, 2026 commit titled “Version change from 1.0 to 0.1.1.” An open format makes it easier to move definitions between tools, approved or not.

---

How is a semantic model different from a semantic layer, an ontology, or a schema?

Several neighboring artifacts get confused with a semantic model, and each has a different job. The model is the definitions you author; the system that serves them is covered in semantic layer vs data model, and storage versus meaning in ontology vs data model.

Two more boundaries trip teams up. One is whether an ontology is just another word for a semantic model; the other is where a semantic layer vs data catalog line falls. Conceptual, logical and physical design belong to data modeling.

What a semantic model is not	The difference in one line
Physical schema	The schema stores rows; the model says what they mean and how to compute from them
Semantic layer	The layer is the system that serves and applies definitions; the model is the definitions
Ontology	An ontology formalizes classes and properties across systems; an analytics model computes measures for one scope
Data catalog	The catalog inventories and describes assets; the model defines calculations over a subset of them
Business glossary	The glossary defines terms in words; the model makes them computable

The boundary is moving. According to the Apache Ossie project (2026), “Ossie is an open specification for both semantic layer and ontology,” and its repository ships an ontology specification beside the core one. The ontology and semantic layer split still describes how most teams divide the work.

---

Why do AI agents need a semantic model?

Agents writing SQL struggle on enterprise data, and business context helps, up to a point. Every study below is an arXiv preprint: one team’s result in one setting.

According to the Spider 2.0 authors (v2, March 2025), their code agent framework “successfully solves only 21.3% of the tasks, compared with 91.2% on Spider 1.0 and 73.0% on BIRD.” That shows how hard real enterprise text-to-SQL workflows are, without isolating what a semantic model adds.

In one drug-safety database study with an LLM (2024, 60 test questions), accuracy rose “from 8.3% with the database schema alone to 78.3% with the business context document.” That document held plain-language descriptions of the data, the content a semantic model encodes, though not a model in the spec sense. A 2026 preprint gave three models 100 questions with and without a 4 KB hand-written document of measures and conventions; adding it “improves accuracy by +17 to +23 percentage points across all three models.” Both argue against raw text-to-SQL as a route to AI agent accuracy.

The limits matter just as much. On the EntSQL benchmark, with English inputs, “the best evaluated system reaches only 15.9% when long-form documents are provided” (2026). Documents more than doubled the best system’s score, from 6.8%, and targeted evidence did better still, at 21.4%.

A 2026 preprint built on a 100-question synthetic benchmark found that “a semantic-only condition with exact metric definitions but no access policy still leaks data,” so access control for AI agents is a separate job. Agents also read a model differently from BI tools, and not all alike: a 2026 study of data agents found each context technique paid off only for the behavior it matched, and for investigating agents “the semantic layer stops them from looking.”

Study (arXiv preprint)	Setting and what the agent was given	Finding	What it means for your model
Spider 2.0, v2 17 Mar 2025	Real enterprise text-to-SQL workflows	Best agent framework tested solved 21.3%, against 91.2% on Spider 1.0 and 73.0% on BIRD	Enterprise workflows are hard; semantics are not isolated as the cause
Pharmacovigilance SQL, v3 4 Sep 2024	One drug-safety database, 60 questions; a plain-language business context document	8.3% with the schema alone, 78.3% with the document	A plain-language context document carried the gain
Semantic layers benchmark, submitted 28 Apr 2026	100 questions, three frontier models; a 4 KB hand-written semantic document	+17 to +23 points with the document; 67.7 to 68.7% with it, 45.5 to 50.5% without	The semantic document mattered more than the choice of model
EntSQL, v3 14 Jul 2026	Enterprise benchmark, English inputs; long-form documents or targeted evidence	Best system 6.8% with no documents, 15.9% with documents, 21.4% with evidence	Targeted evidence beats whole documents
GROUND, submitted 6 Jul 2026	100-question synthetic enterprise-reporting benchmark	Exact metric definitions without an access policy still leaked data	Access rules need their own enforcement
Same Context, Different Agents, v2 22 Oct 2026	Data agents with different working styles	A semantic layer can stop investigating agents from looking	Test the model with your own agent

A semantic layer for AI agents helps only as far as its definitions are owned and tested.

---

Who should own a semantic model?

Each definition in a semantic model encodes a business decision, so each needs someone who answers for it. According to DAMA International’s 2024 revision of the DMBOK, the data owner is now defined as “a business person accountable for decisions within a domain.” So finance answers for what net_revenue means, whoever typed the YAML.

Ownership only works if each definition exists once. Two agents carrying their own net_revenue will drift apart, the failure a semantic model exists to prevent. Keep one shared, owned definition per concept and scope each agent to the subset its job needs. If finance and sales need different numbers, give each a named metric and owner, not one name with two formulas.

Ossie’s core model-level fields cover version, name, description, ai_context, datasets, relationships, metrics and custom extensions. None of them records who owns or approved a definition, and the 0.1.1 schema has none either. Extra attributes can go in custom_extensions (“Vendor-specific attributes for extensibility,” in the spec’s words), and the project’s roadmap lists governance and certification frameworks as planned work. Ossie’s own docs advise: “Define who owns each semantic model and who is responsible for approving changes.”

Atlan’s Context Engineering Studio splits edits by field. Descriptions stay owned by the source asset while names, expressions, relationships and derived metrics are edited in the model, and “the linked glossary term supplies the certified definition.” Synonyms come from the asset’s display name or AI alias, and mined joins and filters are corrected on the source asset’s Usage & Intelligence tab. Settle who owns the context layer the way teams handle KPI definitions and a business glossary or data contracts.

Field type	Edited where	Accountable person (recommended)
Description (source-owned)	The source asset	The asset’s owner
Metric expression and derived metrics (repo-defined)	The model	The metric’s business owner
Synonyms	The asset’s display name or AI alias, at the source	The asset’s owner
Mined joins and filters	The source asset’s Usage & Intelligence tab	The asset’s owner
Certified definition	The linked glossary term	The term’s owner

Edit locations come from Atlan’s docs; the accountable person is a recommendation built on the DAMA definition. An owner gives a dispute somewhere to go. Testing is how you find out whether the definition is right.

---

What goes wrong with semantic models, and how do you fix it?

Semantic models fail in ways a schema check cannot see: a valid file proves the YAML parses, not whether refunds belong in revenue.

They tend to surface after launch, as context drift or an answer nobody can trace, so each needs a test you can repeat when evaluating an AI agent.

Failure	What happens	Fix
Format mistaken for truth	A schema-valid file is assumed correct, though the core spec has no approval field	Keep validation, owner approval and answer testing as three separate gates
Over-broad scope	Many tables bring “more competing definitions of the same word”	Scope each agent to the definitions its questions need; keep the definitions themselves shared
Silent drift	Source columns or descriptions change after the model was built	Watch upstream changes since the last build and review on change
Documentation dumped in bulk	Long documents help, but accuracy stays low	Pass the definitions the questions need, then test the answers
Metric right, access wrong	Exact definitions without a policy still leak data	Enforce row and column policy at query time
Model suppresses data inspection	A semantic layer can stop investigating agents from looking	Test with your own agent; do not assume every agent gains
No owner	Nobody can settle which definition wins	Name a business owner per definition
Unmodeled questions	The model cannot answer what it does not contain	Grow coverage from a test set of real questions

---

How do you know a semantic model is ready for AI agents?

Run these twelve checks on your semantic model, its entities, measures, time fields and owners, before an agent reads it. It is not ready if any of SM-01, SM-02, SM-03, SM-04, SM-05, SM-08, SM-09 or SM-11 fails. It is ready with gaps if only SM-06, SM-07, SM-10 or SM-12 fail, and ready when all twelve pass. The blocking set is a judgment call: each can return a wrong number or expose rows when it fails. The same checks belong in any plan for implementing an enterprise context layer.

ID	Check	Pass when
SM-01	Agent scope is a subset of shared definitions	The agent reads a named subset of shared, owned definitions, and no metric is redefined for one agent
SM-02	Every dataset has a tested key	Each dataset declares a primary key, and a uniqueness test on the real table confirms it
SM-03	Joins are declared	Every cross-dataset question has a declared relationship
SM-04	Every metric states its formula and exclusions	Exclusions every consumer must apply, such as refunds and test accounts, are in the expression; instructions only steer an LLM reader
SM-05	Time is explicit	Time dimensions are marked, and each time field states whether it is fiscal or calendar
SM-06	Every metric and entity has a description	Each one has a non-empty description
SM-07	Synonyms are your organization’s words, reviewed	Synonyms are business vocabulary, not generic paraphrases, and someone reviewed them
SM-08	Every definition has an accountable business owner	A named owner per metric or entity, recorded outside the core fields if the format has no slot
SM-09	Tested against real questions	Real questions, with answers the metric’s owner approved, run before each change ships, kept apart from examples the agent is shown
SM-10	Drift is watched	Upstream changes since the last build are visible and trigger a review
SM-11	Access is enforced at query time	Row and column policies are enforced at query time, not assumed from metric definitions
SM-12	Portable format	The model can be written in an open spec, or the gap is known

---

How Atlan approaches semantic models in the context layer

In Atlan, the semantic model is one of two things a context repository holds: “the Atlan assets it points to, and the semantic model that says how those assets answer questions.”

The model lists tables, relationships, derived metrics, named filters, verified queries and custom instructions. Verified queries are “Question-and-SQL pairs that ground the engine in answers you’ve confirmed are correct.” For SM-09, test with a separate set, so the agent is not graded on answers it was shown.

Two choices in Atlan’s docs line up with the ownership argument. A repository is scoped to the job an agent has to do, while the linked glossary term supplies the shared, certified definition, so scope narrows without a second copy of the meaning. And an Activity tab shows what changed upstream since the last build, “so you learn about drift from the tab rather than from a wrong answer.”

Where this sits relative to semantic-layer tools is covered in context engineering vs a semantic layer, and the broader argument in why AI agents need an enterprise context layer.

Context Engineering Studio is gated behind an Atlan Labs toggle, and Atlan’s docs say it “isn’t self-serve”: your Atlan account team enables it for your tenant, then an admin turns on the toggle.

---

FAQs about semantic models

1. What is a semantic data model and what is its purpose?

A semantic data model is a structured description of business data: which datasets exist, what their fields mean, how they relate, and which metrics can be calculated. Its purpose is to make one business question resolve to one calculation for people, BI tools and AI agents alike.

2. Is a semantic model the same as a semantic layer?

No. The semantic model is the set of definitions you author: datasets, joins, metrics and synonyms. The semantic layer is the system that serves those definitions to tools and agents and applies them when a query runs.

3. Is there an open standard for semantic models?

Yes. Apache Ossie, formerly Open Semantic Interchange (OSI), is an open JSON- and YAML-based specification. Version 0.1.1, which the spec’s history dates to December 11, 2025, is the latest release. The main branch holds a 0.2.0 development draft, no 1.0 has been released, and a project post dated July 10, 2026 says Ossie is undergoing incubation at the Apache Software Foundation.

4. Does a semantic model make AI agents accurate on its own?

No. In independent preprints, business context raised text-to-SQL accuracy sharply, yet exact metric definitions without an access policy still leaked data in one 2026 study, and another found a semantic layer can stop investigating agents from looking at the data. Test the model with your own agent.

5. Who should own a semantic model?

A business person accountable for decisions in each domain should own its definitions, such as finance for revenue, while engineers maintain the file. In Atlan’s Context Engineering Studio, descriptions and synonyms come from the source asset, while expressions and derived metrics are edited in the model.

6. How large should a semantic model be?

Keep each definition shared and owned once, and scope each agent to the subset its job needs. Pulling in a whole domain’s tables brings more competing definitions of the same word. Start from the questions the agent must answer, then add the tables they need.

---

Sources

1. Apache Ossie, docs/index.md, Apache Ossie on GitHub, undated
2. Apache Ossie (incubating), Apache Ossie on GitHub, undated README
3. Home - Apache Ossie (incubating), Apache Ossie, undated
4. Apache Ossie - Core Metadata Specification, Apache Ossie on GitHub, Version 0.2.0.dev0 draft
5. OSI Core Metadata Specification (osi-schema.json at tag osi-0.1.1-rc1), Apache Ossie on GitHub, Version 0.1.1 (release-candidate tag, 19 May 2026)
6. Version change from 1.0 to 0.1.1, Apache Ossie on GitHub, commit of 9 March 2026
7. Apache Ossie Roadmap (Community-Informed), Apache Ossie on GitHub, undated
8. Apache Ossie (Incubating): The New Name for Open Semantic Interchange, Apache Ossie, July 10, 2026
9. OWL 2 Web Ontology Language Document Overview (Second Edition), W3C, 11 December 2012
10. SKOS Simple Knowledge Organization System Reference, W3C, 18 August 2009
11. RDF 1.1 Concepts and Abstract Syntax, W3C, 25 February 2014
12. The RDF Data Cube Vocabulary, W3C, 16 January 2014
13. DAMA DMBOK Revision, DAMA International, undated (2024 revision)
14. Spider 2.0: Evaluating Language Models on Real-World Enterprise Text-to-SQL Workflows, arXiv, v2 17 Mar 2025
15. Automating Pharmacovigilance Evidence Generation: Using Large Language Models to Produce Context-Aware SQL, arXiv, v3 4 Sep 2024
16. Semantic Layers for Reliable LLM-Powered Data Analytics: A Paired Benchmark of Accuracy and Hallucination Across Three Frontier Models, arXiv, submitted 28 Apr 2026
17. EntSQL: A Benchmark for Grounding Text-to-SQL in Long-Context Enterprise Knowledge, arXiv, v3 14 Jul 2026
18. GROUND: Reducing Hallucinations in LLM-Based Enterprise Analytics Through Governed Semantic Definitions, arXiv, submitted 6 Jul 2026
19. Same Context, Different Agents: A Behavioral Study of Semantic Layers, Multi-Agent Orchestration and Memory Compaction in Data Agents, arXiv, v2 22 Oct 2026
20. What’s in a context repository, Atlan Docs
21. Create your context repository, Atlan Docs
22. Enable Context Engineering Studio, Atlan Docs
23. What is Context Engineering Studio?, Atlan Docs