chore: unify configuration properties

[rsynek]

Fixes #2496.

Renames configuration properties by the following logic:

• user-defined properties are prefixed with "ai.timefold.model"
• properties primarily injected by the platform are prefixed with "ai.timefold.platform" (this is not a clear split since user can override them e.g. for local testing)
• keep "ai.timefold.storage" as a separate category (mostly injected by the platform)

Some duplicate properties removed, timefold.application.version renamed to ai.timefold.model.api-version to better reflect what it is.

Related: https://github.com/TimefoldAI/timefold-solver-enterprise/pull/795

TODO:

• update docs when changes are approved

[Copilot]

Pull request overview

This PR standardizes service/model configuration property names under ai.timefold.model.* (user-defined) and ai.timefold.platform.* (platform-injected), including renaming the former timefold.application.version to ai.timefold.model.api-version and updating all in-repo usages touched by the service modules.

Changes:

• Renamed injected/configured property keys across worker, Quarkus deployment/runtime, maps client, and test modules to the new ai.timefold.model.* namespace (and kept platform-specific keys under ai.timefold.platform.*).
• Updated default application.properties templates to use ai.timefold.model.* placeholders (notably REST base path via ai.timefold.model.api-version).
• Updated Maven property names and build flags (.mvn/maven.config, service parent POM) to match the new configuration keys.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
service/worker/src/main/java/ai/timefold/solver/service/worker/impl/termination/TerminationConfigParams.java	Renames termination property keys to ai.timefold.model.termination.*.
service/worker/src/main/java/ai/timefold/solver/service/worker/impl/SolverWorker.java	Switches injected model name/version properties to ai.timefold.model.*.
service/worker/src/main/java/ai/timefold/solver/service/worker/impl/metrics/PlatformMetricsMeterFilter.java	Switches injected model identifier property to ai.timefold.model.id.
service/tools/maven-plugin/README.adoc	Documents the new ai.timefold.model.api-version key for model registration/version validation.
service/test/src/main/java/ai/timefold/solver/service/test/impl/quarkus/ModelRequestSerializationCallback.java	Renames test serialization toggle property to ai.timefold.model.* and fixes wording.
service/test-model/src/test/java/ai/timefold/solver/model/testmodel/OpenApiTest.java	Updates injected API version property key.
service/test-model/src/test/java/ai/timefold/solver/model/testmodel/EmployeeScheduleResourceTest.java	Updates injected API version property key.
service/test-model/src/test/java/ai/timefold/solver/model/testmodel/ApiVersion2ConfigProfile.java	Updates overridden API version property key.
service/test-model/src/main/resources/application.properties	Renames model metadata + test termination config keys to ai.timefold.model.*.
service/service-defaults/src/main/resources/application.properties	Updates model metadata placeholders and REST/OpenAPI/container naming to ai.timefold.model.*.
service/quarkus/runtime/src/main/java/ai/timefold/solver/service/quarkus/deployment/rest/schema/ValidatingReaderInterceptorContext.java	Renames schema validation enablement property to ai.timefold.model.schema.validation.enable.
service/quarkus/integration-tests/src/main/resources/application.properties	Updates integration-test config to ai.timefold.model.*.
service/quarkus/deployment/src/test/java/ai/timefold/solver/service/quarkus/deployment/VisualizationPagesConfigTest.java	Updates config keys and expected bind failure messages to the new prefix.
service/quarkus/deployment/src/test/java/ai/timefold/solver/service/quarkus/deployment/ApplicationVersionValidationTest.java	Updates expected error message content for renamed API version key.
service/quarkus/deployment/src/main/java/ai/timefold/solver/service/quarkus/deployment/TimefoldModelDescriptorProcessor.java	Renames all model descriptor metadata property keys and updates validation messaging.
service/quarkus/deployment/src/main/java/ai/timefold/solver/service/quarkus/deployment/config/VisualizationPagesConfig.java	Renames @ConfigMapping prefix to ai.timefold.model.visualization.
service/maps/service-client/src/main/java/ai/timefold/solver/service/maps/service/client/impl/MapServiceOptionsSupplier.java	Updates injected model id/version/resource property keys.
service/facade/service-parent/pom.xml	Renames Maven properties (including api-version) and Quarkus plugin propagated properties.
.mvn/maven.config	Renames the build flag property to ai.timefold.model.processing.disabled.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

service/service-defaults/src/main/resources/application.properties:86

