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.

Figure 1. A model’s API version and maturity

We have defined the following maturity levels:

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:

MAJOR version:
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.
MINOR version
Introduces new functionality, performance improvements, or behavioral changes that are intended to remain backward compatible at the API level.
PATCH version
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 table to customize which columns you want to include e.g. model version and solver version.

Figure 2. Models' version details in Manage tenant

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 table to customize which columns you want to include e.g. model version and solver version.

Figure 3. Datasets' model version details

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.

Platform version visibility

In Manage tenant → Details, you can see the current version of the Timefold Cloud Platform.

Figure 4. Platform’s version details

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.

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.

Figure 5. Model documentation version switcher