Distinguish Schema and Boolean case for AdditionalProperties in Schema

[jmini]

See Issue #257.

I think the TCK should test getter/setter/builder for additionalProperties in ModelConstructionTest.schemaTest(). I was surprised to see nothing there for the moment.
=> I will add a commit to this PR.

[jmini]

TCK test added with 0bf0c2d

[arthurdm]

I am trying to understand why the schema property would be null here, and not ap. Is it because we set the boolean property, and therefore would have automatically set the schema property to null? If so we should change the javadoc of the methods to specify this behaviour, and also change the default interface impl to set the other variant to null.

[jmini]

This OpenAPI spec snippet shows the possible values for additionalProperties:

  schemas:
    Test1:
      additionalProperties: false
    Test2:
      additionalProperties: true
    Test3:
      additionalProperties:
        type: object
        description: a person object
        properties:
          firstName:
            type: string
          lastName:
            type: string

(+ the null case, of course)

The additionalProperties is either a Boolean or a Schema but can not be both on the same time.

Because in Java we do not have union type, we decided to follow KaiZen approach: having getter, setters and builder as if there was 2 members additionalPropertiesBoolean and additionalPropertiesSchema.

In comparison swagger model just use Object and the consumer needs to know that can be made with the value (call instanceof Schema or instanceof Boolean to see what the additionalProperties member really is).

In my opinion the implementation needs to decide how it wants to handle this case in the setter and getter for additionalPropertiesBoolean, additionalPropertiesSchema.

1/ They can decide to store it in an Object member, and then do an instanceof + cast in the getter.

2/ They can decide to have 2 members, but then they need to null the value in the setter when the other value is set.

3/ Or they use their own storage layer (I did not verify it, but my understanding is that Kaizen does store everything in the JSON data structure).

The default implementation method only does a “delegation to the setter”. Doing anything else in those case might break this rule. The implementation needs to do it right anyway, it is not the responsibility of the builder.

Does this make sense?

---

Maybe I need to write the TCK test in an other way.

---

I have tried to update Javadoc:

• I have added a precision in the getter.
• In the setter and builder there is already a note about the method being “mutually exclusive” with the other variant. I have added a reference to the other method.

[arthurdm]

thanks @jmini - with your latest additions to the javadoc I think it's clearer now for users.