Model maturity and versioning
This page explains the different maturity levels we have for our Timefold models and what you can expect for each maturity level.
Additionally, it explains how versioning works for Timefold models and the Timefold Platform today, what visibility and controls are available to customers, and how these capabilities help you validate model behavior across environments.
Maturity levels
We assign each model a maturity level. This level is shown on the Platform Homepage and Model Information pages.
We have defined the following maturity levels:
| Maturity level | Description |
|---|---|
Example |
Example models are usually the first version of a model. The main purpose of these models is to showcase a given use case in action and serve as technology proof-points. |
Experimental |
Experimental models are models that are actively being worked on. You can assess the model’s features and quickly access its capabilities. Experimental models are likely to change a lot. |
Preview |
Models that have been mostly developed, but still need to be tested are labeled Preview. They are offered to early adopters to provide feedback as we refine the features. At this stage some backward incompatible changes can still be introduced. |
Stable |
These models are considered enterprise-ready. They have been developed and released under a given version number. Stability brings guarantees of backward compatibility so you can expect the model to behave consistently with new releases. |
Deprecated |
Models with this label are no longer supported on the platform, and will soon be removed. |
Models will typically start as examples or experimental and become stable over time.
Semantic versioning
Timefold applies semantic versioning to both the platform and optimization models with maturity level "Stable":
MAJOR.MINOR.PATCH
For example: v1.15.2
The meaning of each component is:
-
MAJORversion:
May introduce backward-incompatible API changes. The major version is part of the model API URL, which allows customers to run multiple major versions of a model in parallel and migrate gradually. -
MINORversion
Introduces new functionality, performance improvements, or behavioral changes that are intended to remain backward compatible at the API level. -
PATCHversion
Contains bug fixes and hotfixes only. Patch versions do not introduce new features.
| Some changes that are technically backward compatible (for example, new warning types or additional enum values) may still affect downstream business logic. For this reason, version visibility is critical, even when version control is limited. |
Platform version versus model version
It is important to distinguish between platform versions and model versions.
The Timefold Cloud Platform is shared, multi-tenant infrastructure. All tenants are upgraded together, and individual tenants cannot control platform upgrades. For control over versioning of the Platform, see self-hosting the platform.
Timefold models encapsulate domain-specific optimization logic. Model versions can differ between tenants and have a direct impact on optimization outcomes.
This separation ensures that:
-
the platform can move forward continuously for security and reliability;
-
customers can reason about behavioral changes at the model level.
Model version visibility in the UI
Timefold provides transparency into which model version your tenant is running at a given time.
In Manage tenant → Models, you can see:
-
Which models are enabled in your tenant.
-
The major API version of each model.
-
The current minor model version, including build time and commit information and the model’s dependencies (like solver version and SDK version).
Click the "…" at the top right of the models table to customize which columns you want to include e.g. model version and solver version.
This allows you to:
-
Verify exactly which model version is active in a tenant.
-
Correlate observed behavior with model changelogs.
-
Confirm whether a behavior change coincides with a model upgrade.
We will never automatically upgrade your models to a new major version. By default, however, we do upgrade models to newer minor versions. For more control over minor versions, please contact us.
Historical model version tracking
For every dataset, Timefold stores the model version that was used at the time the dataset was submitted.
Click the "…" at the top right of the datasets table to customize which columns you want to include e.g. model version and solver version.
This enables you to:
-
See when your tenant started using a new model version.
-
Identify which datasets were solved with which model version.
-
Compare optimization results across versions over time.
This is particularly useful when:
-
Investigating changes in optimization outcomes after an upgrade.
-
Supporting internal audits or post-incident analysis.
| If you received an unexpected warning or change in behavior, look for the first dataset that shows a new model version number - that is when the upgrade occurred. |
Platform version visibility
In Manage tenant → Details, you can see the current version of the Timefold Cloud Platform.
While platform versions are not customer-controlled, visibility helps you:
-
Correlate incidents or behavioral changes with platform releases.
-
Align observations with the public Timefold changelog.
-
Verify the platform state during incident investigations.
| In normal operation, customers should rarely need to concern themselves with the platform version. This information is provided primarily for transparency and diagnostics. |
Following model releases
Timefold publishes model changes in two complementary places:
-
docs.timefold.ai (this site) uses version numbers. This is relevant for self-hosted customers as well, where release dates differ per installation. Each model has a changelog page (accessible from the model’s documentation) listing changes per version.
-
The Timefold Platform changelog at feedback.timefold.ai/changelog uses dates. It reflects when the Timefold Cloud Platform EU was updated and when default model versions changed. Subscribe to this changelog to receive email notifications when a new release is deployed.
To answer "Did a new model version get deployed to my tenant, and when?", check the model version column in the datasets list: the first dataset using a new version shows when the upgrade happened.
| The model changelogs on this documentation site list changes by version number, not by date. To find the deployment date for a given version, refer to the Timefold Platform changelog. |
Documentation versioning
When the Platform is running multiple versions of the same model, Timefold exposes versioned model documentation.
This ensures that:
-
Documentation matches the model version you are running.
-
You do not accidentally rely on features introduced in later versions.
-
Validation and troubleshooting are based on the correct behavioral contract.
For models where this is supported, you’ll see a dropdown at the top right of the model’s documentation (next to the search bar) to switch to documentation about previous versions.
