feat: Allow custom options in the RunConfiguration by cristianonicolai · Pull Request #2590 · TimefoldAI/timefold-solver

cristianonicolai · 2026-08-13T06:40:01Z

Related to https://github.com/TimefoldAI/timefold-platform/issues/5335

Copilot

Pull request overview

This PR extends the service API model to support passing arbitrary custom key/value options as part of a RunConfiguration, and exposes that capability through the generated OpenAPI schema.

Changes:

Add options: Map<String, String> to RunConfiguration, including constructor overloads and propagation through withTermination(...)/override(...).
Update the generated OpenAPI schema for RunConfiguration to include the new options object property.

Reviewed changes

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

File	Description
service/test-model/src/build/openapi.json	Adds `options` map property to the `RunConfiguration` schema.
service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java	Adds `options` field to the record and threads it through copy/override behavior.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

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

Suppressed comments (2)

service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java:94

The tag override guard uses !finalTags.isEmpty() which prevents inheriting tags when the current tags are empty (the default from constructors) and can unintentionally overwrite non-empty tags, so it should check finalTags.isEmpty() and assign via the accessor.

        if ((finalTags == null || !finalTags.isEmpty()) && configuration.tags() != null && !configuration.tags().isEmpty()) {
            finalTags = configuration.tags;
        }

service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java:26

