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

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

This 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; single-object @Valid is untouched.
Verified on Spring Boot 3.3 (Spring 6.1) and 4.1 (Spring 7): a container
parameter carrying only the type-argument @Valid still triggers element
validation via method validation, with no HV000271.

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

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 @Valid.
Reactive Mono/Flux bodies are intentionally untouched (not Jakarta containers,
so no HV000271).

Regenerated all affected samples and added/updated codegen tests in
SpringCodegenTest, JavaClientCodegenTest, JavaJAXRSSpecServerCodegenTest and
JavaValidationArrayPrimitivesTest.

Author: twonky4

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java

@@ -1097,7 +1097,7 @@ public String getTypeDeclaration(Schema p) {
         Schema<?> target = ModelUtils.isGenerateAliasAsModel() ? p : schema;
         if (ModelUtils.isArraySchema(target)) {
             Schema<?> items = getSchemaItems(schema);
-            String typeDeclaration = getTypeDeclarationForArray(items);
+            String typeDeclaration = getTypeDeclarationWithBeanValidation(items);
             return getSchemaType(target) + "<" + typeDeclaration + ">";
         } else if (ModelUtils.isMapSchema(target)) {
             // Note: ModelUtils.isMapSchema(p) returns true when p is a composed schema that also defines
@@ -1108,12 +1108,43 @@ public String getTypeDeclaration(Schema p) {
                 inner = new StringSchema().description("TODO default missing map inner type to string");
                 p.setAdditionalProperties(inner);
             }
-            return getSchemaType(target) + "<String, " + getTypeDeclaration(inner) + ">";
+            // Unlike arrays/sets, map values never received a type-argument bean
+            // validation before, so this is gated: only generators that have dropped the
+            // deprecated container-level @Valid (HV000271) opt in, to avoid silently adding
+            // new validation to generators that still cascade via the container.
+            String valueDeclaration = useBeanValidationOnMapValueType()
+                    ? getTypeDeclarationWithBeanValidation(inner)
+                    : getTypeDeclaration(inner);
+            return getSchemaType(target) + "<String, " + valueDeclaration + ">";
         }
         return super.getTypeDeclaration(target);
     }
 
