[BUG][Java][Spring][SpringBoot] optional array with 'minItems' set, fails validation

[kingofdisasterr]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

given an optioal array with 'minItems: 1', fails validation if this array isn't provided by the client.

All arrays defined in OpenAPI are, by default, initialized as empty lists in Java. If an array is required to have at least one entry when it is provided, validation will fail if the client omits the array.

openapi-generator version

v7.18.0, v7.19.0, master

OpenAPI declaration file content or url

OpenApi declaration:

openapi: 3.1.1
info:
    title: Optional Array OpenAPI Example
    version: 1.0.0
paths:
  /v1/new-customer:
    put:
      operationId: setNewCustomer
      requestBody:
        description: the new customer to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCustomerRequest'
      responses:
        204:
          description: The new customer was set successfully.

components:
  schemas:
    NewCustomerRequest:
      type: object
      properties:
        newCustomer:
          properties:
            name:
              type: string
          required:
            - name
        documents:
          description: |
            the documents to be attached to identify the new customer.
            This array is optional. If provided, it must contain between 1 and 3 items
          type: array
          items:
            $ref: '#/components/schemas/Document'
          minItems: 1
          maxItems: 3
      required:
        - newCustomer
    Document:
      type: object
      properties:
        documentId:
          description: |
            The document id (uuid)
          type: string
          format: uuid
        documentType:
          $ref: '#/components/schemas/DocumentType'
        documentNo:
          type: string
      required:
        - documentId
        - documentType
        - documentNo
    DocumentType:
      type: string
      enum:
        - ID_CARD
        - PASSPORT

Generation Details

java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate
-i optional_array-openapi.yaml
-g spring
-o tmp/spring-api

generates this model:

package org.openapitools.model;

import java.net.URI;
import java.util.Objects;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonCreator;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import org.openapitools.model.Document;
import org.openapitools.model.NewCustomerRequestNewCustomer;
import org.springframework.lang.Nullable;
import org.openapitools.jackson.nullable.JsonNullable;
import java.time.OffsetDateTime;
import javax.validation.Valid;
import javax.validation.constraints.*;
import io.swagger.v3.oas.annotations.media.Schema;


import java.util.*;
import javax.annotation.Generated;

/**
 * NewCustomerRequest
 */

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2026-01-23T09:37:18.269659+01:00[Europe/Zurich]", comments = "Generator version: 7.20.0-SNAPSHOT")
public class NewCustomerRequest {

  private NewCustomerRequestNewCustomer newCustomer;

  @Valid
  private List<@Valid Document> documents = new ArrayList<>();

  public NewCustomerRequest() {
    super();
  }

  /**
   * Constructor with only required parameters
   */
  public NewCustomerRequest(NewCustomerRequestNewCustomer newCustomer) {
    this.newCustomer = newCustomer;
  }

  public NewCustomerRequest newCustomer(NewCustomerRequestNewCustomer newCustomer) {
    this.newCustomer = newCustomer;
    return this;
  }

  /**
   * Get newCustomer
   * @return newCustomer
   */
  @NotNull @Valid 
  @Schema(name = "newCustomer", requiredMode = Schema.RequiredMode.REQUIRED)
  @JsonProperty("newCustomer")
  public NewCustomerRequestNewCustomer getNewCustomer() {
    return newCustomer;
  }

  public void setNewCustomer(NewCustomerRequestNewCustomer newCustomer) {
    this.newCustomer = newCustomer;
  }

  public NewCustomerRequest documents(List<@Valid Document> documents) {
    this.documents = documents;
    return this;
  }

  public NewCustomerRequest addDocumentsItem(Document documentsItem) {
    if (this.documents == null) {
      this.documents = new ArrayList<>();
    }
    this.documents.add(documentsItem);
    return this;
  }

  /**
   * the documents to be attached to identify the new customer. This array is optional. If provided, it must contain between 1 and 3 items 
   * @return documents
   */
  @Valid @Size(min = 1, max = 3) 
  @Schema(name = "documents", description = "the documents to be attached to identify the new customer. This array is optional. If provided, it must contain between 1 and 3 items ", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
  @JsonProperty("documents")
  public List<@Valid Document> getDocuments() {
    return documents;
  }

  public void setDocuments(List<@Valid Document> documents) {
    this.documents = documents;
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) {
      return true;
    }
    if (o == null || getClass() != o.getClass()) {
      return false;
    }
    NewCustomerRequest newCustomerRequest = (NewCustomerRequest) o;
    return Objects.equals(this.newCustomer, newCustomerRequest.newCustomer) &&
        Objects.equals(this.documents, newCustomerRequest.documents);
  }