• Docs in docs/src/modules/ROOT still reference the renamed properties (for example timefold.application.* and ai.timefold.platform.termination.*), so they will be incorrect after this change unless updated in the same release.

########################
# REST API configuration
########################
quarkus.rest.path=${ai.timefold.model.api-version}

[diogodanielsoaresferreira]

Also added an issue for the platform to sync with the new properties when we update to this solver version https://github.com/TimefoldAI/timefold-platform/issues/5238

[winklerm]

Thank you, looks good to me!

@rsynek @diogodanielsoaresferreira I have one concern that I would like to double check:

• After the properties are renamed, the models using the new solver service will be compatible only with the platform using the new solver service as well. That is business as usual.
• However, also the other way around applies: all older models will stop working with the new platform. This means we will have to upgrade and release new versions of all older models used in staggered releases for selected customers and upgrade all at once.

Is my understanding correct?

[diogodanielsoaresferreira]

Thank you, looks good to me!

@rsynek @diogodanielsoaresferreira I have one concern that I would like to double check:

* After the properties are renamed, the models using the new solver service will be compatible only with the platform using the new solver service as well. That is business as usual.

* However, also the other way around applies: all older models will stop working with the new platform. This means we will have to upgrade and release new versions of all older models used in staggered releases for selected customers and upgrade all at once.

Is my understanding correct?

Yes, technically that is correct. We can try to support old and new properties in the platform for a while, so that the models do not break.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 51 changed files in this pull request and generated no new comments.

Suppressed comments (3)

service/service-defaults/src/main/resources/application.properties:16

• The PR description says renamed user properties use the ai.timefold.model.* prefix, but the implementation consistently uses timefold.model.*, so the description (and any linked docs) should be updated or the properties should be renamed to avoid confusing users.

timefold.model.id=

service/quarkus/runtime/src/main/java/ai/timefold/solver/service/quarkus/deployment/config/TimefoldRenamedPropertiesFallbackInterceptor.java:40