Marking the new options property as @Schema(hidden = true) while the record schema forbids additional properties (@Schema(additionalProperties = Schema.False.class)) makes the OpenAPI contract disallow the very field this PR adds, so either expose it in the schema or revisit the schema-level additionalProperties policy.

        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(hidden = true) Map<String, String> options) {

Copilot

Pull request overview

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

Suppressed comments (2)

service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java:25

The new options field is marked @Schema(hidden = true), which contradicts the stated goal of allowing custom options because it will be omitted from generated OpenAPI/SDKs.

        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(
                description = "Optional tags to be assigned to the dataset.") @Size(max = 100) Set<String> tags,
        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(hidden = true) Map<String, String> options) {

service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java:15

Unlike other API domain records (for example ModelRequest.java:11), RunConfiguration no longer declares @Schema(additionalProperties = Schema.False.class), which can mislead OpenAPI clients into sending unknown fields that Jackson rejects (FAIL_ON_UNKNOWN_PROPERTIES), so re-add the annotation and keep custom data under the explicit options property.

public record RunConfiguration(

diogodanielsoaresferreira

Looks good to me 👍

triceo · 2026-08-18T09:13:55Z

I would appreciate if the Sonar/Copilot comments were resolved before we merge this. If the comment is wrong, it's fine to close it without any action - but very often, these comments are right.

cristianonicolai · 2026-08-18T09:28:07Z

@triceo I dont see much option here on what could be done to satisfy it both ways. Idea is that options is hidden/not visible since these are intended only for Platform use. Since options is hidden, schema validation would fail if it is inlucded in the payload, hence the decision to remove additionalProperties. I think its either like this or we accept to have it shown in the schema as a raw options map, which means we could include @Schema(additionalProperties = Schema.False.class) back. @mswiderski @rsynek wdyt?

mswiderski · 2026-08-18T09:33:34Z

I am more in favour of allowing additional properties rather than make the field visible to all. The whole idea with this was to not promote this to end consumers.

Copilot

Pull request overview

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

Suppressed comments (2)

service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java:84

The condition "(finalTags == null || !finalTags.isEmpty())" in override() overwrites existing non-empty tags and fails to inherit tags when the current set is empty; change it to check for emptiness and assign via the accessor.

        if ((finalTags == null || !finalTags.isEmpty()) && configuration.tags() != null && !configuration.tags().isEmpty()) {
            finalTags = configuration.tags;
        }

service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java:16

Dropping @Schema(additionalProperties = Schema.False.class) from RunConfiguration makes the OpenAPI schema accept arbitrary unknown properties even though the service ObjectMapper is configured to fail on unknown properties, leading to surprising request failures unless schema and deserialization are aligned.

public record RunConfiguration(
        @Schema(nullable = true,

Copilot

Pull request overview

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

Suppressed comments (1)

service/definition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java:25

Removing @Schema(additionalProperties = Schema.False.class) from RunConfiguration makes the OpenAPI schema accept arbitrary unknown run configuration fields (not just the intended options), which can desync client-side/schema validation from the strict Jackson mapping; consider keeping additionalProperties=false and exposing a documented options map property instead of hiding it (or otherwise constraining schema permissiveness).

public record RunConfiguration(
        @Schema(nullable = true,
                description = "Optional name to be given to the dataset. If not provided, the name will be generated.") @Size(
                        min = 0, max = 255) String name,
        @JsonInclude(JsonInclude.Include.NON_NULL) SolverTerminationConfig termination,
        @Schema(nullable = true,
                description = "Optional maximum number of threads to be used for solving.",
                minimum = "1") @JsonInclude(JsonInclude.Include.NON_EMPTY) @Positive Integer maxThreadCount,
        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(
                description = "Optional tags to be assigned to the dataset.") @Size(max = 100) Set<String> tags,
        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(hidden = true) Map<String, String> options) {

rsynek · 2026-08-20T10:50:12Z

        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(
-                description = "Optional tags to be assigned to the dataset.") @Size(max = 100) Set<String> tags) {
+                description = "Optional tags to be assigned to the dataset.") @Size(max = 100) Set<String> tags,
+        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(hidden = true) Map<String, String> options) {


If it's hidden from the schema, it cannot be sent from the client, since the platform gateway will consider it an invalid parameter, correct?

So we allow these options to only be sent inside the cluster.

the idea is that it can still be part of the POST body, so it wont fail, but only the Platform would know how to handle it. Sort of hidden parameter to be used.

I have slightly different view, shall we have a short meeting tomorrow or on Monday three of us (@cristianonicolai @rsynek )?

rsynek · 2026-08-20T10:55:38Z

        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(
-                description = "Optional tags to be assigned to the dataset.") @Size(max = 100) Set<String> tags) {
+                description = "Optional tags to be assigned to the dataset.") @Size(max = 100) Set<String> tags,
+        @JsonInclude(JsonInclude.Include.NON_NULL) @Schema(hidden = true) Map<String, String> options) {


Do we want to keep it open for any parameters?

If we want to configure a custom seed, it will probably originate from the platform configuration profile, but we will need to set quarkus.timefold.solver.random-seed={some-unknown-key} to propagate it to the solver.

If we make change it to a Map<InternalOptions, String>, where InternalOptions is an enum, we have a good control over what we send to the model pods as hidden options.

Idea was to keep it open to allow for other customization in the future. Other options that wouldnt be public available. I think if we add a InternalOptions enum, it would still show up in the OpenAPI as type no?
Regarding the quarkus.timefold.solver.random-seed that would be set as env var by the Platform, at least thats how I understood this need to be done. So despite changing the RunConfiguration here, thats only because we need to extend it to accept these other parameters. Do you see another way this should be done?

cristianonicolai deployed to internal August 13, 2026 06:40 — with GitHub Actions Active

cristianonicolai force-pushed the feat/seed branch from e4a0e9d to 630af29 Compare August 17, 2026 07:12

cristianonicolai deployed to internal August 17, 2026 07:12 — with GitHub Actions Active

cristianonicolai changed the title ~~feat: Allow to set random-seed for solver in the RunConfiguration~~ feat: Allow custom options in the RunConfiguration Aug 17, 2026

cristianonicolai force-pushed the feat/seed branch from 630af29 to 98aa11a Compare August 17, 2026 07:13

cristianonicolai marked this pull request as ready for review August 17, 2026 07:13

cristianonicolai requested a review from triceo as a code owner August 17, 2026 07:13

Copilot AI lite review requested due to automatic review settings August 17, 2026 07:13

cristianonicolai requested a review from rsynek as a code owner August 17, 2026 07:13

cristianonicolai deployed to internal August 17, 2026 07:13 — with GitHub Actions Active

Copilot started reviewing on behalf of cristianonicolai August 17, 2026 07:13 View session

cristianonicolai requested a review from mswiderski August 17, 2026 07:14

Copilot AI reviewed Aug 17, 2026

View reviewed changes

Comment thread ...inition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java Outdated

mswiderski reviewed Aug 17, 2026

View reviewed changes

Comment thread ...inition/src/main/java/ai/timefold/solver/service/definition/api/domain/RunConfiguration.java Outdated

Copilot AI review requested due to automatic review settings August 17, 2026 13:41

cristianonicolai force-pushed the feat/seed branch from 98aa11a to c6e016d Compare August 17, 2026 13:41

cristianonicolai requested a deployment to external August 17, 2026 13:41 — with GitHub Actions Waiting

Copilot started reviewing on behalf of cristianonicolai August 17, 2026 13:41 View session

Copilot AI reviewed Aug 17, 2026

cristianonicolai requested a lite review from Copilot August 18, 2026 00:10

Copilot started reviewing on behalf of cristianonicolai August 18, 2026 00:10 View session

Copilot AI reviewed Aug 18, 2026

View reviewed changes

mswiderski approved these changes Aug 18, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 18, 2026 06:21

cristianonicolai force-pushed the feat/seed branch from c6e016d to 2e83b23 Compare August 18, 2026 06:21

cristianonicolai deployed to internal August 18, 2026 06:21 — with GitHub Actions Active

Copilot started reviewing on behalf of cristianonicolai August 18, 2026 06:21 View session

Copilot AI reviewed Aug 18, 2026

View reviewed changes

diogodanielsoaresferreira approved these changes Aug 18, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 20, 2026 05:00

cristianonicolai force-pushed the feat/seed branch from 2e83b23 to 9194ebe Compare August 20, 2026 05:00

cristianonicolai deployed to internal August 20, 2026 05:00 — with GitHub Actions Active

Copilot started reviewing on behalf of cristianonicolai August 20, 2026 05:00 View session

Copilot AI reviewed Aug 20, 2026

View reviewed changes

feat: Allow custom options in the RunConfiguration

35a3605

Copilot AI review requested due to automatic review settings August 20, 2026 05:44

cristianonicolai force-pushed the feat/seed branch from 9194ebe to 35a3605 Compare August 20, 2026 05:44

cristianonicolai deployed to internal August 20, 2026 05:44 — with GitHub Actions Active

Copilot started reviewing on behalf of cristianonicolai August 20, 2026 05:44 View session

Copilot AI reviewed Aug 20, 2026

View reviewed changes

rsynek reviewed Aug 20, 2026

View reviewed changes

Uh oh!

Conversation

cristianonicolai commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

diogodanielsoaresferreira left a comment

Choose a reason for hiding this comment

Uh oh!

triceo commented Aug 18, 2026

Uh oh!

cristianonicolai commented Aug 18, 2026

Uh oh!

mswiderski commented Aug 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

rsynek Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

cristianonicolai Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

mswiderski Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

rsynek Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

cristianonicolai Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

cristianonicolai commented Aug 13, 2026 •

edited

Loading