[Picazsoo]

Today kotlin-spring ignores constraints on array items:

val tags: kotlin.collections.List<kotlin.String>? = null   // items: maxLength: 10 is ignored
val pets: kotlin.collections.List<Pet>? = null              // nested Pet is never validated

With this PR (and useBeanValidation=true):

val tags: kotlin.collections.List<@Size(max = 10) kotlin.String>? = null
val pets: kotlin.collections.List<@Valid Pet>? = null

This follows the existing Java logic in AbstractJavaCodegen (getTypeDeclarationWithBeanValidation / getBeanValidation / getExtraListAnnotation).

What changes

• AbstractKotlinCodegen.getTypeDeclaration(): for arrays and sets, the element type is rendered as <extra annotations> <bean validation> Type[?]. The protected hooks behind it are no-ops by default, so other Kotlin generators (kotlin client, kotlin-server, kotlin-wiremock, …) produce identical output. Only KotlinSpringServerCodegen overrides them. A useBeanValidationOnMapValueType() hook (default false) is ready for a follow-up on map values.
• Bean validation on elements (useBeanValidation=true):
  • $ref to object or composed (oneOf/anyOf/allOf, including normalizer-wrapped allOf: [$ref]) models → @Valid
  • string / number / integer / long constraints → @Size, @Pattern, @Email, @Min, @Max, @DecimalMin, @DecimalMax
  • enum and free-form object items → no annotation
• x-field-extra-annotation on items (string or list) is added to the element type. This also works for inline enum items.
• New option additionalItemsAnnotations (kotlin-spring): ;- or newline-separated annotations added to every collection element type. Unlike Java, @NotNull is not removed for nullable: true items. In Kotlin, element nullability is expressed by ?, which the compiler checks and Jackson 3's Kotlin module enforces on deserialization.
• Nested collections work recursively: List<List<@Size(max = 3) kotlin.String>>.
• Nullability is kept: List<@Valid Pet?>.
• Annotations go before qualified names (@Size(max = 3) kotlin.String). Kotlin doesn't need Java's java.lang.@Size String placement.

Making it effective at runtime

