OpenAPI-Specification
OpenAPI-Specification copied to clipboard
Clarify `security`; state what `[]` means
A partial fix for #3938 (partial because this PR only addresses 3.1.1-dev). Note that I have also created draft PRs to port this to the other two -dev
branches. I have no opinion on in which order they should be merged.
Thoughts as far as I can tell so far, as we still try to find some consensus.
Mostly we're talking about two cases: (1) security is not specified, and (2) security is specified but empty ([]
); and for each of those two cases, obvious options include (a) define it as "allow all" aka "no security"; (b) define it as "deny all" aka "there is no way to authorize"; (c) state that the behaviour is undefined; (d) state that the behaviour is implementation-defined.
Case 1: Leaving security
unspecified
- (a) "allow all" aka "no security"
- (b) "deny all" aka "no way in". I don't think anyone is suggesting this option.
- (c) undefined (which would be a sign that
security
should actually be a required field). I don't think anyone is suggesting this option either. - (d) implementation-defined
Case 2: security
is []
- (a) "allow all" aka "no security". A perfectly reasonable possibility; albeit one which makes the empty list a special case, not following the usual rules of list logic.
- (b) "deny all" aka "no way in". Also a perfectly reasonable possibility, and one where the list logic follows the usual rules. Under this option,
security: []
is how you express "deny all", andsecurity: [{}]
is one way of expressing "allow all". - (c) undefined
- (d) implementation-defined
Whichever one we opt for, could we also state that security: []
is deprecated? "Implementers of services SHOULD NOT introduce new instances of security: []
, and SHOULD seek an alternative formulation.", for example?