Ontology Versioning: How to Manage Evolving Schemas

When a knowledge graph's definitions change, the systems and AI agents that rely on them can break or give wrong answers. Ontology versioning is the practice of recording what changed, why it changed, and who needs to act on it.

Good versioning starts by classifying every proposed change before it ships. Some changes are safe additions. Some restructure things without breaking anything. Some break things. Breaking changes need a warning period, advance notice to teams whose systems depend on the schema, and a written migration guide. That guide becomes a permanent record. It must say what changed, why, who approved it, when it takes effect, and which systems are affected. Every answer an AI agent produces should be stamped with the exact schema version it used at that moment. That way, a later definition change cannot silently reclassify a decision already made. SHACL (a W3C standard for checking data against rules) can automatically test whether a proposed change would break previously valid data. This catches problems before they reach production.

A well-documented schema can drift out of step with the data and systems it describes. A concept may quietly change meaning. A property may disappear. A new data source may use a different definition. Those silent shifts can produce incomplete results, broken queries, or misleading context for an AI agent. Versioning lets teams catch and manage those differences before they cause damage.

Schemas need to evolve as business terms, rules, and data sources change. Updating a date on the whole file is not enough to explain that evolution. Record which classes and properties changed, the reason for each change, whether it breaks anything, and what consumers need to do about it.

What ontology versioning is, and what it is not

An ontology is not a business glossary, and it is not a taxonomy. The three get used interchangeably in casual conversation, but they are different things. A glossary defines terms for human readers. A taxonomy organises concepts into hierarchies. An ontology does something stricter. It formally specifies classes, properties, and the logical relationships between them in a way a machine can reason over.

Each layer changes at a different pace and carries a different level of risk. Editing a glossary entry to clarify a definition is low-stakes. Deleting a class from a production ontology that forty downstream systems import is not. Treating them the same way either drowns glossary edits in unnecessary approval steps or lets schema changes slip through too casually.

There is also a difference between deliberate versioning and silent drift. Versioning is deliberate. Someone proposes a change, someone reviews it, and a version number moves. Drift is what happens without that discipline. "Customer" means one thing to the sales team's system and something quietly different to finance's. Nobody approved the difference. It just happened over eighteen months of separate teams making separate local decisions.

The W3C's guidance on vocabulary management frames the task well. Managing an ontology means identifying, documenting, and publishing its terms so other applications can cite and reuse them reliably. A term in an ontology is a public commitment. Think of it like a published API endpoint, a fixed address other software calls. Other systems build on top of it. Breaking that commitment without notice has consequences that ripple outward.

The most common failure in practice is what might be called the version documentation gap. A team updates the version number, applies that single number to the entire file, and calls it done. But if a downstream consumer only uses thirty of the ontology's two thousand classes, they have no way of knowing whether any of those thirty changed. The version number tells you something changed. It tells you nothing about what.

Classify changes before you version them

Change management is one of the field's hardest unsolved problems. Most published ontology work simply does not keep a record of changes as they happen. Without that record, nobody can trace a change forward to see its effects or backward to understand why it was made. Fixing that starts before anyone touches a version number. It starts with a basic act of classification.

Three categories matter. Safe additions are new classes, properties, or relationships that do not change anything already in the model. Existing consumers can ignore them and keep working as before. Non-breaking modifications are trickier. These are renames or restructurings that keep the underlying meaning of a term even though its label or position changed. Then there are breaking changes. These include deleting a class, an attribute, or a relationship. They also include tightening a rule so that data which used to be valid no longer is. Breaking changes need explicit notice to consumers and a real migration plan, not just a changelog line buried in release notes.

Renames deserve a special warning because they cause a lot of quiet damage. Relabelling a property's display name from hasAddr to hasAddress while the meaning stays the same is safe. But a rename where the label stays similar while the underlying meaning shifts is dangerous. Say a property now captures billing address instead of shipping address. That is one of the most common sources of downstream breakage in ontology work. It does not look like a breaking change on the surface. It passes a basic comparison of the two files. It fails in production, in the query that assumed the old meaning.

Changes to the main identifier used to refer to an entity need the most care of all. Re-keying an entity's identity requires deliberate planning. Relationships and downstream records tied to that identifier can be silently orphaned if the change happens without a coordinated migration path.

Use semantic versioning for ontologies

Software engineers have used semantic versioning, the X.Y.Z numbering pattern, for years. It maps onto ontologies with only minor adjustment. The major number (X) goes up when something breaks backward compatibility. That means a class, attribute, or relationship is deleted, or a URI (the unique address of a term) changes. The minor number (Y) goes up for safe additions such as new classes, properties, or relationships that existing consumers can ignore. The patch number (Z) is for fixes that change nothing structural, such as corrected definitions, fixed labels, or cleaned-up metadata.

This is not theoretical. The European eProcurement Ontology, maintained by the EU Publications Office, runs on exactly this pattern. Change notes are tied to each release. A breaking change such as deleting a class or relationship triggers a major version bump as a matter of policy, not convention.

Embed the version number in the file itself so it travels with the ontology. That way every consumer that imports it can always see the version they are using.

Semantic versioning solves exactly one problem. It tells a consumer, at a glance, what class of change occurred. It does not say what changed, who approved it, or why the change was made. That is a different job, and it belongs to the changelog.

Use a changelog as your audit layer

Every release of an ontology should produce a changelog entry. That entry needs five things at minimum. What changed. Why it changed. Who approved it. When it takes effect. Which downstream consumers are affected. Skipping any one of these turns the changelog into a list of diffs nobody can act on.

Three practical situations make explicit change tracking essential. First, an auditor asks when a given type of entity entered the model and who signed off on it. The version number alone cannot answer that. Second, an engineering team needs to know, after a schema change ships, which downstream systems or documents need updating. That only works if the changelog records what was touched. Third, someone may need to roll back to a prior schema version entirely. That is only possible if the boundary between versions was recorded clearly, not guessed at after the fact.

One approach from ontology research proposes splitting the record into two graphs. A SchemaVersionGraph tracks operations on the schema itself. An InstanceVersionGraph tracks operations on the data governed by that schema. Each captures which elements were affected, alongside metadata such as version number, date, author, and a plain description of the change. That separation matters because schema changes and data changes carry different risks and affect different audiences.

There is an institutional memory argument here too, and it is easy to underrate. A new hire reading through a changelog does not just learn what the current model contains. They learn the reasoning behind how it got there. Why a class got split in two. Why a property was retired rather than deleted. The changelog works as organisational memory as much as a technical log of changes.

Split the ontology into modules to limit the impact of any one change

Ontologies rarely stand alone. Most reuse or extend pieces of other ontologies, and the dependencies between those pieces exist at every level. Splitting an ontology into modules keeps coming up as necessary. Without it, every change risks rippling through the whole graph whether it needed to or not.

The core idea is straightforward. If a module covering regulatory compliance terms needs a major version bump because a class was deleted, that bump should stay within that module. Teams building on unrelated modules, such as a product catalogue module, should not need to migrate anything just because compliance restructured its internals.

Making that work in practice requires a few disciplines. Split modules along lines of change rate and risk, not just subject-matter convenience. Regulatory terms change on a compliance calendar. Product terms change on a release calendar. Forcing them into one file means every governance cycle has to account for both at once. Declare dependencies between modules explicitly. That way the changelog's "who does this affect" question can be traced automatically instead of guessed at. Treat a module's public interface, the classes and properties it exposes for other modules to import, with the same versioning care you would apply to a public API.

A consumer who only imports thirty classes from a two-thousand-class ontology can finally know, from a per-module changelog, whether those thirty were touched. They no longer need to read a comparison of the entire file.

Patterns for routine, safe evolution

In a well-run ontology, most changes should be minor or patch bumps. If your organisation makes breaking changes every few months, that is a sign of a governance problem before it is a modelling problem. It suggests changes are not being scoped carefully enough to stay backward-compatible when they could be.

A handful of patterns cover most routine, safe evolution. Adding new classes, subclasses, or properties is safest and most common. Existing consumers can simply ignore them. Adding an optional property to an existing class does not break any instance that predates it. Consumers who never fill in the new property remain perfectly valid. Adding a subclass beneath an existing class keeps the parent's meaning for any consumer not yet working at that finer level of detail. Improving annotations, such as better labels, clearer definitions, or added source notes, never breaks anything downstream. Annotations carry no logical weight in the reasoning layer.