• By default the Kotlin compiler does not write type-use annotations to bytecode. All kotlin-spring Maven/Gradle templates (spring-boot, spring-cloud, spring-declarative-http-interface; SB2/3/4) now pass -Xemit-jvm-type-annotations when useBeanValidation=true. The option description tells users with their own build to add it.
• Verified at runtime on the Spring Boot 3 sample: element constraints on model properties (including nested lists/sets) and on controller list parameters are enforced.
• Response types carry no element annotations. With visible type annotations, ResponseEntity<List<@Valid Pet>> made every call fail with HV000197 (no ValueExtractor for ResponseEntity, see @NotNull on a web endpoint generic type parameter fails spring-projects/spring-framework#32375). Element annotations are therefore not added when rendering response types, so return signatures stay as they were before this PR.

Unchanged on purpose

• Existing container-level annotations: @field:Valid on container properties, @get:Size for minItems/maxItems, @Valid @RequestBody / @RequestParam on parameters.
• Reactive request bodies render Flow<{{{baseType}}}> and stay without element annotations.
• Annotations on API parameters/request bodies beyond what dataType already produces are handled in [JAVA-SPRING;KOTLIN-SPRING] feature: x-field-extra-annotation parity for kotlin-spring params + new x-request-body-extra-annotation + --inject-operation-vendor-extensions #24780.

dataType audit

I checked the places where kotlin-spring uses dataType/returnType as something other than a type: default values ({{{dataType}}}("…") is scalar-only), @ApiResponse(implementation = X::class) (uses baseType), sealed/oneOf interfaces (baseType), x-kotlin-implements overrides (same types on both sides), the reactive x-reactive-array-string-return check, and enum-array branches. Inline enum arrays bypassed dataType, so I fixed them in dataClassReqVar/dataClassOptVar.

Imports

• Models/APIs: existing javax/jakarta.validation.* wildcard imports already cover the new annotations.
• delegate / service / serviceImpl / api_test: a new beanValidationImports.mustache partial imports only the annotations actually used on element types in that file. Operation x-extra-imports are added there when signatures contain custom element annotations.
• x-*-message values are escaped as Kotlin string literals.

Docs

• docs/generators/kotlin-spring.md: new additionalItemsAnnotations option.
• x-field-extra-annotation description in VendorExtension now says it applies to the element type on items. Because the vendor extension description is shared, this regenerates one line in several Java/Spring/Kotlin generator docs.

Samples

• New config bin/configs/kotlin-spring-boot-collection-item-annotations.yaml with its own annotated spec copy (petstore-collection-item-annotations.yaml), added to the samples-kotlin-server-jdk17 workflow matrix.
• I regenerated all Kotlin configs. Only kotlin-spring samples changed: build files (compiler flag) and element-annotated types/imports.

Testing

• ./mvnw -q -pl modules/openapi-generator test -Dtest='KotlinSpringServerCodegenTest' -Dsurefire.failIfNoSpecifiedTests=false -Djacoco.skip=true → passed (kotlin.spring.KotlinSpringServerCodegenTest: 309 tests, kotlin.KotlinSpringServerCodegenTest: 12 tests, 0 failures)
• New tests cover $ref/oneOf/allOf/allOf:[$ref] items, all constraint annotations, uniqueItems sets, enum/free-form items, nullable items, nested arrays, x-field-extra-annotation (string/list), additionalItemsAnnotations alone and combined, useBeanValidation=false, response types without element annotations, imports in delegate/service files, and unchanged kotlin client output.
• Samples compiled locally: the new collection sample plus delegate, reactive, swagger2, openApiNullable+modelMutable, spring-cloud, declarative-interface, SB2 (javax), SB3, SB4.

PR checklist

• Read the contribution guidelines.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

---

Summary by cubic

Makes bean validation actually apply to list/set element types in the Kotlin Spring server generator, so nested collection items are validated at runtime instead of only the collection itself.

• Applies @Valid, @Size, @Pattern, @Email, @Min/@Max, and @DecimalMin/@DecimalMax from array items schemas to the element type (e.g. List<@Valid Pet>), plus x-field-extra-annotation and a new additionalItemsAnnotations option for element-type annotations.
• Opt-in via no-op hooks in AbstractKotlinCodegen; only KotlinSpringServerCodegen overrides them, so other Kotlin generators are unchanged.
• Generated Maven/Gradle builds pass -Xemit-jvm-type-annotations when useBeanValidation is enabled so the annotations reach bytecode, and element annotations are kept out of return types because Hibernate Validator can't extract values from ResponseEntity/Flow.
• Regenerates Kotlin Spring samples and adds a collection-item-annotation sample config.

^{Written for commit 0319295. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 245 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/server/petstore/kotlin-spring-cloud-4/src/main/kotlin/org/openapitools/api/PetApi.kt">

<violation number="1" location="samples/server/petstore/kotlin-spring-cloud-4/src/main/kotlin/org/openapitools/api/PetApi.kt:71">
P2: These annotations are nested inside `ResponseEntity`, which Bean Validation does not traverse as a container, so the generated endpoints still will not validate returned `Pet` elements at runtime. Apply validation to an actually traversed response body or configure a supported value extractor for the response wrapper.</violation>
</file>

<file name="samples/server/petstore/kotlin-springboot-collection-item-annotations/build.gradle.kts">

<violation number="1" location="samples/server/petstore/kotlin-springboot-collection-item-annotations/build.gradle.kts:16">
P1: This Gradle build cannot be evaluated because `plugins {}` appears after regular build logic and uses a local version variable inside the constrained plugin DSL. Move the block to the top and use literal versions (or declare them through `pluginManagement`).</violation>
</file>

<file name="samples/server/petstore/kotlin-springboot-no-response-entity/src/main/kotlin/org/openapitools/api/PetApiController.kt">

<violation number="1" location="samples/server/petstore/kotlin-springboot-no-response-entity/src/main/kotlin/org/openapitools/api/PetApiController.kt:66">
P2: These annotations are retained only in Kotlin source for this sample, so Spring/Hibernate Validator cannot cascade validation into the returned `Pet` elements at runtime. Add `-Xemit-jvm-type-annotations` to the sample's Kotlin compiler arguments (and the generated sample configuration) so the new return-value validation works.</violation>
</file>

<file name="samples/server/petstore/kotlin-spring-default/src/main/kotlin/org/openapitools/api/PetApiController.kt">

<violation number="1" location="samples/server/petstore/kotlin-spring-default/src/main/kotlin/org/openapitools/api/PetApiController.kt:96">
P2: The new `@Valid` is nested inside `ResponseEntity`, so method validation cannot unwrap the response wrapper and traverse the `List` elements. Generate a return shape that exposes `List<@Valid Pet>` directly, or provide an explicit `ResponseEntity` value extractor/response-validation path; otherwise these annotations do not enable the advertised runtime validation.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

P1: This Gradle build cannot be evaluated because plugins {} appears after regular build logic and uses a local version variable inside the constrained plugin DSL. Move the block to the top and use literal versions (or declare them through pluginManagement).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At samples/server/petstore/kotlin-springboot-collection-item-annotations/build.gradle.kts, line 16:

<comment>This Gradle build cannot be evaluated because `plugins {}` appears after regular build logic and uses a local version variable inside the constrained plugin DSL. Move the block to the top and use literal versions (or declare them through `pluginManagement`).</comment>

<file context>
@@ -0,0 +1,45 @@
+    kotlinOptions.jvmTarget = "17"
+}
+
+plugins {
+    val kotlinVersion = "1.9.25"
+    id("org.jetbrains.kotlin.jvm") version kotlinVersion
</file context>

[Picazsoo]

Not valid for the Kotlin DSL: plugins {} is extracted and evaluated first regardless of its position, and a local val inside the block is supported. The layout comes unchanged from the existing template (only the compiler flag was added), and sh ./gradlew help evaluates this script successfully.

[cubic-dev-ai]

2 issues found across 279 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/server/petstore/kotlin-springboot-modelMutable/README.md">

<violation number="1" location="samples/server/petstore/kotlin-springboot-modelMutable/README.md:16">
P2: `./gradlew` is not executable in this sample: `gradlew` is tracked with mode `100644`, so this command fails with permission denied on POSIX checkouts. Mark `gradlew` executable in Git (mode `100755`).</violation>
</file>

<file name="samples/server/petstore/kotlin-springboot-bigdecimal-default/README.md">

<violation number="1" location="samples/server/petstore/kotlin-springboot-bigdecimal-default/README.md:7">
P2: `./gradlew` is not executable in this sample, so the documented Gradle build fails with `Permission denied` on POSIX systems. Mark `gradlew` executable in Git (mode `100755`) before documenting direct execution.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 279 files

<sub>Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

3 issues found across 279 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/server/petstore/kotlin-springboot-integer-enum/README.md">

<violation number="1" location="samples/server/petstore/kotlin-springboot-integer-enum/README.md:16">
P2: This Gradle command cannot start the documented server: the build disables `bootJar` and the sample has no application `main` class, so the produced JAR has no executable entry point. Enable and configure `bootJar` or remove the `java -jar` step and the claim that this build runs the server.</violation>
</file>

<file name="samples/server/petstore/kotlin-spring-oneof-jackson-default-impl/README.md">

<violation number="1" location="samples/server/petstore/kotlin-spring-oneof-jackson-default-impl/README.md:16">
P2: This Gradle command cannot start the sample: the project has no application entry point and disables `bootJar`, so the generated JAR is not executable. Add/configure a Spring Boot main class and enable `bootJar`, or remove the `java -jar` launch step and update the surrounding startup guidance.</violation>
</file>

<file name="samples/server/others/kotlin-springboot/oneOf-discriminator/README.md">

<violation number="1" location="samples/server/others/kotlin-springboot/oneOf-discriminator/README.md:16">
P2: This new Gradle command cannot start the advertised server: the build disables `bootJar`, and this sample has no application entry point or executable JAR manifest. Either add/configure a Spring Boot main application and enable `bootJar`, or remove the `java -jar` launch instruction.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: This Gradle command cannot start the documented server: the build disables bootJar and the sample has no application main class, so the produced JAR has no executable entry point. Enable and configure bootJar or remove the java -jar step and the claim that this build runs the server.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At samples/server/petstore/kotlin-springboot-integer-enum/README.md, line 16:

<comment>This Gradle command cannot start the documented server: the build disables `bootJar` and the sample has no application `main` class, so the produced JAR has no executable entry point. Enable and configure `bootJar` or remove the `java -jar` step and the claim that this build runs the server.</comment>

<file context>
@@ -4,18 +4,21 @@ This Kotlin based [Spring Boot](https://spring.io/projects/spring-boot) applicat
+To build the project using gradle on Linux or macOS, run:
 ```bash
-gradle build && java -jar build/libs/openapi-spring-1.0.0.jar
+sh ./gradlew build && java -jar build/libs/openapi-spring-1.0.0.jar
+```
+
</file context>

[Picazsoo]

Valid, but pre-existing and out of scope: for interfaceOnly=true projects there is no Application.kt, bootJar is disabled and the Maven boot plugin is omitted, so the upstream java -jar instructions (Maven and Gradle) never worked. This PR no longer touches the README: I reverted all README template changes to keep it focused on collection element annotations. The interfaceOnly-aware wording will go into a separate docs PR.

[cubic-dev-ai]

P2: This Gradle command cannot start the sample: the project has no application entry point and disables bootJar, so the generated JAR is not executable. Add/configure a Spring Boot main class and enable bootJar, or remove the java -jar launch step and update the surrounding startup guidance.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At samples/server/petstore/kotlin-spring-oneof-jackson-default-impl/README.md, line 16:

<comment>This Gradle command cannot start the sample: the project has no application entry point and disables `bootJar`, so the generated JAR is not executable. Add/configure a Spring Boot main class and enable `bootJar`, or remove the `java -jar` launch step and update the surrounding startup guidance.</comment>

<file context>
@@ -4,18 +4,21 @@ This Kotlin based [Spring Boot](https://spring.io/projects/spring-boot) applicat
+To build the project using gradle on Linux or macOS, run:
 ```bash
-gradle build && java -jar build/libs/kotlin-spring-oneof-jackson-default-impl-1.0.0.jar
+sh ./gradlew build && java -jar build/libs/kotlin-spring-oneof-jackson-default-impl-1.0.0.jar
+```
+
</file context>

[Picazsoo]

Valid, but pre-existing and out of scope: for interfaceOnly=true projects there is no Application.kt, bootJar is disabled and the Maven boot plugin is omitted, so the upstream java -jar instructions (Maven and Gradle) never worked. This PR no longer touches the README: I reverted all README template changes to keep it focused on collection element annotations. The interfaceOnly-aware wording will go into a separate docs PR.

[cubic-dev-ai]

P2: This new Gradle command cannot start the advertised server: the build disables bootJar, and this sample has no application entry point or executable JAR manifest. Either add/configure a Spring Boot main application and enable bootJar, or remove the java -jar launch instruction.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At samples/server/others/kotlin-springboot/oneOf-discriminator/README.md, line 16:

<comment>This new Gradle command cannot start the advertised server: the build disables `bootJar`, and this sample has no application entry point or executable JAR manifest. Either add/configure a Spring Boot main application and enable `bootJar`, or remove the `java -jar` launch instruction.</comment>

<file context>
@@ -4,18 +4,21 @@ This Kotlin based [Spring Boot](https://spring.io/projects/spring-boot) applicat
+To build the project using gradle on Linux or macOS, run:
 ```bash
-gradle build && java -jar build/libs/openapi-spring-1.0.0.jar
+sh ./gradlew build && java -jar build/libs/openapi-spring-1.0.0.jar
+```
+
</file context>

[Picazsoo]

Valid, but pre-existing and out of scope: for interfaceOnly=true projects there is no Application.kt, bootJar is disabled and the Maven boot plugin is omitted, so the upstream java -jar instructions (Maven and Gradle) never worked. This PR no longer touches the README: I reverted all README template changes to keep it focused on collection element annotations. The interfaceOnly-aware wording will go into a separate docs PR.

[cubic-dev-ai]

No issues found across 249 files

<sub>Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

View guided diff | Re-trigger cubic</sub>