What is a semantic layer, and why every number should have one definition
The semantic layer explained with small-business examples: why dashboards, accounting spreadsheets and AI answers disagree, and how one versioned definition per metric fixes it.
By The DataxLand team· · 5 min read
Every weekly meeting has this moment: marketing says October revenue was 310 million, accounting says 270 million, and the owner's marketplace dashboard shows 330 million. Nobody is wrong. Each person uses a different definition of "revenue", and nobody wrote theirs down. The meeting turns into reconciling numbers instead of deciding anything.
A semantic layer solves this: one place that defines every business metric — which table it comes from, which column is added up, what is filtered, which dimensions it can be split by — and every tool that shows numbers goes through it. This post explains the idea with small-business examples; no SQL needed.
Three "revenues" in one company
| Person | Calls it "revenue" | What it actually is | Example (illustrative) |
|---|---|---|---|
| Owner | The big number on the marketplace dashboard | GMV: price × quantity, before discounts | 330 million ₫ |
| Marketing | Revenue in the ad report | Conversion value attributed by the ad platform | 310 million ₫ |
| Accounting | Revenue in the books | Net revenue: after discounts, vouchers, refunds | 270 million ₫ |
All three are correct by their own definition. The problem is that definitions live in people's heads, in each spreadsheet's formulas and in each tool's settings. Add an AI chatbot that reads raw tables and writes its own queries, and you get a fourth definition — guessed by the model, possibly different between two runs of the same question.
What a metric definition contains
| Part | Example for "profit after fees" |
|---|---|
| Name and synonyms | Profit after marketplace fees and ads; synonyms: profit, net profit |
| Formula | Contribution margin − allocated ad spend |
| Components | Contribution margin = net revenue − COGS − platform fees − payment fees − shipping − return shipping |
| Source model | Order-line profit model (orders joined with fees, cost of goods and ads) |
| Allowed dimensions | Channel, marketplace, product, category, date |
| Time grains | Day, ISO week (Monday start), month |
| Good direction | Up |
| Completeness | Reported with the share of revenue that has a cost |
| Version | 1.0.0 — a formula change bumps the version |
When a dashboard needs "profit after fees by channel for October", it does not write its own query. It asks the semantic layer for this metric, this dimension, this period. The semantic layer builds the query from the definition, runs it, and returns the number with the definition version and the data-as-of date. Scheduled reports, alerts, Si and external agents over MCP ask the same way, so they get the same number.
Why it matters more once you add AI
A common way to "talk to your data with AI" is to give a language model the list of tables and columns and let it write SQL. It demos well, but has three problems with business numbers:
- It guesses definitions. The model cannot know whether your "revenue" is GMV or net revenue, whether refunds are subtracted, how order vouchers are split. It picks something reasonable — reasonable is not the same as right.
- It is not repeatable. Ask twice, get two queries, sometimes two numbers.
- It does not match the dashboard. The chatbot and the dashboard take different paths, so when they disagree you do not know which to trust.
DataxLand takes a different route: Si does not write SQL against business data. Si can only call semantic-layer tools — pick a metric, dimensions, filters, period, comparison — and the DataxLand engine builds the query from the definition. Si's answers match the dashboard, and every answer ends with Sources: which metric, which version, which period, data as of which date. See Si.
Confirmation levels: standard, approved, unconfirmed
One definition per name does not mean nobody can add metrics:
| Level | Where the definition comes from | Example |
|---|---|---|
| Standard | Industry × department metric packs, with tests | Net revenue, contribution margin, profit after fees, true ROAS |
| Approved | Workspace-defined metrics (ws.<name>), checked against real data and enabled by someone with permission | "Profit after fees minus affiliate commission" |
| Unconfirmed | Exploratory measures when you ask something no metric covers yet | "Units sold of the gift category by province" |
Exploratory answers come back immediately, labelled "Unconfirmed". If useful, Si can propose turning one into a workspace metric — as a draft until someone approves it. Packs are a starting point, not a limit, and there are still never two definitions behind one name.
Versions: when a definition has to change
Definitions change — for example, the shop starts restocking returned goods and wants returned lines to get their cost back. Without a semantic layer someone edits a formula in a file and last month's numbers silently "change". With one:
- The new formula goes into the definition and the version is bumped (1.0.0 → 1.1.0).
- Before use, the new definition is checked against real data to see the difference. For workspace metrics, DataxLand requires this check before the metric can be enabled.
- Every answer afterwards carries the new version, so when you compare with an old report you know why the number differs.
When a small business needs one
You do not need a semantic layer if one person makes the numbers in one spreadsheet and nobody asks twice. You do when two or more of these are true:
- More than one person or tool reports "revenue" or "profit".
- Meetings spend time reconciling numbers instead of deciding.
- You want to ask an AI about your numbers but are not sure it computes them correctly.
- Reports to partners, investors or banks must explain every figure.
- An outsourced accountant or agency needs to see the same numbers you do.
What a semantic layer is not
- Not a warehouse. The warehouse stores data; the semantic layer defines how to read it as metrics.
- Not a dashboard. A dashboard is one place to display numbers; the semantic layer serves all of them.
- Not only for large companies. The concept is common in enterprise data tooling (for example the dbt Semantic Layer), but "three people, three numbers" starts the day a company has a second person making numbers.
DataxLand ships a semantic layer with standard metrics per industry and department — see the retail finance dashboard template — and lets you add your own, checked before use. Start with the DataxLand docs or read how external AI tools reach the same metrics in MCP for business metrics.