v3.3: define an explicit default for the top-level "security" object - #5536
v3.3: define an explicit default for the top-level "security" object#5536karenetheridge wants to merge 1 commit into
Conversation
mikekistler
left a comment
mikekistler
left a comment
There was a problem hiding this comment.
I have concerns about this change.
| | <a name="oas-security"></a>security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. | ||
| If the `security` field is not provided, or is an empty array, the default value would be an array consisting of a single Security Requirement Object with no properties (`[{}]`), which indicates that security is optional. | |
There was a problem hiding this comment.
I am uncomfortable with this change, as it seems to change the meaning of an OpenAPI description that does not have a security field in an "Open World" interpretation of OpenAPI (which I think is how we want OpenAPI descriptions to be interpreted).
From [Is OpenAPI an Open World or a Closed World Contract?](#568):
In an open world we cannot make assumptions about what is not described.
So if security is not provideed/described, we cannot make assumptions about it -- including about whether it is optional or required. It may very well be required and simply not described.
There was a problem hiding this comment.
Isn't it already described that "no security" is the default, in the absence of any security specification? That is: how would an implementation's behaviour change?
There was a problem hiding this comment.
@mikekistler good point, but we cannot make any assumptions either way. Which is why I rely on what the spec stipulates today.
isn't it already described that "no security" is the default, in the absence of any security specification?
Let's discuss in the TDC
There was a problem hiding this comment.
Where in the spec does it state that "no security" is the default? I did try to find this myself but was unsuccessful.
There was a problem hiding this comment.
In an "Open World" interpretation of OpenAPI, what would be the security requirements if there are no security keywords anywhere in the document?
Similar to the "servers" default, this does not change any functionality; it only adds clarity.
7181419 to
0a03bbb
Compare
|
Discussion from the meeting: not documented is different to being optional. We agree we should close this PR. |
|
Example: an API has some sort of security requirement (that is not "allow all access"), but it is not documented as a Since we do not want to force users to document everything about the API, having this default present in the schema is not desirable. A lack of |
4 participants
Similar to the "servers" default, this does not change any functionality; it only adds clarity.
(I'm on the fence as to whether this should/could go into v3.2.)