-    private String getTypeDeclarationForArray(Schema<?> items) {
+    /**
+     * Whether bean validation of map values is expressed on the value type argument
+     * ({@code Map<String, @Valid V>}) instead of on the map itself. Generators that have migrated
+     * off the deprecated container-level {@code @Valid} (Hibernate Validator HV000271)
+     * override this to return {@code true}. Arrays/sets always place bean validation on the
+     * type argument, so they are not gated by this method.
+     *
+     * @return {@code true} to emit map-value bean validation on the type argument;
+     *         {@code false} by default
+     */
+    protected boolean useBeanValidationOnMapValueType() {
+        return false;
+    }
+
+    /**
+     * Renders the type declaration of a container element (array/set item or map value) with its
+     * bean validation applied to the type argument, e.g. {@code @Valid Pet} or
+     * {@code @Size(max = 3) String}. Hibernate Validator 9.1+ expects cascade/constraints on the
+     * type argument; a container-level {@code @Valid} is deprecated and logs HV000271, so the
+     * annotation is placed here instead of on the container.
+     *
+     * @param items the array/set item or map value schema
+     * @return the element type declaration prefixed with its bean validation (no prefix if none)
+     */
+    private String getTypeDeclarationWithBeanValidation(Schema<?> items) {
         String typeDeclaration = getTypeDeclaration(items);
 
         String beanValidation = getBeanValidation(items);
@@ -1137,11 +1168,12 @@ private String getTypeDeclarationForArray(Schema<?> items) {
     }
 
     /**
-     * This method stand for resolve bean validation for container(array, set).
+     * This method stand for resolve bean validation for a container element
+     * (array/set item or map value).
      * Return empty if there's no bean validation for requested type or prop useBeanValidation false or missed.
      *
      * @param items type
-     * @return BeanValidation for declared type in container(array, set)
+     * @return BeanValidation for declared element type of a container (array, set, map value)
      */
     private String getBeanValidation(Schema<?> items) {
         if (!isUseBeanValidation()) {

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaJAXRSServerCodegen.java

@@ -132,6 +132,14 @@ public CodegenType getTag() {
         return CodegenType.SERVER;
     }
 
+    @Override
+    protected boolean useBeanValidationOnMapValueType() {
+        // The JAX-RS templates place container element validation on the type argument
+        // (List<@Valid T>, Map<String, @Valid V>) rather than the deprecated
+        // container-level @Valid (HV000271).
+        return true;
+    }
+
     @Override
     public void processOpts() {
         super.processOpts();

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java

@@ -201,6 +201,14 @@ public DocumentationProvider defaultDocumentationProvider() {
         return DocumentationProvider.SOURCE;
     }
 
+    @Override
+    protected boolean useBeanValidationOnMapValueType() {
+        // The Java templates place container element validation on the type argument
+        // (List<@Valid T>, Map<String, @Valid V>) rather than the deprecated
+        // container-level @Valid (HV000271).
+        return true;
+    }
+
     @Override
     public List<DocumentationProvider> supportedDocumentationProvider() {
         List<DocumentationProvider> documentationProviders = new ArrayList<>();

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java

@@ -1555,6 +1555,14 @@ public List<VendorExtension> getSupportedVendorExtensions() {
         return extensions;
     }
 
+    @Override
+    protected boolean useBeanValidationOnMapValueType() {
+        // The Spring templates place container element validation on the type argument
+        // (List<@Valid T>, Map<String, @Valid V>) rather than the deprecated
+        // container-level @Valid (HV000271).
+        return true;
+    }
+
     protected boolean isSpringCodegen() {
         return getName().contains("spring");
     }

modules/openapi-generator/src/main/resources/Java/beanValidation.mustache

@@ -3,13 +3,6 @@
   @NotNull
 {{/isReadOnly}}
 {{/required}}
-{{#isContainer}}
-{{^isPrimitiveType}}
-{{^isEnum}}
-  @Valid
-{{/isEnum}}
-{{/isPrimitiveType}}
-{{/isContainer}}
 {{^isContainer}}
 {{^isPrimitiveType}}
   @Valid

modules/openapi-generator/src/main/resources/Java/libraries/microprofile/bodyParams.mustache

@@ -1 +1 @@
-{{#isBodyParam}}{{#useBeanValidation}}@Valid {{/useBeanValidation}}{{{dataType}}} {{paramName}}{{/isBodyParam}}
+{{#isBodyParam}}{{#useBeanValidation}}{{^isContainer}}@Valid {{/isContainer}}{{/useBeanValidation}}{{{dataType}}} {{paramName}}{{/isBodyParam}}

modules/openapi-generator/src/main/resources/JavaJaxRS/beanValidation.mustache

@@ -1 +1 @@
-{{#required}}{{^isReadOnly}}@NotNull {{/isReadOnly}}{{/required}}{{#isContainer}}{{^items.isPrimitiveType}}{{^items.isDate}}{{^items.isDateTime}}{{^items.isString}}{{^items.isFile}}{{^items.isEnumOrRef}}@Valid {{/items.isEnumOrRef}}{{/items.isFile}}{{/items.isString}}{{/items.isDateTime}}{{/items.isDate}}{{/items.isPrimitiveType}}{{/isContainer}}{{^isContainer}}{{^isPrimitiveType}}{{^isDate}}{{^isDateTime}}{{^isString}}{{^isFile}}{{^isEnumOrRef}}@Valid {{/isEnumOrRef}}{{/isFile}}{{/isString}}{{/isDateTime}}{{/isDate}}{{/isPrimitiveType}}{{/isContainer}}{{>beanValidationCore}}
+{{#required}}{{^isReadOnly}}@NotNull {{/isReadOnly}}{{/required}}{{^isContainer}}{{^isPrimitiveType}}{{^isDate}}{{^isDateTime}}{{^isString}}{{^isFile}}{{^isEnumOrRef}}@Valid {{/isEnumOrRef}}{{/isFile}}{{/isString}}{{/isDateTime}}{{/isDate}}{{/isPrimitiveType}}{{/isContainer}}{{>beanValidationCore}}

modules/openapi-generator/src/main/resources/JavaJaxRS/cxf-ext/bodyParams.mustache

@@ -1 +1 @@
-{{#isBodyParam}}{{#useBeanValidation}}@Valid {{/useBeanValidation}}{{{dataType}}} {{paramName}}{{/isBodyParam}}
+{{#isBodyParam}}{{#useBeanValidation}}{{^isContainer}}@Valid {{/isContainer}}{{/useBeanValidation}}{{{dataType}}} {{paramName}}{{/isBodyParam}}

modules/openapi-generator/src/main/resources/JavaJaxRS/cxf-ext/pojo.mustache

@@ -40,8 +40,8 @@ public class {{classname}} {{#parent}}extends {{{.}}}{{/parent}}{{#vendorExtensi
 {{#withXml}}
   @XmlElement(name="{{baseName}}"{{#required}}, required = {{required}}{{/required}})
 {{/withXml}}
-  @ApiModelProperty({{#example}}example = "{{{.}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}value = "{{{description}}}"){{^isPrimitiveType}}{{^isDate}}{{^isDateTime}}{{^isString}}{{^isFile}}{{#useBeanValidation}}
-  @Valid{{/useBeanValidation}}{{/isFile}}{{/isString}}{{/isDateTime}}{{/isDate}}{{/isPrimitiveType}}
+  @ApiModelProperty({{#example}}example = "{{{.}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}value = "{{{description}}}"){{^isContainer}}{{^isPrimitiveType}}{{^isDate}}{{^isDateTime}}{{^isString}}{{^isFile}}{{#useBeanValidation}}
+  @Valid{{/useBeanValidation}}{{/isFile}}{{/isString}}{{/isDateTime}}{{/isDate}}{{/isPrimitiveType}}{{/isContainer}}
 {{#isDate}}
   @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
 {{/isDate}}

modules/openapi-generator/src/main/resources/JavaJaxRS/cxf/bodyParams.mustache

@@ -1 +1 @@
-{{#isBodyParam}}{{#useBeanValidation}}@Valid {{#required}}{{^isNullable}}@NotNull {{/isNullable}}{{/required}}{{/useBeanValidation}}{{#isFile}}{{#useAbstractionForFiles}}{{#collectionFormat}}java.util.Collection<InputStream>{{/collectionFormat}}{{^collectionFormat}}InputStream{{/collectionFormat}}{{/useAbstractionForFiles}}{{^useAbstractionForFiles}}{{{dataType}}}{{/useAbstractionForFiles}}{{/isFile}}{{^isFile}}{{{dataType}}}{{/isFile}} {{paramName}}{{/isBodyParam}}
+{{#isBodyParam}}{{#useBeanValidation}}{{^isContainer}}@Valid {{/isContainer}}{{#required}}{{^isNullable}}@NotNull {{/isNullable}}{{/required}}{{/useBeanValidation}}{{#isFile}}{{#useAbstractionForFiles}}{{#collectionFormat}}java.util.Collection<InputStream>{{/collectionFormat}}{{^collectionFormat}}InputStream{{/collectionFormat}}{{/useAbstractionForFiles}}{{^useAbstractionForFiles}}{{{dataType}}}{{/useAbstractionForFiles}}{{/isFile}}{{^isFile}}{{{dataType}}}{{/isFile}} {{paramName}}{{/isBodyParam}}