• RENAMED_PROPERTY_PREFIXES relies on iteration order (“first match wins”) but Map.ofEntries() does not guarantee a deterministic entrySet() order, so prefix-to-legacy mapping can be applied inconsistently across JVMs/builds; use an insertion-ordered structure (for example, populate a LinkedHashMap in a static block) to guarantee matching order.

    // Renames of every property under a given prefix, checked in order; the first match wins.
    private static final Map<String, String> RENAMED_PROPERTY_PREFIXES = Map.ofEntries(
            Map.entry("timefold.model.default-config.", "ai.timefold.model.default-config."),
            Map.entry("timefold.model.termination.", "ai.timefold.platform.termination."),
            Map.entry("timefold.model.contact.", "timefold.application.contact."),

docs/src/modules/ROOT/pages/quickstart/service/getting-started.adoc:250

• The quickstart config snippet still uses legacy timefold.application.* metadata properties even though this PR renames them to timefold.model.*, which will cause copy-pasted configs to silently not bind without the fallback interceptor; update the snippet to the new property names.

timefold.model.termination.spent-limit=PT30S

[Copilot]

Pull request overview

Copilot reviewed 36 out of 51 changed files in this pull request and generated no new comments.

Suppressed comments (3)

service/service-defaults/src/main/resources/application.properties:28

• The new property prefixes in this PR use timefold.* (e.g. timefold.model.*, timefold.platform.*, timefold.storage.*), which contradicts the PR description that says user-defined/platform properties are prefixed with ai.timefold.model/ai.timefold.platform and storage stays ai.timefold.storage, so either update the description or rename the properties accordingly.

timefold.model.id=
timefold.model.name=
timefold.model.description=
timefold.model.build-timestamp=
timefold.model.contact.email=
timefold.model.contact.name=
timefold.model.contact.url=

#############################
# Default generic storage configuration
#############################

timefold.storage.bucket=${timefold.model.id}

docs/src/modules/ROOT/pages/quickstart/service/getting-started.adoc:254

• The example application.properties snippet mixes timefold.model.termination.* with timefold.application.* metadata keys, which is inconsistent with the property rename and will confuse readers.

timefold.model.termination.spent-limit=PT30S

# Application metadata — included in the generated OpenAPI specification
timefold.application.name=my-model
timefold.application.contact.email=info@example.com

service/quarkus/runtime/src/main/java/ai/timefold/solver/service/quarkus/deployment/config/TimefoldRenamedPropertiesFallbackInterceptor.java:33

• The comment claims prefix renames are "checked in order" but Map.ofEntries(...) does not guarantee iteration order, making this misleading for future maintainers.

    // Renames of every property under a given prefix, checked in order; the first match wins.

[rsynek]

Thank you, looks good to me!
@rsynek @diogodanielsoaresferreira I have one concern that I would like to double check:

* After the properties are renamed, the models using the new solver service will be compatible only with the platform using the new solver service as well. That is business as usual.

* However, also the other way around applies: all older models will stop working with the new platform. This means we will have to upgrade and release new versions of all older models used in staggered releases for selected customers and upgrade all at once.

Is my understanding correct?

Yes, technically that is correct. We can try to support old and new properties in the platform for a while, so that the models do not break.

I added a FallbackInterceptor to make sure the old property names can still be used. The "Secured Downstream Workflow" shows it works across all mature models. Haven't tried the platform yet.

CC @winklerm

[diogodanielsoaresferreira]

introduction.adoc and rest-api.adoc also need some property naming changes

[rsynek]

Renamed remaining references in the docs.

@triceo The PR is ready to merge once @mswiderski or @diogodanielsoaresferreira confirm it does not break the platform (depends if I missed something in the TimefoldRenamedPropertiesFallbackInterceptor).

[Copilot]

Pull request overview

Copilot reviewed 38 out of 53 changed files in this pull request and generated no new comments.

Suppressed comments (8)

docs/src/modules/ROOT/pages/running-timefold-solver/service/rest-api.adoc:89

• The documentation instructs overriding the non-existent timefold.model.version Maven property, but the build and runtime use timefold.model.api-version.

NOTE: To change the API version, override the `timefold.model.version` Maven property in the `pom.xml`.
The Quarkus property of the same name gets configured automatically from the Maven property.

docs/src/modules/ROOT/pages/running-timefold-solver/service/rest-api.adoc:99

• The demo-data path examples use timefold.model.version, which should be timefold.model.api-version to match the actual REST prefix property.

These are *not* nested under `<root>`: the path is `/{timefold.model.version}/demo-data`, not `/<root>/demo-data`.
For example, with `timefold.model.version=v1` this is `/v1/demo-data`.

docs/src/modules/ROOT/pages/running-timefold-solver/service/rest-api.adoc:83

• The documentation refers to timefold.model.version, but the service uses timefold.model.api-version (see service defaults) and timefold.model.version does not appear to be a valid property key.

This issue also appears in the following locations of the same file:

• line 88
• line 98

The SDK default configuration sets `quarkus.rest.path=${timefold.model.version}`, which Quarkus prepends to every `@Path` at runtime.
So for `timefold.model.version=v1` and `@Path("/timetables")`, `<root>` is `/v1/timetables`.

docs/src/modules/ROOT/pages/quickstart/service/getting-started.adoc:302

• This quickstart section references timefold.model.version, but the SDK config uses timefold.model.api-version for quarkus.rest.path.

NOTE: Do not include an API version in `@Path`. The SDK default configuration sets `quarkus.rest.path=${timefold.model.version}`, which Quarkus automatically prepends to every `@Path` at runtime.
So with `timefold.model.version=v1`, `@Path("/timetables")` is served at `/v1/timetables` — locally and on the platform.

docs/src/modules/ROOT/pages/deploying-to-platform/model-metadata.adoc:20

• This page references timefold.model.version, but the configured API version property is timefold.model.api-version.

`timefold.model.name`, `timefold.model.version`, and the `timefold.model.contact.*` properties are covered in xref:quickstart/service/getting-started.adoc[Getting started: building a service], since they are required for every model, service or not.

docs/src/modules/ROOT/pages/deploying-to-platform/introduction.adoc:85

• This platform concept points to timefold.model.version, but the actual API version property is timefold.model.api-version.

This is what appears in the consumer-facing API path (`/api/models/<model>/<version>`). The version comes from `timefold.model.version`.

service/worker/src/main/java/ai/timefold/solver/service/worker/impl/termination/TerminationConfigParams.java:7

• The PR description says the new naming scheme prefixes properties with ai.timefold.model/ai.timefold.platform, but this change uses timefold.model.*, so either the description or the property names should be aligned.
  service/test-model/src/build/openapi.json:22
• After fixing the schema title typo in EmployeeScheduleInputMetrics, this OpenAPI snapshot should be regenerated so it no longer contains "Emplyees" (currently present under components.schemas.EmployeeScheduleInputMetrics).

    "/v1/schedules" : {

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
90.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud