Semantic Model Specification Template (Metrics Layer)

Semantic Model Specification: [Model name]

Specification of one governed semantic model (metrics layer): the datasets and entities it covers, relationships and join keys, dimensions and time grains, measures and aggregations, metrics by type, default filters, access rules, owners, certification, tests, change control and export to an open interchange format. Concepts are aligned with dbt MetricFlow (Apache License 2.0, release v0.213.0 of 2026-09-10) and kept tool-neutral; Apache Ossie (incubating), formerly Open Semantic Interchange, is named as an emerging draft interchange format. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

• 1. Purpose and scope
• 2. Model overview
• 3. Datasets and entities
• 4. Relationships and join keys
• 5. Dimensions and time grains
• 6. Measures and aggregations
• 7. Metrics
• 8. Filters and default constraints
• 9. Access rules
• 10. Ownership and certification
• 11. Tests and validation
• 12. Change control and versioning
• 13. Consumers and interchange
• 14. Traceability matrix
• 15. Glossary and references

1. Purpose and scope

The [Orders] semantic model gives every consumer one governed way to ask questions about orders, revenue, customers and products at Corvid Commerce (Example). Once certified, dashboards and notebooks must query revenue and order metrics through this model rather than writing their own SQL against the marts.

Questions the model must answer (Example):

1. What were net revenue and order count by region and channel last fiscal month, compared with the same month last year?
2. What is average order value by customer segment over a rolling 90 days?
3. What share of orders were refunded within 30 days of purchase?

2. Model overview

3. Datasets and entities

Every dataset must be a public mart with an enforced contract (see rule DBT-051 in dbt Project Standard, data/dbt-project-standard), or a table covered by a Data Contract (data/data-contract).

Column lineage to the Orders data contract (Example): fct_orders keeps order_id, customer_id, channel, net_amount, currency and ship_country with the contract names. The contract's order_ts is renamed ordered_at in staging under rule DBT-013 of dbt Project Standard; the meaning (time the order was confirmed, UTC) is unchanged. The deprecated region_code is not used; the region is derived from ship_country (DIM-04).

Entities are the keys that identify business objects and allow joins. Use the four entity roles below; most semantic engines distinguish them in the same way.

customer_id is a pseudonymous key (classified Confidential with the PD and PSEUDO flags in the Orders data contract); the semantic model never exposes names, e-mail addresses or other direct identifiers, and does not offer customer_id as a dimension.

4. Relationships and join keys

Rules:

• SEM-001 Allow only many-to-one and one-to-one joins toward a primary or unique entity. A many-to-many path must be resolved by a bridge dataset with its own grain, documented here.
• SEM-002 Limit join depth to [2] hops (Example); beyond that, build a mart.
• SEM-003 State the join type explicitly; never rely on an engine default.
• SEM-004 For dimensions that keep history, state whether metrics use the value at event time or the current value. Default (Example): the value at event time for region, the current value for customer segment.

5. Dimensions and time grains

Dimensions are either categorical (labels to group and filter by) or time (dates and timestamps that roll up to coarser grains).

Time rules:

• SEM-010 Define one metric time per measure (the aggregation time dimension). Consumers asking for "revenue by month" get months of that time dimension unless they choose another.
• SEM-011 Store timestamps in UTC; derive local or fiscal periods through a calendar dataset, not through per-query conversions.
• SEM-012 Declare the smallest grain each time dimension supports. Consumers may roll up to coarser grains only.
• SEM-013 Define the fiscal calendar once (Example: fiscal year starts 1 February, weeks start Monday, ISO week numbering) and expose fiscal grains as separate dimensions.

6. Measures and aggregations

Measures are the base aggregations of a column or expression. Some engines declare them separately; from dbt v1.12 the dbt semantic layer expresses them as simple metrics (type: simple with agg and expr) instead of a separate measures list. Either way, list them here, because every other metric type is built from them. On an engine without separate measures, each row below becomes a simple metric, usually hidden from consumers when it is only an input.

• SEM-020 Every monetary measure states its currency in the name and the conversion rule in the description (Example: converted to EUR at the daily reference rate of the order date).
• SEM-021 Mark non-additive and semi-additive measures; dashboards must not total them across the non-additive dimension.
• SEM-022 Percentile and median measures state whether they are exact or approximate on the engine in use.

7. Metrics

Metric types follow the five types used by MetricFlow; most semantic layers support equivalents.

Net revenue (MET-REV-001) is the governed metric that the Orders data contract names for its measure total_net_amount: the sum of net_amount (order value after discounts, before tax and shipping) for confirmed orders that are not cancelled. This model implements it as a simple metric over MEA-06, converted to EUR with the SEM-020 rule, so a question about "net revenue" gets the same answer from the contract's verified statement, from SQL on the mart and from the semantic layer. Refunds are reported separately (MET-REV-006) and are not deducted from net revenue. Gross revenue less discounts at line grain must equal net revenue at order grain (TST-07). Derived and ratio metrics take metrics as inputs, never measures; that is why discounts and customers appear as hidden simple metrics.

