fix(java): place bean-validation @Valid on the type argument instead of the container (HV000271)

[twonky4]

Fixes Hibernate Validator HV000271 ("Using @Valid on a container is deprecated. You should apply the annotation on the type argument(s)") across the Java generator family. HV 9.1+ (bundled with Spring Boot 4) logs this at WARN for every @Valid-annotated List/Set/Map — on both model properties and API parameters.

The fix relocates @Valid from the container to its type argument — the Bean-Validation-2.0 form (List<@Valid T>, Map<String, @Valid V>) — which cascades identically but is not deprecated. Backward-compatible: element validation is preserved, never dropped.

Scope (Java family): spring, java client, JAX-RS (jersey, resteasy(+eap), cxf(+extended/cdi), spec), java-camel.

• Models (property/getter): the container @Valid is moved to the type argument. Map values are gated behind a new AbstractJavaCodegen#useBeanValidationOnMapValueType() (default false; overridden true in Spring/JavaClient/JAX-RS) so untouched generators don't silently gain map-value validation. Arrays/sets already injected the type-argument form.
• Parameters (@RequestBody/@RequestParam/@RequestPart): the redundant container-level @Valid is dropped for container parameters; element validation is driven by the type-argument @Valid. Single-object parameters keep their @Valid. Reactive Mono/Flux bodies are intentionally untouched — they are not Jakarta containers and do not trigger HV000271.

