Allow custom schema to be specified directly in annotation

[Azquelt]

What are your thoughts on having a String value() default "" property that could be used to set an arbitrary schema (that must be valid JSON/YAML)? That would give support for alternate dialects with the annotation.

I'm not sure myself, but I wanted to mention it as a possibility.

_Originally posted by @MikeEdgar in https://github.com/eclipse/microprofile-open-api/pull/601#discussion_r1593060737_

[Azquelt]

Initial thoughts

• pros:
  • this would sidestep the problem that JSON schemas are more expressive than Java annotations
  • gives users full access to JSON schema features directly from annotations
  • allows use of custom schema dialects directly from annotations
• cons:
  • not typesafe (unlike annotations)
  • requires familiarity with JSON schema
  • likely no IDE assistance (in contrast with writing OpenAPI or JSON schema in a standalone file)
  • need to define how this would interact with other annotation parameters or schema generated from the type
  • need to define what happens if the schema is not valid JSON/YAML

[Azquelt]

I've provisionally added this to the 4.0 milestone, but we can decide not to do it and close it, or push it out of 4.0 if we're unsure or don't have time.

[Azquelt]

Discussed on the call today, on balance we think it's probably a good idea, it provides access to all of the possible schema options and sidesteps the lack of recursion in Java annotations.

We thought that an exception should probably be thrown at startup if the value is not well-formed JSON.

However, we don't think we have enough time to add it in this release, though as it's just adding a new annotation parameter it would be a good candidate for a future minor release.