What counts as "backward-compatible" is narrower than you might expect from API design. Tightening a rule, changing a property from optional to required, or narrowing an allowed value range, can break instances that were perfectly valid a moment before. No class was deleted and no address moved. But it is still a breaking change in substance, even if it looks minor in form. You need to classify it as one.

One more point, specific to newer workflows. Where an AI model helps propose schema changes, the reasoning behind its suggestion is part of the audit trail. It is not incidental output to discard once a human approves the change. If that reasoning is not captured and stored, the governance record has a hole in it exactly where an automated decision was made.

How to handle breaking changes so AI agents do not query stale schemas

Deleting a class, an attribute, or a relationship triggers a major version bump. Structural changes of similar impact need the same treatment. There is no way to avoid the bump while doing the same thing under a different name.

A responsible breaking-change process has a few fixed steps. Notify known downstream consumers before the major version ships. Give them a defined migration window, not a surprise on release day. Mark the affected class or property as deprecated (flagged as due for removal) in a minor version first. This gives consumers time to adjust before the actual deletion lands in the next major release. Write a migration guide that covers what changed, what replaces it, and how existing data should be transformed. That guide becomes part of the permanent changelog record, not a one-off email. Keep existing consumers on the prior supported version until their migration is complete or their support window ends. Refuse patches that paper over an incompatibility without actually fixing it.

SHACL, the W3C standard for defining constraint shapes over RDF graphs (a type of structured data), gives this process a machine-checkable guardrail. SHACL shapes can test whether a proposed change would break data that was previously valid. This catches problems before they reach production, not after a downstream system starts throwing errors.

Rollback is only a real option where the change is actually reversible. If a breaking change involves migrating data and then discarding the old format, that is an irreversible step. Flag it during approval, before the change runs, not after someone asks to revert and finds there is nothing to revert to.

Pin decisions to a schema version for traceability and compliance

A change in definition must never reach backward and silently reclassify a decision that was already made. If an ontology's definition of "high-risk transaction" shifts next quarter, that shift cannot quietly reclassify a decision an AI system made last quarter under the old definition. Every output produced by an automated system needs to be stamped with the exact schema version hash (a unique fingerprint of the file) active at the moment of inference. Not just a date, but the specific governed state of meaning that produced that result.

This closes off a dangerous failure mode: definition laundering. Without a fixed link between a decision and the schema version that governed it, someone could modify a definition after the fact. That would retroactively change what a past compliance classification means, without touching a single row of data or a single line of code. Only the meaning of the term moved. That kind of change is invisible unless decisions are pinned to version-stamped decision records that cannot be quietly rewritten after the fact.

Auditors are already asking for this. Under SOC 2 Type II review (a common security and compliance audit), an AI-aware auditor's first requests typically include model lineage, prompt and inference logs, and drift-monitoring output. An ontology version stamp on every AI decision is the semantic equivalent of model lineage. It is the record that shows exactly which governed state of meaning produced a given output.

Standards-based provenance frameworks can give this a formal foundation. They link a decision to the model files and processes that generated it. They also support the traceability chains that emerging AI governance requirements ask auditors to reconstruct.

Keep the versioned schema synchronised with live systems

A static ontology ships once and starts decaying the moment it does. Agents built to reason against a static model eventually query a version of reality that no longer exists. A column gets deprecated. A policy changes. A dashboard the ontology assumed was live goes stale. None of it makes it back into the model. The agent does not know any of this happened. It answers anyway, and it answers wrong. It is reasoning from an old description of the world, not the world itself.

An active ontology closes that gap by staying connected to the operational signals around it: live metadata, lineage, governance state. When something changes downstream, the model finds out.

Atlan describes an architecture with four connected graphs: a data graph for assets, schemas and lineage; a governance graph for ownership, policy and quality signals; a knowledge graph for business terms and relationships; and an active ontology graph for formal classes, properties and constraints. In that design, the graphs share a metadata store so that operational changes can move across them. This is one architectural approach. Teams can reach the same goal of keeping definitions in step with the systems they describe using different storage and integration designs.

That is the real argument for treating versioning as a governance discipline rather than a filing exercise. A version number, a changelog entry, a deprecation window: none of these matter for their own sake. They matter because they are how a model that has to keep changing stays trustworthy enough for a system, an agent, or an auditor to rely on.