The microprofile client bodyParams change is a consistency change with no sample impact (those samples don't enable bean validation).

Tests: added SpringCodegenTest#beanValidationOnContainerTypeArgument_issue23614 and #beanValidationOnContainerParameter_issue23614, JavaClientCodegenTest#testBeanValidationOnContainerTypeArgument_issue23614, updated JavaJAXRSSpecServerCodegenTest; the reactive test now also asserts the parameter-level @Valid is retained.

Fixes #23614

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.
  • Java: @bbdouglas @sreeshas @jfiala @lukoyanov @cbornet @jeff9finger @karismann @Zomzog @lwlee2608 @martin-mfg
  • Java Spring: @cachescrubber @welshm @MelleD @atextor @manedev79 @javisst @borsch @banlevente

---

Summary by cubic

Moves bean-validation @Valid from container types to their type arguments to eliminate Hibernate Validator HV000271 while keeping cascade validation. Applies to models and API parameters across Spring, Java client, JAX-RS, and Java Camel; reactive bodies are unchanged, fixing #23614.

• Bug Fixes
  • Models: move @Valid to List/Set items and map value types; gated via AbstractJavaCodegen#useBeanValidationOnMapValueType() (overridden to true in SpringCodegen, JavaClientCodegen, AbstractJavaJAXRSServerCodegen). Removed container-level @Valid in Java/JAX-RS/Spring/Java Camel templates.
  • Parameters: drop container-level @Valid on @RequestBody, @RequestParam, @RequestPart for containers (incl. MicroProfile/JAX-RS); keep for single objects; reactive Mono/Flux retain parameter-level @Valid.
  • Updated templates, added tests, and regenerated samples.

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

[cubic-dev-ai]

6 issues found across 579 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/openapi3/server/petstore/springboot-implicitHeaders/src/main/java/org/openapitools/model/ArrayOfArrayOfNumberOnly.java">

<violation number="1" location="samples/openapi3/server/petstore/springboot-implicitHeaders/src/main/java/org/openapitools/model/ArrayOfArrayOfNumberOnly.java:50">
P3: Unused `jakarta.validation.Valid` import remains after the only `@Valid` annotation in the class was removed.</violation>
</file>

<file name="samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/model/ArrayOfNumberOnly.java">

<violation number="1" location="samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/model/ArrayOfNumberOnly.java:64">
P3: `javax.validation.Valid` import is unused after the only @Valid annotation was removed from the getter. This leaves stale generated code that can trigger lint/checkstyle failures.</violation>
</file>

<file name="samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/model/MixedPropertiesAndAdditionalPropertiesClass.java">

<violation number="1" location="samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/model/MixedPropertiesAndAdditionalPropertiesClass.java:51">
P2: `@Valid` on the map value type argument is declared in both the field and the getter return type, which may cause duplicate cascaded validation for the same property per Hibernate Validator documentation.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 200 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: @Valid on the map value type argument is declared in both the field and the getter return type, which may cause duplicate cascaded validation for the same property per Hibernate Validator documentation.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/model/MixedPropertiesAndAdditionalPropertiesClass.java, line 51:

<comment>`@Valid` on the map value type argument is declared in both the field and the getter return type, which may cause duplicate cascaded validation for the same property per Hibernate Validator documentation.</comment>

<file context>
@@ -48,7 +48,7 @@ public class MixedPropertiesAndAdditionalPropertiesClass {
   @SerializedName(SERIALIZED_NAME_MAP)
   @javax.annotation.Nullable
-  private Map<String, Animal> map = new HashMap<>();
+  private Map<String, @Valid Animal> map = new HashMap<>();
 
   public MixedPropertiesAndAdditionalPropertiesClass() {
</file context>

[cubic-dev-ai]

P3: Unused jakarta.validation.Valid import remains after the only @Valid annotation in the class was removed.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/openapi3/server/petstore/springboot-implicitHeaders/src/main/java/org/openapitools/model/ArrayOfArrayOfNumberOnly.java, line 50:

<comment>Unused `jakarta.validation.Valid` import remains after the only `@Valid` annotation in the class was removed.</comment>

<file context>
@@ -47,7 +47,7 @@ public ArrayOfArrayOfNumberOnly addArrayArrayNumberItem(List<BigDecimal> arrayAr
    * @return arrayArrayNumber
    */
-  @Valid 
+  
   @Schema(name = "ArrayArrayNumber", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
   @JsonProperty("ArrayArrayNumber")
</file context>

[cubic-dev-ai]

P3: javax.validation.Valid import is unused after the only @Valid annotation was removed from the getter. This leaves stale generated code that can trigger lint/checkstyle failures.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/model/ArrayOfNumberOnly.java, line 64:

<comment>`javax.validation.Valid` import is unused after the only @Valid annotation was removed from the getter. This leaves stale generated code that can trigger lint/checkstyle failures.</comment>

<file context>
@@ -61,7 +61,6 @@ public ArrayOfNumberOnly addArrayNumberItem(BigDecimal arrayNumberItem) {
    */
   @javax.annotation.Nullable
-  @Valid
 
 
   public List<BigDecimal> getArrayNumber() {
</file context>

[twonky4]

A couple of notes to save reviewers some time.

On the automated review flagging that dropping the parameter-level @Valid disables element validation

It doesn't. The generated API interface is annotated @Validated, so Spring method validation cascades into a container parameter via the type-argument @Valid (List<@Valid T> / Map<String, @Valid V>) — the parameter-level container @Valid is redundant for that and only exists to trigger the HV000271 deprecation warning.

Verified empirically on Spring Boot 3.3 (Spring 6.1 / Hibernate Validator 8) and Spring Boot 4.1 (Spring 7 / Hibernate Validator 9.1), using an isolated single-method @Validated controller (no sibling @Valid, to rule out any bean-level effect):

@RestController
@Validated
class C {
    @PostMapping("/x")
    String x(@RequestBody List<@Valid Pet> body) { return "ok"; }   // Pet.name is @NotNull
}

Posting [{}] to /x:

• new form @RequestBody List<@Valid Pet> → ConstraintViolationException: x.body[0].name: must not be null (element validation runs), no HV000271
• old form @Valid @RequestBody List<@Valid Pet> → same ConstraintViolationException, plus HV000271 on HV 9.1+

So element validation is preserved on both Spring versions; the change only removes the deprecation warning. Single-object body parameters keep their @Valid, and reactive Mono/Flux bodies are deliberately left untouched (they are not Jakarta containers and don't trigger HV000271).

On the remaining red check

Build Java Client JDK11 (samples/client/petstore/java/jersey3) fails with invalid target release: 17 — a JDK-matrix issue (a JDK 11 job compiling a sample whose POM targets Java 17). It is unrelated to this change: the jersey3 sample is not modified by this PR and the error is a compiler-target mismatch, not a validation/codegen problem.