{"slug": "ersioning-business-semantics-for-enterprise-ai", "title": "ersioning Business Semantics for Enterprise AI", "summary": "A developer outlines a versioning approach for enterprise semantic layers, arguing that business metrics like Revenue need immutable, time-aware versions rather than mutable definitions so that data agents can resolve the correct meaning for historical queries. The proposed model separates metric identity from its versions, tracks both publication time and effective business time, and adds an explicit policy for whether historical queries use the definition in force at the time (\"as_was\") or today's restated definition.", "body_md": "**Your SQL can be perfectly reproducible while your business meaning is not.**\n\nSuppose a user asks:\n\nWhat was revenue in Q1?\n\nYour data agent resolves `Revenue`, generates valid SQL, executes it successfully, and returns a number.\n\nNow suppose Finance changed the definition of Revenue in June.\n\nThe old definition was:\n\n```\nRevenue v3\n=\nRecognized Revenue\n```\n\nThe new definition is:\n\n```\nRevenue v4\n=\nRecognized Revenue\n- Approved Adjustments\n```\n\nWhen the same user asks about Q1 in September, which definition should the agent use?\n\nThat is not an SQL problem.\n\nIt is a **semantic versioning problem**.\n\nEnterprise data agents need more than a mapping from:\n\n```\nBusiness Term → Metric\n```\n\nThey increasingly need:\n\n```\nBusiness Term\n      ↓\nMetric\n      ↓\nVersion\n      ↓\nEffective Time\n      ↓\nApproval State\n      ↓\nPhysical Mapping\n```\n\nIf business meaning changes over time, the semantic layer needs a lifecycle.\n\n**Why a Static Semantic Layer Breaks Down**\n\nA basic semantic registry might store:\n\n```\n{\n  \"id\": \"revenue\",\n  \"name\": \"Revenue\",\n  \"field\": \"finance_revenue.recognized_amount\",\n  \"aggregation\": \"SUM\"\n}\n```\n\nThat works until the definition changes.\n\nIf the object is simply overwritten, you lose important information:\n\n```\nWhat was the previous definition?\nWhen did the change become effective?\nWho approved it?\nWhich answers used the old definition?\nShould historical periods use the old or new logic?\n```\n\nA production semantic object should therefore be treated more like a versioned artifact than a mutable label.\n\n**Model Semantic Objects as Immutable Versions**\n\nOne useful pattern is to separate the stable identity of a business concept from its versions.\n\n```\nMetric Identity\nrevenue\n   │\n   ├── v1\n   ├── v2\n   ├── v3\n   └── v4\n```\n\nFor example:\n\n```\n{\n  \"metric_id\": \"revenue\",\n  \"version\": 4,\n\n  \"definition\": \"Recognized revenue after approved adjustments\",\n\n  \"expression\": {\n    \"type\": \"formula\",\n    \"value\": \"recognized_revenue - approved_adjustments\"\n  },\n\n  \"owner\": \"finance\",\n\n  \"status\": \"published\",\n\n  \"effective_from\": \"2026-06-01\",\n\n  \"effective_to\": null\n}\n```\n\nDo not mutate `v3` into `v4`.\n\nCreate a new version.\n\nThat preserves historical meaning.\n\n**Separate Version Time From Business Time**\n\nThis is where implementation gets interesting.\n\nThere are at least two relevant timelines.\n\nWhen was the semantic definition created or published?\n\n```\ncreated_at\npublished_at\ndeprecated_at\n```\n\nWhen is the definition supposed to apply?\n\n```\neffective_from\neffective_to\n```\n\nThese are not always the same.\n\nFinance might approve a new metric definition on June 10 but make it effective from June 1.\n\nSo a semantic object may need:\n\n```\n{\n  \"published_at\": \"2026-06-10T09:00:00Z\",\n  \"effective_from\": \"2026-06-01\",\n  \"effective_to\": null\n}\n```\n\nThis distinction is essential for historical queries.\n\n**Resolve Semantics With Time Context**\n\nA semantic resolver should not simply do:\n\n```\nmetric = registry.get(\"revenue\")\n```\n\nIt needs temporal context.\n\nConceptually:\n\n```\nmetric = registry.resolve(\n    metric_id=\"revenue\",\n    effective_at=query_time\n)\n```\n\nFor a question like:\n\nWhat was revenue in January?\n\nthe pipeline becomes:\n\n```\nQuestion\n      ↓\nIntent Resolution\n      ↓\nMetric = Revenue\n      ↓\nTime Context = January\n      ↓\nApplicable Semantic Version\n      ↓\nPhysical Mapping\n      ↓\nQuery Plan\n```\n\nThis is **version-aware semantic resolution**.\n\n**But Historical Queries Have Two Meanings**\n\nThere is an important complication.\n\nWhen someone asks:\n\nWhat was Revenue in January?\n\nthey may mean:\n\nCalculate Revenue using the definition that was valid in January.\n\nor:\n\nCalculate January data using today's Revenue definition.\n\nThese can produce different numbers.\n\nSo your semantic system may need an explicit policy:\n\n```\n{\n  \"historical_metric_policy\": \"as_was\"\n}\n{\n  \"historical_metric_policy\": \"restated\"\n}\n```\n\nIn some environments, the right answer may depend on the metric itself.\n\nIf the system cannot determine the intended policy safely, clarification may be better than silently guessing.\n\n**Comparison Queries Are Harder**\n\nNow consider:\n\nCompare Q1 and Q3 Revenue.\n\nSuppose the definition changed in Q2.\n\nIf you use each period's historical definition:\n\n```\nQ1 → Revenue v3\nQ3 → Revenue v4\n```\n\nthe comparison may not be semantically consistent.\n\nIf you restate both periods using v4:\n\n```\nQ1 → Revenue v4\nQ3 → Revenue v4\n```\n\nthe comparison is consistent, but it no longer represents exactly what the organization reported in Q1.\n\nThis decision belongs in business governance.\n\nThe LLM should not invent the policy.\n\n**Version More Than Metrics**\n\nMetrics are the obvious case, but other semantic objects can change too.\n\n```\n\"Active Customer\"\n```\n\nmay change definition.\n\n```\n\"Product Code\"\n→ product_master.material_id\n```\n\nmay later become:\n\n```\n\"Product Code\"\n→ product_dim.product_code\nRegion\nBusiness Unit\nProduct Category\nCustomer Segment\n```\n\ncan change structure.\n\n```\nValid Order\nEligible Customer\nCompleted Transaction\n```\n\ncan change inclusion logic.\n\nIf a change can alter analytical results, it should be traceable.\n\n**A Generic Semantic Version Model**\n\nYou can model semantic objects with a shared envelope:\n\n```\n{\n  \"object_id\": \"metric.revenue\",\n  \"object_type\": \"metric\",\n  \"version\": 4,\n\n  \"lifecycle\": {\n    \"status\": \"published\",\n    \"owner\": \"finance\",\n    \"approved_by\": \"finance_governance\"\n  },\n\n  \"validity\": {\n    \"effective_from\": \"2026-06-01\",\n    \"effective_to\": null\n  },\n\n  \"provenance\": {\n    \"created_at\": \"2026-05-28T08:12:00Z\",\n    \"published_at\": \"2026-06-10T09:00:00Z\",\n    \"previous_version\": 3\n  },\n\n  \"payload\": {\n    \"definition\": \"...\",\n    \"expression\": \"...\",\n    \"physical_mapping\": \"...\"\n  }\n}\n```\n\nThe `payload` differs by semantic object type.\n\nThe lifecycle and provenance model can remain consistent.\n\n**Add Lifecycle States**\n\nVersioning alone is not governance.\n\nA new definition should not automatically become production truth.\n\nA useful lifecycle might be:\n\n```\nDraft\n  ↓\nReview\n  ↓\nValidated\n  ↓\nPublished\n  ↓\nDeprecated\n```\n\nThis prevents a work-in-progress definition from being used by production agents.\n\n```\n{\n  \"metric_id\": \"gross_margin\",\n  \"version\": 5,\n  \"status\": \"draft\"\n}\n```\n\nshould not automatically replace:\n\n```\n{\n  \"metric_id\": \"gross_margin\",\n  \"version\": 4,\n  \"status\": \"published\"\n}\n```\n\nin production query resolution.\n\n**Controlled Rollout Matters**\n\nSometimes a semantic change needs to be tested before becoming the default.\n\n```\nGross Margin v5\n      ↓\nTest Workspace\n      ↓\nSelected Users\n      ↓\nValidation\n      ↓\nProduction\n```\n\nThis is similar to feature rollout in software systems.\n\nThe semantic definition itself becomes a governed production artifact.\n\nA platform such as Semora already treats business semantic definitions, mappings, metrics and dimensions as governed objects alongside version and controlled-release management. That is the right architectural direction: meaning needs lifecycle management, not just storage.\n\n**Define Material vs. Non-Material Changes**\n\nDo not create a new analytical version for every edit.\n\nA typo fix:\n\n```\n\"recgonized revenue\"\n→\n\"recognized revenue\"\n```\n\ndoes not change analytical behavior.\n\nA formula change does.\n\nA practical classification:\n\n```\nNON-MATERIAL\n- spelling\n- description wording\n- examples\n- documentation\n\nMATERIAL\n- formula\n- aggregation\n- source field\n- semantic mapping\n- filter rule\n- inclusion/exclusion logic\n- hierarchy\n```\n\nOnly material changes need to create a new analytical version.\n\nYou can still audit non-material edits separately.\n\n**Compute a Semantic Diff**\n\nWhen a new version is created, show what changed.\n\nExample:\n\n```\nRevenue v3 → v4\n\n- expression:\n-   recognized_revenue\n\n+ expression:\n+   recognized_revenue - approved_adjustments\n\n+ effective_from:\n+   2026-06-01\n```\n\nFor mappings:\n\n```\nProduct Code v1 → v2\n\n- product_master.material_id\n+ product_dim.product_code\n```\n\nA semantic diff is much easier to review than comparing two large JSON objects manually.\n\n**Dependency Analysis Before Publishing**\n\nSemantic objects rarely exist alone.\n\nSuppose:\n\n```\nGross Margin\n```\n\ndepends on:\n\n```\nRevenue\n```\n\nIf Revenue changes, downstream metrics may be affected.\n\nRepresent dependencies:\n\n```\nRevenue\n   ↓\nGross Profit\n   ↓\nGross Margin\n```\n\nBefore publishing Revenue v4:\n\n```\nChange\n  ↓\nDependency Graph\n  ↓\nImpacted Metrics\n  ↓\nValidation\n  ↓\nPublish\n```\n\nThis is where semantic governance begins to resemble software dependency management.\n\n**Keep Semantic Versions in the Query Plan**\n\nOnce a version is resolved, preserve it.\n\nA semantic query plan should not contain only:\n\n```\n{\n  \"metric\": \"revenue\"\n}\n```\n\nPrefer:\n\n```\n{\n  \"metric\": {\n    \"id\": \"revenue\",\n    \"version\": 4\n  }\n}\n```\n\nThen downstream stages know exactly which meaning was selected.\n\n**Persist Versions Into Answer Lineage**\n\nThe final answer should preserve the semantic version that produced it.\n\n```\n{\n  \"answer_id\": \"ans_9281\",\n\n  \"question\": \"What was revenue in Germany in July?\",\n\n  \"semantic_evidence\": {\n    \"metric_id\": \"revenue\",\n    \"metric_version\": 4,\n    \"mapping_version\": 2\n  },\n\n  \"query_id\": \"q_18273\"\n}\n```\n\nSix months later, you can reconstruct the answer even if Revenue has moved to v5.\n\nThis is **reproducible meaning**.\n\n**Why SQL Versioning Is Not Enough**\n\nImagine storing the generated SQL:\n\n```\nSELECT SUM(recognized_amount - adjustment_amount)\nFROM finance_revenue;\n```\n\nThat tells you what executed.\n\nBut it does not necessarily tell you:\n\n```\nWhy this expression represented Revenue\nWhich business definition authorized it\nWho owned that definition\nWhen it became effective\n```\n\nSQL provenance and semantic provenance solve different problems.\n\nProduction AI analytics needs both.\n\n**Cache Carefully**\n\nSemantic versioning also affects caching.\n\nA cache key like:\n\n```\nhash(question)\n```\n\nis unsafe if the semantic definition changes.\n\nA better cache identity may include:\n\n```\nQuestion\n+\nSemantic Version\n+\nData Source Version / Freshness\n+\nPolicy Context\ncache_key = hash(\n    question,\n    metric_version,\n    mapping_version,\n    policy_version\n)\n```\n\nOtherwise the system can return an answer generated under outdated semantics.\n\n**Version-Aware Retrieval**\n\nIf semantic retrieval uses embeddings, versioning creates another issue.\n\nSuppose both:\n\n```\nRevenue v3\nRevenue v4\n```\n\nexist in the semantic index.\n\nThe retriever should not blindly return whichever vector is closest.\n\nRetrieval needs governance filters:\n\n```\nsemantic_search(\n    term=\"revenue\",\n    status=\"published\",\n    effective_at=query_time\n)\n```\n\nSimilarity identifies candidates.\n\nGovernance determines which candidate is valid.\n\n**Audit Every Semantic Resolution**\n\nFor production use, log:\n\n```\n{\n  \"question_id\": \"qst_182\",\n  \"term\": \"revenue\",\n  \"resolved_object\": \"metric.revenue\",\n  \"resolved_version\": 4,\n  \"effective_at\": \"2026-07-15\",\n  \"resolution_source\": \"semantic_registry\"\n}\n```\n\nThis makes semantic decisions observable.\n\nIf an answer is disputed, you can inspect exactly which definition the system used.\n\n**A Reference Resolution Pipeline**\n\nPutting the pieces together:\n\n```\nNatural-Language Question\n          ↓\nIntent Resolution\n          ↓\nBusiness Concept\n          ↓\nExtract Time Context\n          ↓\nSemantic Registry\n          ↓\nFilter:\n- published\n- effective at time\n- allowed for user\n          ↓\nResolve Version\n          ↓\nResolve Physical Mapping\n          ↓\nRelationship Context\n          ↓\nSemantic Query Plan\n          ↓\nSQL\n          ↓\nAnswer\n          ↓\nAnswer Lineage\n```\n\nThe LLM does not decide which semantic version is authoritative.\n\nThe governed semantic layer does.\n\n**What to Test**\n\nSemantic versioning needs its own test cases.\n\n```\nQuestion:\nWhat is Revenue this month?\n\nExpected:\nLatest published effective version\nQuestion:\nWhat was Revenue in January?\n\nExpected:\nHistorical version or governed restatement policy\nQuestion:\nCompare Q1 and Q3 Revenue.\n\nExpected:\nExplicit comparison policy\nRevenue v5 = draft\n\nExpected:\nProduction agent does not use it\nProduct Code v1 = deprecated\n\nExpected:\nNew queries use the published replacement\n```\n\nThese are semantic correctness tests, not SQL syntax tests.\n\n**What to Measure**\n\nUseful operational metrics include:\n\n```\n% queries using published semantic objects\n% answers with semantic version lineage\nSemantic resolution failures\nQueries affected by semantic changes\nDeprecated-version usage\nAverage approval time for material changes\n```\n\nThese help teams operate the semantic layer as production infrastructure.\n\n**Final Thoughts**\n\nEnterprise AI cannot treat business meaning as a static prompt.\n\nMetrics change.\n\nMappings change.\n\nBusiness rules change.\n\nDimensions change.\n\nAnd historical questions still need to remain explainable and reproducible.\n\nThe architecture therefore needs to move from:\n\n```\nTerm → Definition\n```\n\nto:\n\n```\nTerm\n ↓\nGoverned Semantic Object\n ↓\nVersion\n ↓\nEffective Time\n ↓\nApproval State\n ↓\nPhysical Mapping\n ↓\nQuery\n```\n\nThe key engineering principle is:\n\nBecause a perfectly reproducible SQL query can still produce the wrong business answer if the system cannot reproduce the meaning that was valid when the question was asked.", "url": "https://wpnews.pro/news/ersioning-business-semantics-for-enterprise-ai", "canonical_source": "https://dev.to/arisyndata/ersioning-business-semantics-for-enterprise-ai-2gcm", "published_at": "2026-09-24 23:05:00+00:00", "updated_at": "2026-09-24 23:29:07.539081+00:00", "lang": "en", "topics": ["ai-agents", "mlops", "ai-infrastructure", "developer-tools"], "entities": [], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/ersioning-business-semantics-for-enterprise-ai", "markdown": "https://wpnews.pro/news/ersioning-business-semantics-for-enterprise-ai.md", "text": "https://wpnews.pro/news/ersioning-business-semantics-for-enterprise-ai.txt", "jsonld": "https://wpnews.pro/news/ersioning-business-semantics-for-enterprise-ai.jsonld"}}