Schema.getAdditionalProperties(): return something better as Object?

[jmini]

Per spec: additionalProperties in a Schema object can be an Object or a Boolean.
See OAI/OpenAPI-Specification#668 (comment)

In the code, Object is returned:
https://github.com/eclipse/microprofile-open-api/blob/c2a26360d460bfe07b30c83ba4fe6f9cc73543c6/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java#L641

This is not really user-friendly because the user needs to know that this Object can be a Schema or a Boolean and write code with instanceOf to reflect this.

---

Kaizen Model has 2 getters for this:

• Boolean getAdditionalProperties()
• Schema getAdditionalPropertiesSchema()

I do not like this either, but it is better in a sense that no instanceOf is needed.

kaizen-parser Schema.java

---

What is the typical java way of telling Schama or Boolean (a sort of Union Types)?
A new Interface AdditionalProperties with 2 getters returning an optional:

• Optional<Schema> getAsSchema()
• Optional<Boolean> getAsBoolean()

[arthurdm]

Discussed in Sept 10 hangout. +1 to the way Kaizen's has done it.

Boolean getAdditionalProperties()
Schema getAdditionalPropertiesSchema()

[arthurdm]

1.1 will deprecate getAdditionalProperties and introduce the 2 new methods, while 2.0 will remove getAdditionalProperties

[jmini]

Thank you for discussing this in the Hangout, and thank you for reporting here the decision.

Current (1.0):

Object getAdditionalProperties()

---

Is the idea to have:

Boolean getAdditionalPropertiesBoolean()
Schema getAdditionalPropertiesSchema()

Then I understand that getAdditionalProperties() needs to be removed with 2.0 (and can be deprecated with 1.1).

I prefer this solution, because if users are using Object o = s.getAdditionalProperties() it is not clear that the method now only returns Boolean.

---

But you have mentioned:

Boolean getAdditionalProperties()
Schema getAdditionalPropertiesSchema()

Then the only modification is that getAdditionalProperties() was returning an Object with 1.0 and will return a Boolean with 2.0.

[jmini]

Additional proposition:

We have also already 2 setters:
https://github.com/eclipse/microprofile-open-api/blob/8e0f2479a00470911d64ae13a59c5cd78f4240c9/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java#L643-L659

I think they should be renamed to:

Boolean setAdditionalPropertiesBoolean(Boolean)
Schema setAdditionalPropertiesSchema(Schema)

In order to be consistent with the getters.

[arthurdm]

Good catch @jmini

We discussed in today's hangout and agreed with the additions of:

Boolean getAdditionalPropertiesBoolean()
Schema getAdditionalPropertiesSchema()
Boolean setAdditionalPropertiesBoolean(Boolean)
Schema setAdditionalPropertiesSchema(Schema)

And deprecate the existing ones in 1.1, removing then in 2.0

[jmini]

PR for this: #277. Feedback welcomed.