How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.
The Ontology is a long-lived contract that must evolve without breaking active runs, active
queues, active integrations, or the audit chain. This section specifies how it evolves —
semver rules, deprecation windows, branching for parallel evolution, version pinning at the
agent and tool level, schema-compatibility tests, and replay against historic versions.
Each ontology object is independently versioned under a strict semver discipline, and the
ontology as a whole has a release version that pins a coherent set of object versions.
Change kind
Bump
Examples
Migration
Additive optional
minor
New optional property; new enum variant; new link with cardinality 0..N
None required; consumers transparently see new fields.
Additive required (with default)
minor
New required property with a derivable or default value
Backfill via mapping; default applied at projection time.
Required with no default
major
New required property that cannot be defaulted
Dual-write window; both versions live concurrently.
Type narrowing
major
String → enum; nullable → non-nullable
Validation pass over historic records; quarantine rejects.
Removal
major
Property dropped; link cardinality changed downward
Deprecation period of at least one minor; readers updated first.
Rename
major
Property renamed
Aliasing: old name continues to read for one major; writes go to new name.
Deprecated fields must remain readable for two minor versions after the deprecation announcement.
Deprecation is itself a typed AuditEvent on the ontology version chain.
Tools and agents pinned to a deprecated version produce an Exception (kind ontology.deprecated_pin) at run start; runs continue but operators see a warning.
Removal across a major bump is gated by a release-gate check that no production agent or tool still pins the removed field.
The ontology supports branches for parallel evolution: a tenant may need to
stage a major change against a subset of agents and tools without affecting production.
Branches are first-class; a branch is named, owned, and has a lifecycle.Fig. 6.1 — Ontology branching state diagram. A branch may be promoted to shadow, where it dual-writes against trunk and is exercised by a candidate model/prompt set, before merging.
Every agent definition, tool signature, mapping definition, and prompt revision pins to an
ontology version. The pin is a tuple (release, branch?). Pins are recorded in
the run’s model lineage (§4.3) and in every Decision’s
metadata. A run executed against a pinned version sees a frozen contract regardless
of subsequent ontology changes on trunk.
A pinned object is read with the resolver ontology.read(ref, asOf=pin). The
substrate retains historic schemas; readers are version-aware.
Every ontology change passes through a compatibility test pack before it can be promoted.
The pack runs three classes of test:
Structural: JSON Schema diff classifies the change (additive optional / additive required / narrowing / removal / rename) and validates the bump matches §6.1.
Replay: A sample of recent runs is replayed against the candidate version; deviations in Decision verdict beyond the noise band are flagged.
Consumer: Every active tool, mapping, and agent declaring a pin to the changed object is re-validated; pins that no longer satisfy contract block promotion.
Replay (§4.7) of an old run resolves the ontology version captured in
the run’s model lineage; it does not “upgrade” the run to current trunk. This guarantees
that a regulator-driven re-execution of a Decision produces the exact ontology contract that
was in force at decision time.
Each tenant has its own ontology release line. Ontology assets are not shared across
tenants; convergence on a common base happens only via the platform’s reference release,
which a tenant chooses to consume on its own schedule. There is no automatic propagation of
tenant-specific objects, properties, or markings.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Layerup","colors":{"primary":"#0a0a0b","light":"#3d3d3f","dark":"#0a0a0b"},"logo":{"light":"https://mintcdn.com/layerup/7JDjwgQFFUauG8YE/logo/logo-lightmode.png?fit=max\u0026auto=format\u0026n=7JDjwgQFFUauG8YE\u0026q=85\u0026s=e3cb87895efb1a8ca2d812d71d4afe32","dark":"https://mintcdn.com/layerup/7JDjwgQFFUauG8YE/logo/logo-darkmode.png?fit=max\u0026auto=format\u0026n=7JDjwgQFFUauG8YE\u0026q=85\u0026s=b3966afbf43531ec235964cfa3bb865a"},"favicon":"https://mintcdn.com/layerup/7JDjwgQFFUauG8YE/favicon.png?fit=max\u0026auto=format\u0026n=7JDjwgQFFUauG8YE\u0026q=85\u0026s=6a7afccf7183fa330023e2abfab54e21","appearance":{"default":"light"},"background":{"color":{"light":"#ffffff","dark":"#0a0a0b"}},"navbar":{"primary":{"type":"button","label":"Request Access","href":"https://www.uselayerup.com/contact"}},"footer":{"socials":{"twitter":"https://twitter.com/layerup_","github":"https://github.com/layerupai","linkedin":"https://www.linkedin.com/company/layerupai"}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"layerup","hasAudioNarration":false,"actualSubdomain":"layerup","customDomains":["docs.uselayerup.com"],"gitSource":{"type":"github","owner":"layerupai","repo":"core","deployBranch":"main","contentDirectory":"docs/layerup-docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6aebed8a7322b8787c5c1697","collectionId":"00593435-9d81-462f-b555-9d7f89c84192","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6aebed8a7322b8787c5c1697"},"entitlements":{},"buildId":"6aebed8a7322b8787c5c1697","clientVersion":"0.0.4076","searchFilterCounts":[{"language":"default","tag":"Platform Docs","count":23},{"language":"default","tag":"Agents Docs","count":21},{"language":"default","tag":"Deployment Architecture","count":7},{"language":"default","tag":"Foundations","count":6},{"language":"default","tag":"Security \u0026 Governance","count":6},{"language":"default","tag":"Operations","count":4},{"language":"default","tag":"Configuration \u0026 Lifecycle","count":3},{"language":"default","tag":"Logic \u0026 Reasoning","count":3},{"language":"default","tag":"Data \u0026 Integration","count":2},{"language":"default","tag":"Observability \u0026 Resilience","count":2}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"comment-mode","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"ontology/evolution","slug":"/ontology/evolution","pageMetadata":{"title":"Ontology Evolution, Branching \u0026 Versioning","description":"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.","href":"/ontology/evolution"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={code:`code`,em:`em`,li:`li`,ol:`ol`,p:`p`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{Heading,Mermaid,Table,Warning}=_components;if(!Heading)_missingMdxReference(`Heading`,true);if(!Mermaid)_missingMdxReference(`Mermaid`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`1`,id:`06-—-ontology-evolution-branching-\u0026-versioning`,children:`06 — Ontology evolution, branching \u0026 versioning.`}),`\n`,_jsx(_components.p,{children:`The Ontology is a long-lived contract that must evolve without breaking active runs, active\nqueues, active integrations, or the audit chain. This section specifies how it evolves —\nsemver rules, deprecation windows, branching for parallel evolution, version pinning at the\nagent and tool level, schema-compatibility tests, and replay against historic versions.`}),`\n`,_jsx(Heading,{level:`2`,id:`6-1-versioning-model`,children:`6.1 Versioning model`}),`\n`,_jsx(_components.p,{children:`Each ontology object is independently versioned under a strict semver discipline, and the\nontology as a whole has a release version that pins a coherent set of object versions.`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Change kind`}),_jsx(_components.th,{children:`Bump`}),_jsx(_components.th,{children:`Examples`}),_jsx(_components.th,{children:`Migration`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Additive optional`}),_jsx(_components.td,{children:_jsx(_components.strong,{children:`minor`})}),_jsx(_components.td,{children:`New optional property; new enum variant; new link with cardinality 0..N`}),_jsx(_components.td,{children:`None required; consumers transparently see new fields.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Additive required (with default)`}),_jsx(_components.td,{children:_jsx(_components.strong,{children:`minor`})}),_jsx(_components.td,{children:`New required property with a derivable or default value`}),_jsx(_components.td,{children:`Backfill via mapping; default applied at projection time.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Required with no default`}),_jsx(_components.td,{children:_jsx(_components.strong,{children:`major`})}),_jsx(_components.td,{children:`New required property that cannot be defaulted`}),_jsx(_components.td,{children:`Dual-write window; both versions live concurrently.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Type narrowing`}),_jsx(_components.td,{children:_jsx(_components.strong,{children:`major`})}),_jsx(_components.td,{children:`String → enum; nullable → non-nullable`}),_jsx(_components.td,{children:`Validation pass over historic records; quarantine rejects.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Removal`}),_jsx(_components.td,{children:_jsx(_components.strong,{children:`major`})}),_jsx(_components.td,{children:`Property dropped; link cardinality changed downward`}),_jsx(_components.td,{children:`Deprecation period of at least one minor; readers updated first.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Rename`}),_jsx(_components.td,{children:_jsx(_components.strong,{children:`major`})}),_jsx(_components.td,{children:`Property renamed`}),_jsx(_components.td,{children:`Aliasing: old name continues to read for one major; writes go to new name.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Marking change`}),_jsx(_components.td,{children:_jsx(_components.strong,{children:`major`})}),_jsx(_components.td,{children:`Default marking elevated`}),_jsx(_components.td,{children:`Re-classification batch; access caches invalidated.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`6-2-deprecation-discipline`,children:`6.2 Deprecation discipline`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Deprecated fields must remain readable for `,_jsx(_components.strong,{children:`two minor versions`}),` after the deprecation announcement.`]}),`\n`,_jsx(_components.li,{children:`Deprecation is itself a typed AuditEvent on the ontology version chain.`}),`\n`,_jsxs(_components.li,{children:[`Tools and agents pinned to a deprecated version produce an Exception (kind `,_jsx(_components.code,{children:`ontology.deprecated_pin`}),`) at run start; runs continue but operators see a warning.`]}),`\n`,_jsx(_components.li,{children:`Removal across a major bump is gated by a release-gate check that no production agent or tool still pins the removed field.`}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`6-3-branching`,children:`6.3 Branching`}),`\n`,_jsxs(_components.p,{children:[`The ontology supports `,_jsx(_components.strong,{children:`branches`}),` for parallel evolution: a tenant may need to\nstage a major change against a subset of agents and tools without affecting production.\nBranches are first-class; a branch is named, owned, and has a lifecycle.`]}),`\n`,_jsx(Mermaid,{chart:`stateDiagram-v2\n [*] --> trunk\n trunk --> branch_proposal: fork(name)\n branch_proposal --> branch_active: review.approved\n branch_active --> branch_active: edit / commit\n branch_active --> shadow: promote(shadow)\n shadow --> shadow: dual-write \u0026 eval\n shadow --> trunk: merge(approved)\n shadow --> branch_active: revert\n branch_active --> archived: abandon\n trunk --> [*]`}),`\n`,_jsx(_components.p,{children:_jsxs(_components.em,{children:[`Fig. 6.1 — Ontology branching state diagram. A branch may be promoted to `,_jsx(_components.em,{children:`shadow`}),`, where it dual-writes against trunk and is exercised by a candidate model/prompt set, before merging.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`6-4-pinning`,children:`6.4 Pinning`}),`\n`,_jsxs(_components.p,{children:[`Every agent definition, tool signature, mapping definition, and prompt revision pins to an\nontology version. The pin is a tuple `,_jsx(_components.code,{children:`(release, branch?)`}),`. Pins are recorded in\nthe run’s model lineage (§4.3) and in every Decision’s\nmetadata. A run executed against a pinned version sees a `,_jsx(_components.em,{children:`frozen contract`}),` regardless\nof subsequent ontology changes on trunk.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`A pinned object is read with the resolver `,_jsx(_components.code,{children:`ontology.read(ref, asOf=pin)`}),`. The\nsubstrate retains historic schemas; readers are version-aware.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`6-5-schema-compatibility-tests`,children:`6.5 Schema-compatibility tests`}),`\n`,_jsx(_components.p,{children:`Every ontology change passes through a compatibility test pack before it can be promoted.\nThe pack runs three classes of test:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Structural:`}),` JSON Schema diff classifies the change (additive optional / additive required / narrowing / removal / rename) and validates the bump matches §6.1.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Replay:`}),` A sample of recent runs is replayed against the candidate version; deviations in Decision verdict beyond the noise band are flagged.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Consumer:`}),` Every active tool, mapping, and agent declaring a pin to the changed object is re-validated; pins that no longer satisfy contract block promotion.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`6-6-replay-against-historic-versions`,children:`6.6 Replay against historic versions`}),`\n`,_jsx(_components.p,{children:`Replay (§4.7) of an old run resolves the ontology version captured in\nthe run’s model lineage; it does not “upgrade” the run to current trunk. This guarantees\nthat a regulator-driven re-execution of a Decision produces the exact ontology contract that\nwas in force at decision time.`}),`\n`,_jsx(Heading,{level:`2`,id:`6-7-reconciliation-merge-algorithm`,children:`6.7 Reconciliation merge algorithm`}),`\n`,_jsx(_components.p,{children:`When a shadow branch merges into trunk, conflicts are resolved per a fixed algebra:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsx(_components.li,{children:`Disjoint additive changes always merge cleanly.`}),`\n`,_jsx(_components.li,{children:`Same-property concurrent additions: the one with the higher pin-count wins; the other becomes a deprecation candidate.`}),`\n`,_jsxs(_components.li,{children:[`Type changes from both branches: hard conflict; merge fails; resolution is by an explicit Decision tagged `,_jsx(_components.code,{children:`ontology.merge.resolution`}),`.`]}),`\n`,_jsx(_components.li,{children:`Marking changes always escalate to the security plane (§15) before merge.`}),`\n`,_jsx(_components.li,{children:`Every merge produces a typed AuditEvent on the ontology chain with the diff, the algorithm path taken, and the resolver principal.`}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`6-8-cross-tenant-boundary`,children:`6.8 Cross-tenant boundary`}),`\n`,_jsx(_components.p,{children:`Each tenant has its own ontology release line. Ontology assets are not shared across\ntenants; convergence on a common base happens only via the platform’s reference release,\nwhich a tenant chooses to consume on its own schedule. There is no automatic propagation of\ntenant-specific objects, properties, or markings.`})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Ontology Evolution, Branching \u0026 Versioning","description":"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.","href":"/ontology/evolution"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"06 — Ontology evolution, branching \u0026 versioning.","slug":"06-—-ontology-evolution-branching-\u0026-versioning","depth":1,"children":[]},{"title":"6.1 Versioning model","slug":"6-1-versioning-model","depth":2,"children":[]},{"title":"6.2 Deprecation discipline","slug":"6-2-deprecation-discipline","depth":2,"children":[]},{"title":"6.3 Branching","slug":"6-3-branching","depth":2,"children":[]},{"title":"6.4 Pinning","slug":"6-4-pinning","depth":2,"children":[]},{"title":"6.5 Schema-compatibility tests","slug":"6-5-schema-compatibility-tests","depth":2,"children":[]},{"title":"6.6 Replay against historic versions","slug":"6-6-replay-against-historic-versions","depth":2,"children":[]},{"title":"6.7 Reconciliation merge algorithm","slug":"6-7-reconciliation-merge-algorithm","depth":2,"children":[]},{"title":"6.8 Cross-tenant boundary","slug":"6-8-cross-tenant-boundary","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"layerup","siteName":"Layerup","title":"Ontology Evolution, Branching \u0026 Versioning - Layerup","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-18T22:33:45.950Z","originalFileLocation":"ontology/evolution.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"light\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Layerup\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Ontology Evolution, Branching \u0026amp; Versioning - Layerup\">\u003cmeta data-mint-head property=\"og:description\" content=\"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Layerup\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.uselayerup.com/ontology/evolution\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://layerup.mintlify.site/_mintlify/api/og/v2?division=Ontology\u0026amp;title=Ontology+Evolution%2C+Branching+%26+Versioning\u0026amp;description=How+the+Insurance+Ontology+evolves+without+breaking+active+runs%2C+queues%2C+integrations%2C+or+the+audit+chain.+Semver+rules%2C+deprecation%2C+branching%2C+pinning%2C+compat\u0026amp;theme=bb302b0a1cec2007607c5737\u0026amp;signature=d8ee7353f1daea12ec28cfd459969bb08548e0360c6ed763ddd9c4463aa265ec\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Ontology Evolution, Branching \u0026amp; Versioning - Layerup\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://layerup.mintlify.site/_mintlify/api/og/v2?division=Ontology\u0026amp;title=Ontology+Evolution%2C+Branching+%26+Versioning\u0026amp;description=How+the+Insurance+Ontology+evolves+without+breaking+active+runs%2C+queues%2C+integrations%2C+or+the+audit+chain.+Semver+rules%2C+deprecation%2C+branching%2C+pinning%2C+compat\u0026amp;theme=bb302b0a1cec2007607c5737\u0026amp;signature=d8ee7353f1daea12ec28cfd459969bb08548e0360c6ed763ddd9c4463aa265ec\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/layerup/AI2c3611NSqy-PIO/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Layerup\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0a0a0b\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.uselayerup.com/ontology/evolution\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/ontology/evolution.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.uselayerup.com/#organization\",\"name\":\"Layerup\",\"url\":\"https://docs.uselayerup.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/layerup/7JDjwgQFFUauG8YE/logo/logo-lightmode.png?fit=max\u0026auto=format\u0026n=7JDjwgQFFUauG8YE\u0026q=85\u0026s=e3cb87895efb1a8ca2d812d71d4afe32\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.uselayerup.com#website\",\"name\":\"Layerup\",\"url\":\"https://docs.uselayerup.com\",\"publisher\":{\"@id\":\"https://docs.uselayerup.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.uselayerup.com/ontology/evolution#webpage\",\"url\":\"https://docs.uselayerup.com/ontology/evolution\",\"name\":\"Ontology Evolution, Branching \u0026 Versioning\",\"description\":\"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.\",\"dateModified\":\"2026-08-18T22:33:45.950Z\",\"isPartOf\":{\"@id\":\"https://docs.uselayerup.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.uselayerup.com/ontology/evolution#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.uselayerup.com/ontology/evolution#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Ontology\",\"item\":\"https://docs.uselayerup.com/ontology/objects\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Ontology Evolution, Branching \u0026 Versioning\",\"item\":\"https://docs.uselayerup.com/ontology/evolution\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.uselayerup.com/ontology/evolution#article\",\"headline\":\"Ontology Evolution, Branching \u0026 Versioning\",\"name\":\"Ontology Evolution, Branching \u0026 Versioning\",\"description\":\"How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay.\",\"url\":\"https://docs.uselayerup.com/ontology/evolution\",\"mainEntityOfPage\":{\"@id\":\"https://docs.uselayerup.com/ontology/evolution#webpage\"},\"dateModified\":\"2026-08-18T22:33:45.950Z\",\"publisher\":{\"@id\":\"https://docs.uselayerup.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.uselayerup.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Layerup\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Layerup","nav":{"global":null,"tabs":[{"tab":"Platform Docs","groups":[{"group":"Foundations","pages":[{"title":"Platform Overview","href":"/overview"},{"title":"Architectural Principles","href":"/principles"},{"title":"Platform Topology","href":"/topology"},{"title":"Core Concepts \u0026 Vocabulary","href":"/concepts"}]},{"group":"Ontology","pages":[{"title":"The Insurance Ontology","description":"The canonical, version-controlled object model. 28 objects across seven groups: Parties, Master data, Underwriting, Claims, Workflow, Evidence, and Governance.","href":"/ontology/objects"},{"title":"Ontology Evolution, Branching \u0026 Versioning","href":"/ontology/evolution"}]},{"group":"Data Plane","pages":[{"title":"Data Plane — Ingestion","description":"The Data Plane accepts heterogeneous signal from many channels, classifies, hashes, normalises, and presents it as a typed, content-addressed stream of objects.","href":"/data/ingestion"},{"title":"Data Abstraction, Mapping, Lineage \u0026 Replay","href":"/data/lineage"}]},{"group":"Logic \u0026 Reasoning","pages":[{"title":"Tool Pattern Library","href":"/tool-patterns"},{"title":"Agent Runtime Architecture","href":"/runtime/runtime"},{"title":"Planner, Executor, Verifier \u0026 Memory","href":"/runtime/internals"}]},{"group":"Models","pages":[{"title":"Model Gateway","href":"/models/gateway"},{"title":"Evaluation, Benchmarks \u0026 Drift","href":"/models/evaluation"}]},{"group":"Action Plane","pages":[{"title":"Action Plane","href":"/action-plane"}]},{"group":"Security \u0026 Governance","pages":[{"title":"Identity, Access \u0026 Safety","href":"/security/identity"},{"title":"Tool Invocation Governance","href":"/security/tool-governance"},{"title":"Audit, Decision Lineage \u0026 Action Lineage","href":"/security/audit"}]},{"group":"Operations","pages":[{"title":"Observability \u0026 Telemetry","href":"/operations/observability"},{"title":"Deployment Topology \u0026 Tenancy","href":"/operations/deployment"},{"title":"Reliability, Throughput \u0026 SLOs","href":"/operations/reliability"},{"title":"Versioning, Release Gates \u0026 Failure Modes","href":"/operations/release-gates"}]},{"group":"Enterprise","pages":[{"title":"Enterprise Scale \u0026 Federation","href":"/enterprise-scale"},{"title":"Reference Appendix","href":"/appendix"}]}]},{"tab":"Agents Docs","pages":[{"title":"Agents Docs","href":"/agents/overview"}]},{"tab":"Integration Docs","pages":[{"title":"Integration Docs","href":"/integrations/chat-widget/embed"}]},{"tab":"Prompting Guides","hidden":true,"pages":[{"title":"Prompting Guides","href":"/guides/prompting/contents"}]},{"tab":"Usage Guides","hidden":true,"pages":[{"title":"Usage Guides","href":"/guides/usage/customer-support"}]}]},"basePath":"","title":"Ontology Evolution, Branching \u0026 Versioning - Layerup","buildId":"dpl_8LJbrAiZvr1K98WQNZXCyY5AvT34","deploymentId":"dpl_8LJbrAiZvr1K98WQNZXCyY5AvT34","dynamics":[],"chunks":[]}