Rules:

• SEM-030 Every certified metric has exactly one Metric Definition (data/metric-definition) with the same ID. The definition owns the business meaning; this specification owns the implementation.
• SEM-031 Compute ratios from aggregated numerator and denominator, never by averaging row-level ratios.
• SEM-032 Labels are unique across all certified models.
• SEM-033 Derived metrics with time offsets state how missing prior periods are shown (Example: null, never zero).

Engine-neutral sketch of one ratio metric (Example):

metric:
  id: MET-REV-003
  name: average_order_value
  label: Average order value
  type: ratio
  numerator: net_revenue
  denominator: orders
  unit: EUR
  certified: true
  owner: "@commerce-analytics"
  definition: data/metric-definition MET-REV-003

Translate the sketch into the syntax of your engine; property names differ between engines and releases.

8. Filters and default constraints

• SEM-040 Model-wide filters are applied in the marts, not in the semantic layer, so that SQL users get the same rows. Metric-specific filters live on the metric.
• SEM-041 Every filter appears in the Metric Definition of each affected metric (section "Filters and exclusions" of that template).

9. Access rules

• SEM-050 Enforce row-level rules in the data platform (row access policies) or in a semantic layer that every consumer must use; record where in this table.
• SEM-051 Apply a minimum group size of [10] customers (Example) to any metric broken down by customer attributes, to limit re-identification from small cells.
• SEM-052 Identity and role mapping follow IAM Solution Design (security/iam-solution-design).

10. Ownership and certification

Certification criteria (all required):

1. The metric has an approved Metric Definition with the same ID.
2. Every input dataset is a contracted public mart.
3. Tests in section 11 pass for [14] consecutive days (Example).
4. The value reconciles with the agreed reference (section 11, TST-04).
5. Access rules in section 9 are implemented and tested.
6. Owners are named and reachable.

Certification lasts [12 months] (Example) or until the logic changes, whichever comes first. Decertify a metric when its owner leaves without a successor or when reconciliation fails twice in a row.

11. Tests and validation

Monitor data quality thresholds from Data Quality Standard (data/data-quality-standard); this section adds the tests that are specific to the semantic layer.

12. Change control and versioning

• SEM-060 Keep a deprecated metric available, labelled as deprecated, for the notice period, and point it to its replacement.
• SEM-061 Version this document with every certified change and list affected metrics in the revision history.
• SEM-062 Record lineage from metrics to marts to sources in the data catalogue so impact analysis is possible before a change.

13. Consumers and interchange

Interchange:

• Keep the model as code in version control, in the native format of the semantic engine, as the source of truth.
• Where consumers use another tool, export rather than retype. Apache Ossie (incubating), formerly Open Semantic Interchange, is an emerging vendor-neutral specification for exchanging semantic models (datasets, relationships, fields and metrics) between analytics, BI and AI tools. As of October 2026 its core specification is a draft (0.2.0.dev0) with no formal release, and dbt can already read Ossie documents as an alternative to its native semantic model YAML. Check its maturity at https://github.com/apache/ossie before relying on it.
• Record the export format, version and the tools tested:

14. Traceability matrix

15. Glossary and references

References:

• dbt MetricFlow, v0.213.0 (2026-09-10), Apache License 2.0 from v0.209.0: https://github.com/dbt-labs/metricflow
• dbt documentation on semantic models and metrics (entity roles, dimension types, metric types; the spec that replaces measures with simple metrics applies to dbt v1.12 and later): https://docs.getdbt.com
• Apache Ossie (incubating), core metadata specification 0.2.0.dev0, draft: https://github.com/apache/ossie
• Related templates: Metric Definition (data/metric-definition), Analytics and BI Solution Design (architecture/analytics-bi-solution-design), Dashboard Specification (data/dashboard-specification), Data Dictionary (architecture/data-dictionary), Data Platform Architecture (architecture/data-platform-architecture), dbt Project Standard (data/dbt-project-standard), Data Contract (data/data-contract).

Standard and licence note

Structure aligned with the semantic modelling concepts of dbt MetricFlow (Apache License 2.0, https://github.com/dbt-labs/metricflow) and with the concept names of the Apache Ossie (incubating) draft core specification (Apache License 2.0, https://github.com/apache/ossie). Only concept and type names are used; no specification text, schema or documentation prose is reproduced, and the Corvid Commerce example is fictional. Ossie is a draft and may change. dbt and MetricFlow are trademarks of dbt Labs, Inc., and Apache and Apache Ossie are trademarks of The Apache Software Foundation; this template is not affiliated with or endorsed by them. This template is original text written for this collection. Check the current official versions before use. Template licence: MIT.