Openapi-specification: State whether Open API schema object definitions are open or closed for extension

[dehora]

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.

[webron]

Tackling PR: #741

[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.

[webron]

additionalProperties can now take a boolean value, and follows the rest of the JSON Schema standard, making it true by default - #894.

[tedepstein]

This came up on a spec discussion today, and some discussion with @handrews followed in the #spec channel on open-api Slack.

The story is much better now with OpenAPI 3.0, because additionalProperties allows a boolean value or a subschema, and the OpenAPI spec _seems_ to defer to JSON Schema with regard to the default value. The Schema Object definition says:

The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.
...

• additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.

Since this definition doesn't adjust anything except the subschema (constraining it to a Schema Object), I take that to mean that it follows JSON Schema's default of additionalProperties: true.

Still, it would be better to make this explicit, especially because there has been so much confusion, and several attempts to clarify or amend the spec, out-of-band, in previous versions. If we can please reopen this issue, I could propose a small clarification to the spec.

[darrelmiller]

Thanks for following up on this @tedepstein Feel free to create a PR with proposed wording changes.

[tedepstein]

Thanks @darrelmiller. Should I branch off master, v3.0.2-dev, or something else? I see open PRs targeting both of those branches. Not sure what the current protocol is.

[darrelmiller]

@tedepstein Branch off v3.0.2-dev. Anything that goes in the spec is off that branch. Guidelines, implementations, etc go off master.

[tedepstein]

@darrelmiller , I think we can close this one now. Thanks.