Open semantic specification

Semantics as Code

Define once. Govern everywhere.

An open, vendor-neutral specification, starter kit, and enterprise blueprint for making business semantics version-controlled, testable, portable, and deployable.

Get Started Explore Specification View on GitHub

Current reference version: v1.1.0

Business Meaning

Defined as YAML

Validated in Git

Generated for Platforms

Consumed by BI, Governance, Data, and AI

Problem

Everything became code except business meaning.

Infrastructure, pipelines, policies, APIs, and observability have become code-first. Business meaning still lives across spreadsheets, decks, BI models, wikis, catalogs, source documentation, and tribal knowledge.

That fragmentation creates conflicting definitions, duplicated metrics, semantic drift, lock-in, inconsistent AI answers, and governance friction.

Solution

Author semantics once, then validate, review, document, and generate.

Semantics as Code treats business entities, metrics, relationships, ownership, quality, and AI context as portable YAML definitions.

From YAML definitions to governed platform artifacts

YAML Definitions

Validation and Linting

Git and CI/CD

Generators and Adapters

BI, Data Platforms, Governance, Knowledge Graphs, AI

Model

What can be modeled

The implemented schema set covers the core objects needed for enterprise semantic authoring.

Domains

Business areas such as Finance, Sales, Supply Chain, or Loyalty.

Entities

Canonical business concepts such as Customer, Order, Product, Supplier, Store, or Region.

Metrics

Governed calculations with formula, grain, filters, dimensions, ownership, and quality context.

Glossary Terms

Shared definitions, synonyms, related objects, and stewardship metadata.

Relationships

Connections between entities and semantic objects for reasoning and diagrams.

Quality Expectations

Business-level quality rules attached to entities and metrics.

Governance Metadata

Owners, stewards, lifecycle status, classification, PII flags, and tags.

AI Context

Plain-language guidance that helps AI systems interpret semantic definitions correctly.

Starter kit

Start with schemas, templates, examples, validation, and CI/CD.

Teams can begin with JSON Schemas, YAML templates, reference domains, CLI commands, validation rules, generated documentation, and architecture blueprints.

Implemented outputs

markdown: index.md, domains.md, entities.md, metrics.md
html: index.html
mermaid: semantic-graph.mmd
dbt: semantic_models.yml
openmetadata: openmetadata.json
ai-context: ai-context.json, ai-context.md
knowledge-graph: knowledge-graph.jsonld, knowledge-graph.ttl
databricks: databricks_metric_views.yml

Vendor neutral

A neutral source of semantic truth above platforms

Semantics as Code does not replace Databricks, Snowflake, Fabric, dbt, OpenMetadata, BigQuery, knowledge graphs, or AI context systems. It gives them a portable source model to consume or generate.

Databricks

Generated artifact or documented adapter target from the reference implementation.

Snowflake

Generated artifact or documented adapter target from the reference implementation.

Microsoft Fabric

Generated artifact or documented adapter target from the reference implementation.

dbt

Generated artifact or documented adapter target from the reference implementation.

OpenMetadata

Generated artifact or documented adapter target from the reference implementation.

BigQuery

Generated artifact or documented adapter target from the reference implementation.

Knowledge Graphs

Generated artifact or documented adapter target from the reference implementation.

AI Context

Generated artifact or documented adapter target from the reference implementation.

Apache Metadata

Generated artifact or documented adapter target from the reference implementation.

Quick start

Run the reference implementation locally

pip install -e ".[dev]"
semantics validate examples/supply-chain
semantics lint examples/supply-chain
semantics generate examples/supply-chain --target html --output dist/html
semantics generate examples/supply-chain --target mermaid --output dist/diagrams
semantics generate examples/supply-chain --target databricks --output dist/databricks
semantics diff --base examples/supply-chain --head examples/retail
python -m pytest

YAML examples

Real semantic definitions from the repository

id: customer
kind: entity
name: Customer
display_name: Customer
description: Organization or individual that purchases products through a sales order.
business_key: customer_id
owner: Sales Operations
steward: Data Governance
domain: Sales
version: 0.1.0
status: active
classification: Confidential
pii: true
canonical_table: gold.customer
relationships:
  - Order
  - Region
synonyms:
  - Client
  - Buyer
business_rules:
  - customer_id cannot change after creation.
  - inactive customers are retained for seven years.
quality:
  - customer_id completeness > 99%
knowledge_graph: Customer
ai_context: Represents the buying party for sales, revenue, shipment, and service analysis.
extensions: {}

id: revenue
kind: metric
name: Revenue
display_name: Revenue
description: Recognized revenue for completed customer orders net of returns and credits.
formula: SUM(net_sales_amount)
grain: Order
owner: Finance
steward: Data Governance
domain: Finance
version: 0.1.0
status: active
classification: Confidential
dimensions:
  - Customer
  - Product
  - Region
filters:
  - order_status = 'Completed'
quality:
  - reconciles with ERP revenue ledger.
synonyms:
  - Net Sales
glossary_terms:
  - Recognized Revenue
ai_context: Use this metric for financial revenue analysis after order completion.
extensions: {}

id: customer-orders
kind: relationship
name: Customer Orders
display_name: Customer Orders
description: A customer can place many sales orders.
from: Customer
to: Order
relationship_type: one_to_many
owner: Sales Operations
domain: Sales
version: 0.1.0
status: active
extensions: {}

id: revenue-reconciliation
kind: quality_expectation
name: Revenue Reconciliation
display_name: Revenue Reconciliation
description: Revenue metric must reconcile to the finance ERP revenue ledger.
target: Revenue
expectation: monthly revenue variance against ERP ledger < 0.5%
severity: critical
owner: Finance
steward: Data Governance
domain: Finance
version: 0.1.0
status: active
extensions: {}

id: recognized-revenue
kind: glossary_term
name: Recognized Revenue
display_name: Recognized Revenue
definition: Revenue that has met accounting recognition criteria for completed customer orders.
owner: Finance
steward: Data Governance
domain: Finance
version: 0.1.0
status: active
classification: Confidential
synonyms:
  - Net Sales
related_objects:
  - Revenue
extensions: {}

Architecture

Semantic lifecycle for enterprise teams

From domain experts to platform artifacts

Business Users and Domain Experts

Semantic YAML Specification

Git, Pull Requests, Validation, Linting, Diff

Generators and Adapters

Databricks, Snowflake, Fabric, dbt, OpenMetadata, BigQuery

BI, Governance, Knowledge Graph, AI Agents

Comparison

Positioning among adjacent tools

Semantics as Code is not another runtime or catalog. It is an implementation-neutral authoring specification, starter kit, and generation layer.

Capability	Semantics as Code	OpenMetadata	dbt Semantic Layer	Databricks Metric Views	Snowflake OSI	LookML
Business glossary	Yes	Partial	Partial	No	Partial	Yes
Git-first authoring	Yes	Partial	Yes	Partial	Partial	Yes
Runtime execution	No	Catalog platform	Metric runtime	Platform feature	Interchange	BI runtime
Vendor neutrality	Yes	Broad but platformed	Partial	No	Yes	No
Starter templates	Yes	Limited	Limited	No	No	Limited
Multi-platform generation	Yes	No	No	No	Interchange-focused	No

Deploy business meaning as code.

Explore the specification, clone the starter kit, and contribute portable semantic definitions.

Explore the specification Clone on GitHub Contribute

Top