fix: remove model.api.version (#2542)

Fixes #2516.

Also, removed the SDK version from metadata (and keep only the Solver
version).

See also:
TimefoldAI/timefold-solver-enterprise#791

The API version is now defined by the `timefold.application.version` in
the `pom.xml`. The maven property is used to define a model descriptor
classifier, e.g.
`timefold-pickup-delivery-routing-descriptor-1.2.0-v1.zip`. Thus, it
must be defined in `pom.xml` and not in the `application.properties`,
where it gets injected by the Quarkus maven plugin.

The service-parent `pom.xml` defines the default value `v1`, which can
be overridden in the model `pom.xml`.

The user must not override the value in `application.properties`, which
may lead to the model being updated to the new version, but its model
descriptor classifier still being `v1`.

Author: rsynek

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

@@ -250,7 +250,6 @@ Create the `src/main/resources/application.properties` file:
 ai.timefold.platform.termination.spent-limit=PT30S
 
 # Application metadata — included in the generated OpenAPI specification
-model.api.version=v1
 timefold.application.name=my-model
 timefold.application.contact.email=info@example.com
 timefold.application.contact.name=Your Name
@@ -264,7 +263,6 @@ For production use, consider at least five minutes (`PT5M`) to allow the solver
 NOTE: The per-request `config.run.termination.spentLimit` field in the POST body (shown later) overrides this default for individual runs.
 
 `timefold.application.name` and the contact fields are *required* metadata.
-`model.api.version` is required (for example `v1`) and is used as the default for `timefold.application.version` and `quarkus.rest.path`.
 They are used to identify your service, validate the JSON schema of requests, and populate the generated OpenAPI specification.
 
 == REST API
@@ -300,8 +298,8 @@ public interface TimetableResource extends ModelRest {
 This is the most basic version of the interface. The SDK will automatically create multiple xref:running-timefold-solver/service/rest-api.adoc[REST API endpoints] for optimization actions.
 The `@Path` annotation is used to configure the base path of all those endpoints.
 
-NOTE: Do not include an API version in `@Path`. The SDK default configuration sets `quarkus.rest.path=${model.api.version}`, which Quarkus automatically prepends to every `@Path` at runtime.
-So with `model.api.version=v1`, `@Path("/timetables")` is served at `/v1/timetables` — locally and on the platform.
+NOTE: Do not include an API version in `@Path`. The SDK default configuration sets `quarkus.rest.path=${timefold.application.version}`, which Quarkus automatically prepends to every `@Path` at runtime.
+So with `timefold.application.version=v1`, `@Path("/timetables")` is served at `/v1/timetables` — locally and on the platform.
 
 == Running and manually testing the model
 

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

@@ -79,21 +79,24 @@ Since an xref:#openAPISpecification[OpenAPI specification] will also be automati
 
 The REST module generates several endpoints; the following are the core endpoints.
 The `<root>` is the full served path, which is the model API version prefix followed by the value of the `@Path` annotation.
-The SDK default configuration sets `quarkus.rest.path=${model.api.version}`, which Quarkus prepends to every `@Path` at runtime.
-So for `model.api.version=v1` and `@Path("/timetables")`, `<root>` is `/v1/timetables`.
+The SDK default configuration sets `quarkus.rest.path=${timefold.application.version}`, which Quarkus prepends to every `@Path` at runtime.
+So for `timefold.application.version=v1` and `@Path("/timetables")`, `<root>` is `/v1/timetables`.
 
 NOTE: Do not include the version in your `@Path` annotation. The SDK handles it automatically via `quarkus.rest.path`.
 Including it (e.g. `@Path("/v1/timetables")`) results in a doubled prefix (`/v1/v1/timetables`) at runtime.
 
+NOTE: To change the API version, override the `timefold.application.version` Maven property in the `pom.xml`.
+The Quarkus property of the same name gets configured automatically from the Maven property.
+
 - `GET /<root>`: Retrieve all registered optimization datasets
 - `POST /<root>`: Create a new optimization dataset
 - `GET /<root>/\{id\}`: Retrieve the (intermediate) result of a dataset optimization run
 - `GET /<root>/\{id\}/score-analysis`: Retrieve score analysis of an optimization dataset
 - `DELETE /<root>/\{id\}`: Terminate a dataset optimization run
 
 If your model provides xref:./demo-data.adoc[demo data], the following endpoints are also created.
-These are *not* nested under `<root>`: the path is `/{model.api.version}/demo-data`, not `/<root>/demo-data`.
-For example, with `model.api.version=v1` this is `/v1/demo-data`.
+These are *not* nested under `<root>`: the path is `/{timefold.application.version}/demo-data`, not `/<root>/demo-data`.
+For example, with `timefold.application.version=v1` this is `/v1/demo-data`.
 
 - `GET /v<version>/demo-data`: Retrieve all available demo dataset ids.
 - `GET /v<version>/demo-data/\{demoDataId\}`: Retrieve the demo dataset with the given identifier

service/definition/src/main/java/ai/timefold/solver/service/definition/internal/descriptor/ModelBuildInfo.java

@@ -1,5 +1,9 @@
 package ai.timefold.solver.service.definition.internal.descriptor;
 
-public record ModelBuildInfo(String solverVersion, String sdkVersion, String version, String buildTime, String branch,
+public record ModelBuildInfo(String solverVersion, String version, String buildTime, String branch,
         String buildCommit) {
+
+    public static ModelBuildInfo empty() {
+        return new ModelBuildInfo(null, null, null, null, null);
+    }
 }

service/facade/service-parent/pom.xml

@@ -48,14 +48,14 @@
     <ai.timefold.platform.model.test.api-key>${env.TF_PLATFORM_TEST_API_KEY}</ai.timefold.platform.model.test.api-key>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 
-    <!-- the model api version has to be kept in sync with the model version in model POM -->
-    <model.api.version>v1</model.api.version>
+    <!-- the application version defines the API version of the model -->
+    <timefold.application.version>v1</timefold.application.version>
     <!-- default configuration, can be overridden by a model if needed -->
     <ai.timefold.model.descriptor.repository>${project.artifactId}</ai.timefold.model.descriptor.repository>
     <ai.timefold.model.native.image.path>${project.build.directory}/${project.build.finalName}-runner</ai.timefold.model.native.image.path>
     <ai.timefold.model.descriptor.groupId>${project.groupId}</ai.timefold.model.descriptor.groupId>
     <ai.timefold.model.descriptor.artifactId>${project.artifactId}-descriptor</ai.timefold.model.descriptor.artifactId>
-    <ai.timefold.model.descriptor.classifier>${model.api.version}</ai.timefold.model.descriptor.classifier>
+    <ai.timefold.model.descriptor.classifier>${timefold.application.version}</ai.timefold.model.descriptor.classifier>
     <ai.timefold.model.descriptor.version>${project.version}</ai.timefold.model.descriptor.version>
     <ai.timefold.model.descriptor.file>${project.build.directory}/model-descriptor.zip</ai.timefold.model.descriptor.file>
     <ai.timefold.model.descriptor.repository.id>github</ai.timefold.model.descriptor.repository.id>
@@ -596,7 +596,7 @@
             <extensions>true</extensions>
             <configuration>
               <properties>
-                <model.api.version>${model.api.version}</model.api.version>
+                <timefold.application.version>${timefold.application.version}</timefold.application.version>
               </properties>
             </configuration>
             <executions>

service/quarkus/deployment/src/main/java/ai/timefold/solver/service/quarkus/deployment/TimefoldModelDescriptorProcessor.java

@@ -347,7 +347,6 @@ void generateBuildTimeInfoBean(ModelBuildInfoRecorder recorder,
 
         String solverVersion =
                 SolverVersionUtils.bareVersion(SolverVersionUtils.CORE_GIT_PROPERTIES, SolverFactory.class);
-        String sdkVersion = SolverVersionUtils.bareVersion(ModelDescriptor.class);
         String version = buildInfo != null ? (String) buildInfo.getValue().get("version") : null;
         String buildTime = buildInfo != null ? (String) buildInfo.getValue().get("time") : null;
         if (buildTime != null) {
@@ -359,7 +358,7 @@ void generateBuildTimeInfoBean(ModelBuildInfoRecorder recorder,
                 gitInfo != null ? (String) ((Map<String, Object>) gitInfo.getValue().getOrDefault("commit", Map.of())).get("id")
                         : null;
 
-        ModelBuildInfo modelBuildInfo = new ModelBuildInfo(solverVersion, sdkVersion, version, buildTime, branch, commit);
+        ModelBuildInfo modelBuildInfo = new ModelBuildInfo(solverVersion, version, buildTime, branch, commit);
 
         byte[] buildInfoContent = MAPPER.writeValueAsBytes(modelBuildInfo);
         Path buildInfoFile = Paths.get(out.getOutputDirectory().toString(), "timefold", "build-info.json");

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

@@ -16,7 +16,6 @@ config_ordinal=230
 timefold.application.id=custom-timefold-model
 timefold.application.name=Custom Timefold model
 timefold.application.description=
-timefold.application.version=${model.api.version}
 timefold.application.build-timestamp=
 timefold.application.contact.email=
 timefold.application.contact.name=
@@ -84,7 +83,7 @@ quarkus.log.console.darken=1
 ########################
 # REST API configuration
 ########################
-quarkus.rest.path=${model.api.version}
+quarkus.rest.path=${timefold.application.version}
 
 # Workaround for https://github.com/quarkusio/quarkus/issues/55362
 quarkus.rest.jackson.optimization.enable-reflection-free-serializers=false
@@ -108,10 +107,10 @@ mp.openapi.extensions.smallrye.remove-unused-schemas.enable=true
 ########################
 image.native-suffix=-native
 # the end model should also set %container.quarkus.container-image.group
-%container.quarkus.container-image.name=model-${timefold.application.id}-${model.api.version}
+%container.quarkus.container-image.name=model-${timefold.application.id}-${timefold.application.version}
 
 # the end model should also set %container-native.quarkus.container-image.group
-%container-native.quarkus.container-image.name=model-${timefold.application.id}-${model.api.version}${image.native-suffix}
+%container-native.quarkus.container-image.name=model-${timefold.application.id}-${timefold.application.version}${image.native-suffix}
 
 ########################################################################
 # Default configuration profile settings relevant for the platform only

service/test-model/src/main/resources/application.properties

@@ -1,7 +1,6 @@
 ########################
 # Timefold application info
 ########################
-model.api.version=v1
 timefold.application.name=Integration Tests - Simplified Employee Shift Scheduling model
 timefold.application.id=integration-tests-simplified-employee-shift-scheduling
 %test.ai.timefold.platform.termination.best-score-limit=0hard/0medium/*soft

service/test-model/src/test/java/ai/timefold/solver/model/testmodel/ApiVersion2ConfigProfile.java

@@ -12,7 +12,7 @@ public class ApiVersion2ConfigProfile implements QuarkusTestProfile {
 
     @Override
     public Map<String, String> getConfigOverrides() {
-        return Map.of("model.api.version", "v2-beta");
+        return Map.of("timefold.application.version", "v2-beta");
     }
 
 }

service/test-model/src/test/java/ai/timefold/solver/model/testmodel/EmployeeScheduleResourceTest.java

@@ -92,8 +92,8 @@ public class EmployeeScheduleResourceTest {
     InMemorySink<FinalBestSolutionEvent> finalBestSolutionSink;
     InMemorySink<DatasetComputedEvent> datasetComputedSink;
 
-    @ConfigProperty(name = "model.api.version")
-    String modelApiVersion;
+    @ConfigProperty(name = "timefold.application.version")
+    String applicationVersion;
 
     @TestHTTPResource
     URI baseUri;
@@ -108,7 +108,7 @@ Multi<SseEvent<Metadata<HardMediumSoftScore>>> getEvents(@PathParam("apiversion"
 
     @BeforeEach
     void before() {
-        RestAssured.basePath = "/" + modelApiVersion;
+        RestAssured.basePath = "/" + applicationVersion;
         datasetComputedSink = connector.sink(SolverChannels.DATASET_COMPUTED);
         datasetComputedSink.clear();
         initSolutionSink = connector.sink(SolverChannels.INIT_SOLUTION);
@@ -229,7 +229,7 @@ void solveEmployeeScheduleWithWatching() throws InterruptedException {
         List<Metadata<HardMediumSoftScore>> receivedResults = new ArrayList<>();
 
         CountDownLatch waitOnRequestSubscribtion = new CountDownLatch(1);
-        Multi<SseEvent<Metadata<HardMediumSoftScore>>> eventStream = client.getEvents(modelApiVersion, metadata.getId());
+        Multi<SseEvent<Metadata<HardMediumSoftScore>>> eventStream = client.getEvents(applicationVersion, metadata.getId());
 
         Cancellable subscription = eventStream.subscribe().with(
                 event -> {

service/test-model/src/test/java/ai/timefold/solver/model/testmodel/OpenApiTest.java

@@ -27,12 +27,12 @@
 @QuarkusTest
 public class OpenApiTest {
 
-    @ConfigProperty(name = "model.api.version")
-    String modelApiVersion;
+    @ConfigProperty(name = "timefold.application.version")
+    String applicationVersion;
 
     @Test
     public void testOperationHasPriorityQueryParam() throws IOException {
-        Path openApiFilePath = Paths.get("target/timefold/timefold-test-model_" + modelApiVersion + "/openapi/service.json");
+        Path openApiFilePath = Paths.get("target/timefold/timefold-test-model_" + applicationVersion + "/openapi/service.json");
 
         if (!Files.exists(openApiFilePath)) {
             fail("OpenAPI file not found at: " + openApiFilePath.toAbsolutePath());
@@ -48,7 +48,7 @@ public void testOperationHasPriorityQueryParam() throws IOException {
         operationsId.forEach(operationId -> assertOperation(openAPI, operationId));
 
         // verify that paths start with api version configured
-        openAPI.getPaths().getPathItems().forEach((k, v) -> assertThat(k).startsWith("/" + modelApiVersion));
+        openAPI.getPaths().getPathItems().forEach((k, v) -> assertThat(k).startsWith("/" + applicationVersion));
     }
 
     private void assertOperation(OpenAPI openAPI, String operationId) {