microprofile-open-api: It is not possible to create Schema with array of referenced items

The things that need to be done to get this in the next release are:

• come up with a good design (I think we have this now 😄)
• create a PR with changes to the API or spec text as needed
• create a PR to add TCK tests

The next release is likely to be some time next year, around the next major MicroProfile release. Additionally, before we can do a release, we also need someone to have implemented it and passed the TCK (both so that people can actually use it, and to ensure we haven’t put anything in the spec that’s actually impossible to implement).

The main hurdle is that most of us are tied up working on other projects so there hasn’t been a lot of work on MP OpenAPI recently. If you’d like to propose a PR to make the API changes and add TCKs for this feature that would be very welcome, otherwise one of us will get to it eventually.

On the call we broadly agreed that reusing @PropertySchema is preferable to adding another nearly identical annotation, even if the naming is not ideal.

I also note that this would provide another way to do #445 if you can’t annotate the item class.

@mklueh Thank you for your detailed breakdown of the problems you’ve had trying to the types right for an array. I’m sorry I’ve been really busy and still haven’t had time to sit down and go through what you’ve written but I hope to get to it later this week.

It appears that when annotating with TYPE_USE, the annotation directly on the array element type is the one that would be considered the items schema. The same annotation also appears on the field in the Java class, so in cases like this the field annotation would need to be discarded by a scanner implementation. The annotation on the array type [] would then be the outer schema and should support arbitrary levels of nesting.

It’s probably not what people are used to seeing since it would be reversed from the typical way of annotating fields, parameters, etc. However, it technically would allow for the schema to be expressed as needed when using arrays.

@Schema(description = "Item description") String 
  @Schema(description = "Array description")[] variableName;

Resulting schema:

"variableName": {
  "type": "array",
  "description": "Array description",
  "items": {
    "type": "string",
    "description": "Item description"
  }
}

Annotating the array type as suggested above may not actually be what is wanted. I need to look further into how the annotated is represented.

@MikeEdgar @arthurdm any thoughts on other workarounds? I feel like I’m missing an obvious approach, but I can’t think of anything.

Yes that is the contract for the ref property. That property is mutually exclusive with all other properties on @Schema.