How our "compatible extensibility" and "robustness principle" apply to OpenAPI / JSON Schema additionalProperties usage?

[tfrauenstein]

Open API is not clear about usage / pragmatics of JSON scheme additionalProperties feature. We should make some clarifying statements on how our compatible extensibility and robustness principle (for clients and servers) maps to this keywords.

For instance, If additionalProperties is false for return data, its structure cannot be extended in future.
Seems to contradict the robustness principle for clients, that anyway should be prepared for additional properties in return data. So I would say we deprecate additionalProperties false here or, at least, give a hint on the consequences.

[rcillo]

@tfrauenstein I believe this is a problem only for plain json-schema, not for OpenAPI.

OpenAPI accepts only objects as valid values for additionalProperties. This is clarified in this related issue OAI/OpenAPI-Specification#668 since this constraint is not explicitly written in the OpenAPI spec.

That said, additionalProperties false/true are not valid when using OpenAPI.

[dehora]

I believe this is a problem only for plain json-schema, not for OpenAPI.

Not quite. Because Open API removes the true/false options such that there's no way to express anything goes, it's unclear what the default extension model is (in JSON Schema, it's open for extension, in Swagger and Open API it's undefined). Common sense, least surprise and the spirit of the guidelines suggests data is open for extension from HTTP APIs working under these guidelines, but that's not a strong basis for resolving differing interpretations.

That said, additionalProperties false/true are not valid

Strictly speaking they're ignored by some swagger tools, ie additionalProperties true doesn't necessarily cause an invalid error. That means teams who aren't reading deeply into multiple specifications may think they're defining something when they're not.

For defining events there's even more going on (as you know) since teams have to work with JSON Schema for event types and Open API for a HTTP API, but are often working with the same underlying entity. Also the rules are not the same, additionalProperties and undefined fields are handled more strictly for event type schema compatibility reasons.

It's really unfortunate, but I suspect we need to cover this. Even if a future Open API edition fixes its specification, we still have to deal with tools in the ecosystem that are lagging behind.

[tfrauenstein]

👍 @dehora It would be great, if you can contribute with related concrete PR proposal, thx.

[fmueller]

@dehora @tfrauenstein Is this issue already resolved with Bill's pull request?

[tfrauenstein]

Yes, resolved with Treat Open API Definitions As Open For Extension By Default. #195