v3.1.1(schema): update empty security array constraint

[jeremyfiel]

based on discussions

• Clarification about the meaning of an empty security array #3938 (comment)

• Clarify security; state what [] means #4007

[handrews]

@jeremyfiel as with the other one this needs to go to main, but also I'm not sure why you have added this as [] is allowed.

[jeremyfiel]

Doesn't your comment infer from the spec language that at minimum for an undefined security requirement, the empty object SHALL be defined?

#3938 (comment)

[jeremyfiel]

I also commented in a slack discussion today that I believe the security requirement spec text is the only reference to an actual JSON structure where is recommends [{}] rather than only descriptive text.

https://open-api.slack.com/archives/C1137F8HF/p1725479409881939?thread_ts=1725473300.217419&cid=C1137F8HF

[handrews]

@jeremyfiel all of that was about defining what security: [] means, so that means it is a legal value and the schema cannot forbid it.

[jeremyfiel]

I suppose the wording To remove a top-level security declaration, an empty array can be used. contradicts the recommendation To make security optional, an empty security requirement ({}) can be included in the array.

[ralfhandl]

the wording To remove a top-level security declaration, an empty array can be used. contradicts the recommendation To make security optional, an empty security requirement ({}) can be included in the array.

No.

The top-level declaration in the OpenAPI Object is the default applying to all operations, and this may state "no authentication required" by including {} in the array.

An operation can opt out of this default in two ways:

1. with a non-empty array listing all mechanisms this operation supports
2. with an empty array saying "I don't tell you how to authenticate here", which probably implies that unauthenticated access allowed by the top-level default will probably not work

Should we need to elaborate this in the specification text?

[lornajane]

There are some problems with this pull request, but having discussed the proposed change (the newest commit), this isn't a useful change to make to our existing validation schemas since it is valid to have an empty security array. Please keep an eye on the project for more discussion about linting schemas in addition to our validation schemas.