OpenAPI extension generates schema with duplicated array type if @Schema specified both on a type and field

[rsynek]

Describe the bug

The following class representing a location is serialized into an array of two numbers (latitude, longitude):

@Schema(implementation = Double.class, minItems = 2, maxItems = 2, example = "[40.5044403760272, -76.37894009358867]",
        description = "Array of two elements: latitude and longitude, in that order.", type = SchemaType.ARRAY)
@JsonFormat(shape = JsonFormat.Shape.ARRAY)
public class Location {
    private double latitude;

    private double longitude;

}

The schema type generated from this class is correct:

"Location" : {
   "description" : "Array of two elements: latitude and longitude, in that order.",
    "type" : "array",
    "examples" : [ [ 40.5044403760272, -76.37894009358867 ] ],
    "maxItems" : 2,
    "minItems" : 2,
    "items" : {
      "type" : "number",
      "format" : "double"
    }
}

So is the schema representing a field that uses the type:

"location" : {
  "$ref" : "#/components/schemas/Location"
}

However, once we add a Schema annotation on the field as well, even only to add a description:

@Schema(description = "something")
private Location location;

the generated schema looks as follows:

"location" : {
 "description" : "something",
 "type" : "array",
 "$ref" : "#/components/schemas/Location"
}

This schema is incorrect, as it suggests the location field is an array of Location, which itself is an array of two numbers, so effectively a two-dimensional array.

Expected behavior

No response

Actual behavior

openapi.json

How to Reproduce?

1. git clone https://github.com/rsynek/openapi-location-reproducer
2. cd openapi-location-reproducer
3. mvn package
4. check the target/openapi-schema/openapi.json

Output of uname -a or ver

Linux fedora 6.12.9-200.fc41.x86_64 #1 SMP PREEMPT_DYNAMIC Thu Jan 9 16:05:40 UTC 2025 x86_64 GNU/Linux

Output of java -version

Java version: 21, vendor: Eclipse Adoptium, runtime: /home/rsynek/.sdkman/candidates/java/21-tem

Quarkus version or git rev

3.17.6

Build tool (ie. output of mvnw --version or gradlew --version)

Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)

Additional information

No response

[quarkus-bot]

/cc @EricWittmann (openapi), @MikeEdgar (openapi), @phillip-kruger (openapi)

[MikeEdgar]

Is this misbehaving in Swagger UI or some other consumer of the OpenAPI? What you show actually seems correct. That is, it represents a one-dimension array. For it to be two-dimensions there would need to be an additional items.

For example, this would be the 2D array:

"location" : {
 "description" : "something",
 "type" : "array",
 "items": {
   "$ref" : "#/components/schemas/Location"
 }
}

[rsynek]

Is this misbehaving in Swagger UI or some other consumer of the OpenAPI? What you show actually seems correct. That is, it represents a one-dimension array. For it to be two-dimensions there would need to be an additional items.

For example, this would be the 2D array:

"location" : {
"description" : "something",
"type" : "array",
"items": {
"$ref" : "#/components/schemas/Location"
}
}

Thanks for looking into this @MikeEdgar .

True, on the other hand, why there is the type : array repeated, if it's inside the Location type itself already? Having the type : array and "$ref" : "#/components/schemas/Location" instead of "items": { "$ref" : "#/components/schemas/Location" } seems to be inconsistent.

[cristianonicolai]

@MikeEdgar thanks for taking a look on it. To give a bit more context, the issue seems to be related to when adding @Schema to the attribute location.
Without annotating the attribute, it generates:

"properties" : {
          "location" : {
            "$ref" : "#/components/schemas/Location"
          }
        }

That seems correct, but as soon as you add something like:

@Schema(description = "Test desc")
    private Location location;

Then it generates:

"properties" : {
          "location" : {
            "description" : "Test desc",
            "type" : "array",
            "allOf" : [ {
              "$ref" : "#/components/schemas/Location"
            } ]
          }
        }

We're using Quarkus 3.16.4