  @Override
  public int hashCode() {
    return Objects.hash(newCustomer, documents);
  }

  @Override
  public String toString() {
    StringBuilder sb = new StringBuilder();
    sb.append("class NewCustomerRequest {\n");
    sb.append("    newCustomer: ").append(toIndentedString(newCustomer)).append("\n");
    sb.append("    documents: ").append(toIndentedString(documents)).append("\n");
    sb.append("}");
    return sb.toString();
  }

  /**
   * Convert the given object to string with each line indented by 4 spaces
   * (except the first line).
   */
  private String toIndentedString(@Nullable Object o) {
    if (o == null) {
      return "null";
    }
    return o.toString().replace("\n", "\n    ");
  }
}

Steps to reproduce

given the declaration above, generate the java code and execute this test:

package org.openapitools.model;

import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;

import javax.validation.ConstraintViolation;
import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;

import java.util.Set;

import static org.assertj.core.api.Assertions.assertThat;

public class NewCustomerRequestTest {

	private final Validator validator;

	public NewCustomerRequestTest() {
		try (ValidatorFactory factory = Validation.buildDefaultValidatorFactory()) {
			this.validator = factory.getValidator();
		}
	}

    @Test
    void testNewCustomerReadFromJsonAndValidate()
            throws Exception {
        final String newCustomerJsonString = "{\"newCustomer\":{\"name\":\"test customer name\"}}";
        final NewCustomerRequest newCustomer = new ObjectMapper().readValue(newCustomerJsonString, NewCustomerRequest.class);
        final Set<ConstraintViolation<NewCustomerRequest>> newCustomerValidations = validator.validate(newCustomer);
        assertThat(newCustomerValidations).isEmpty();
    }

}

Related issues/PRs

#18735
#21269

Suggest a fix

The generator must check whether an array has 'minItems' defined and whether it is optional. If so, the array must not be initialized by default in Java.

[jpfinne]

@kingofdisasterr there are options to skip the initialization of arrays.
Look at https://github.com/openapitools/openapi-generator/blob/master/docs/customization.md#default-values.

For example in maven:
<additionalProperties>defaultToEmptyContainer=""</additionalProperties>

Or in the CLI:
--additional-properties defaultToEmptyContainer="?array"
--additional-properties defaultToEmptyContainer=array

I don't think there is a need for

The generator must check whether an array has 'minItems' defined and whether it is optional. If so, the array must not be initialized by default in Java.

[kingofdisasterr]

@jpfinne actually i use the openapi-generator-maven-plugin. since i use this, i tried already with the following possibilities:
<additionalProperties>defaultToEmptyContainer=""</additionalProperties>
<additionalProperties>defaultToEmptyContainer="?array"</additionalProperties>
<additionalProperties>defaultToEmptyContainer="array"</additionalProperties>

given a second, required, array:

openapi: 3.1.1
info:
    title: Optional Array OpenAPI Example
    version: 1.0.0
paths:
  /v1/new-customer:
    put:
      operationId: setNewCustomer
      requestBody:
        description: the new customer to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCustomerRequest'
      responses:
        204:
          description: The new customer was set successfully.

components:
  schemas:
    NewCustomerRequest:
      type: object
      properties:
        newCustomer:
          properties:
            name:
              type: string
          required:
            - name
        documents:
          description: |
            the documents to be attached to identify the new customer.
            This array is optional. If provided, it must contain between 1 and 3 items
          type: array
          items:
            $ref: '#/components/schemas/Document'
          minItems: 1
          maxItems: 3
        documentsRequired:
          description: |
            the documents to be attached to identify the new customer.
            This array is required and must contain max 3 items
          type: array
          items:
            $ref: '#/components/schemas/Document'
          maxItems: 3
      required:
        - newCustomer
        - documentsRequired
    Document:
      type: object
      properties:
        documentId:
          description: |
            The document id (uuid)
          type: string
          format: uuid
        documentType:
          $ref: '#/components/schemas/DocumentType'
        documentNo:
          type: string
      required:
        - documentId
        - documentType
        - documentNo
    DocumentType:
      type: string
      enum:
        - ID_CARD
        - PASSPORT

