State whether Open API schema object definitions are open or closed for extension

I had a look through the open issues and couldn’t find a specific issue for this, apologies if I missed it. It’s alluded to in the following but not directly addressed

• https://github.com/OAI/OpenAPI-Specification/issues/333
• https://github.com/OAI/OpenAPI-Specification/issues/668
• https://github.com/swagger-api/swagger-codegen/issues/1318

The clarification I’m looking for is - are object definitions open or closed for extension, and specifically what is the default for handling unexpected JSON properties in the absence of an additionalProperties declaration?

If Open API was using vanilla JSON Schema, I would assume the absence of additionalProperties means the instances are open for extension, since additionalProperties has not been explicitly set to false to close the schema. But because Open API redefines parts of JSON Schema, and in particular additionalProperties and how it should handle booleans, I’m reluctant to just assume that behaviour is carried forward into Open API.

At the moment I can’t find a definitive statement in existing specifications for this, in particular http://swagger.io/specification/#schemaObject (again apologies if I missed it). I do think it’s something that needs to be explicit as it relates to how clients based on Open API handle unexpected data and how Open API tooling should behave by default, especially given additionalProperties has been redefined.

[darrelmiller]

You might find #568 a relevant discussion. Although there is no definitive answer, I do believe that the general consensus is that OpenAPI is not a closed contract. I think the only concern is regarding how useful is it to have behavior that is unspecified in the contract.

Relating this back to JSON Schema definitions, it is my understanding that the default behavior of being open for extension is the expected behavior with OpenAPI. However, I think the spec needs to be much clearer about how it redefines the JSON Schema properties that it claims it does.

[dehora]

You might find #568 a relevant discussion.

I did find it very useful in general. This ticket is more specific.

Tackling PR: #741

Similar to prior tickets, I see this alluded to but not directly addressed. There’s a holding header ("Clarify additionalProperties default setting") but with no text and a comment from last August re allOf interacting with additionalProperties’ true/false values which misses the key point of what should happen when the additionalProperties field is absent in OAI, and the fact that true/false are not options in OAI.

At my current shop, because we use OAI and because OAI doesn’t adequately support media types, we don’t have good options to avoid object definition. Truth is no-one really wants to, it’s useful to have them inline and easy to read and be available to a broader toolchain. But it’s starting to hurt when looking at long term data evolution - core constructs like additionalProperties and allOf unions from JSON Schema with swagger inherited overloading are semantic quicksand relative to approaches like Protocol Buffers 3 and Avro, where these issues don’t seem to come up nearly as much.

@darrelmiller @webron - what’s the best way to make progress? I’d be happy to close this ticket in favour of a working actionable one and reduce noise, but #741 is so big I’m concerned this will get lost. The extension model and rules for something as fundamental as an object definition seems like something OAI could make clear conformance statements about and be testable in a validator.