OpenAPI-Specification icon indicating copy to clipboard operation
OpenAPI-Specification copied to clipboard

Clarify `security`; state what `[]` means

Open rvedotrc opened this issue 6 months ago • 3 comments

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", and security: [{}] 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?

rvedotrc avatar Aug 08 '24 19:08 rvedotrc