it leads to the following:
with <additionalProperties>defaultToEmptyContainer=""</additionalProperties>

  @Valid
  private @Nullable List<@Valid Document> documents;
  @Valid
  private List<@Valid Document> documentsRequired;

with <additionalProperties>defaultToEmptyContainer="?array"</additionalProperties>

  @Valid
  private @Nullable List<@Valid Document> documents;
  @Valid
  private List<@Valid Document> documentsRequired;

with <additionalProperties>defaultToEmptyContainer="array"</additionalProperties>

  @Valid
  private @Nullable List<@Valid Document> documents;
  @Valid
  private List<@Valid Document> documentsRequired;

there is no difference in the generated result. somehow the parameter is already being interpreted, since no default values are being assigned anymore.

but i think with the defined arrays in addition with required or not, minItems, maxItems it's correct to check these conditions and generate the resulting models with arrays as desired.

[kingofdisasterr]

@jpfinne
It doesn't even work with the Docker image. (see #22784 (comment))

@wing328
i saw the option defaultToEmptyContainer was introduced here: #21269; but it only works with the CLI, neither with the maven plugin nor with the docker image. personally, i think it shouldn't be necessary to instruct the generator with such an option, because the openapi definition is clear what to expect on spring server side.

[wing328]

but it only works with the CLI, neither with the maven plugin nor with the docker image.

Can you please share the exact docker command?

If I remember correctly, defaultToEmptyContainer is just another additionalProperties so I don't see why it works in CLI but not theDocker CLI image.

[jpfinne]

See #21505 [BUG] defaultToEmptyContainer not working with Maven plugin

[wing328]

@jpfinne thanks for sharing more but does the Docker CLI not working with this option for you either?

[kingofdisasterr]

but it only works with the CLI, neither with the maven plugin nor with the docker image.

Can you please share the exact docker command?

sorry - my bad! i missed the --additional-properties and defaultToEmptyContainer=array in my config to run the docker image. i ran my tests again and found it wrong in my local history.

[Picazsoo]

Hello @kingofdisasterr . I think the issue lies elsewhere. Since the documents array is not marked as required and does not have default fallback value specified, I would expect the variable to be initialized to null in case that it is omitted in the deserialized json regardless of any other minItems, maxItems, etc. properties

[Chrimle]

Isn't the issue that nullable is false by default? Which leads to:

nullable: false
minItems: 1
maxItems: 3

Shouldn't that suggest that the array must be instantiated? 🤔
(Is there any point in differentiating nullable and required in java? I mean, shouldn't everything in java have default: null essentially?)

[MelleD]

If you have minItems you should declare the properties also as required, because if not the array could be empty or you should use nullable: true.

[Chrimle]

Nah, I might have misunderstood it. I interpretation is:

required: whether the KEY in the key-value pair is required. If not required, it can be omitted completely.

nullable: whether the VALUE in the key-value pair is nullable. I suppose nullable is true by default, considering every schema's default is null.

So documents is:

• not required
• nullable: true
• minItems: 1
• minItems: 3

So, these are valid:
{"name":"ignore"} (no documents at all)
{"name":"ignore", "documents": null} (since nullable:true by default)
{"name":"ignore", "documents": [{doc1}]} (since minItems: 1)
{"name":"ignore", "documents": [{doc1}, {doc2}]} (since minItems: 1 & maxItems: 3)

and these are invalid:
{"name":"ignore", "documents": []} (since minItems: 1)
{"name":"ignore", "documents": [{doc1}, {doc2}, {doc3}, {doc4}]} (since maxItems: 3)

[Picazsoo]

@Chrimle
In open api, if you do not explicitly specify nullable: true, the attribute defaults to non-nullable. But you can still omit it entirely in the request if it is not included in the required attributes.

One can use JsonNullable<T> to differentiate cleanly the intent between null and undefined

Regarding your list of valid/invalid requests - it checks out.

You can make it more complicated by also defining a default (-:

In the original spec, the attribute is not required and it is not nullable. Maybe a good candidate for JsonNullable<>? I will admit I did not think it through 100%. Just felt the need to point out that in open api the attribute is always not nullable unless specified otherwise.