Model Versioning
Intermediate 12 min read Model Versioning

Semantic Versions for Models

Signal the size of the change before consuming it

Model versions communicate risk: is this a minor tweak or a breaking contract change? Semantic versioning signals what consumers can expect and what must be revalidated.

semantic versioningbreaking changeminorpatchmodel contract
Prerequisites: Why Version Models Feature Stores
Before we start

What you will learn

  • Map MAJOR/MINOR/PATCH to model changes
  • Define what counts as a breaking model contract
  • Use version bumps to drive revalidation and rollout waves
Introduction

What is this?

Model semantic versioning assigns X.Y.Z meaning: MAJOR for a breaking change to the input/output contract or decision semantics, MINOR for compatible quality improvements or additive features, PATCH for bug-fix retrains that preserve behavior. The version number becomes risk communication to every downstream consumer.

Motivation

Why do you need it?

  • Consumers need to know before integrating whether their input schema or decision thresholds still apply.
  • A MAJOR bump can trigger formal revalidation; a PATCH can deploy quietly.
  • Version semantics make the registry human- and machine-readable.
  • Mixing retrains and contract changes under one number hides breaking risk.
Think about it

Mental model

Imagine

Car model years and trim levels

Think of

Semantic versions

A new model year (MAJOR) may change where the pedals are; a trim update (MINOR) adds features but drives the same; a recall fix (PATCH) makes the car behave as promised. Drivers (consumers) react differently to each.

Mechanics

How it works

  • MAJOR: input schema, feature semantics, output space or decision thresholds change — existing requests or interpretations break.
  • MINOR: model improves quality, gains an output, or adds support without breaking existing contracts.
  • PATCH: corrections and retrains preserving the contract and expected behavior.
  • The registry stores the semantic version alongside the content hash and promotion evidence.
  • Release notes per version explain the change dimension for reviewers and consumers.

Semantic version bump routes differ by risk tier.

Change detected
PATCH
MINOR
MAJOR
Consumers adapt
Real world

In production

  • A feature pipeline declares a categorical value's meaning changed → MAJOR bump triggers downstream revalidation.
  • A nightly retrain improves precision without changing the schema → MINOR with quiet rollout.
  • A bug fix re-trains on corrected labels → PATCH deploys with regression tracking only.
Guidelines

Best practices

  • Define 'breaking' explicitly in your feature contract before the first bump.
  • Write a release note for every version: change, evidence, rollout behavior.
  • Mark breaking changes in the registering API so automation enforces MAJOR handling.
  • Tie revalidation workflows to MAJOR-only in regulated settings.
Watch out

Common mistakes

  • Bumping MINOR for a schema change — silently breaking downstream feature pipelines.
  • Semantic versions stored as free text, drifting from the actual artifact bytes.
  • Over-promising PATCH for retrains that actually change decision distributions.
When things break

Debugging tips

  • Downstream breakage after a 'small' update — check the release note and the bump semantics.
  • Consumers pinned on a MAJOR threshold? Search the registry for version predicates.
Interviews

Interview checkpoint

Test yourself

Quick quiz

0/2
1

A retrain changes the encoding of the categorical feature 'region' from IDs to names. Which bump applies?

2

A PATCH bump implies the model's expected behavior is preserved.

Go deeper

Official documentation

SemVer specification
spec