v3.3: First pass at explaining SAFs - #5447
Open
handrews wants to merge 1 commit into
Open
Conversation
3huss99-ui
previously approved these changes
Jul 25, 2026
karenetheridge
dismissed
3huss99-ui’s stale review
July 26, 2026 01:50
This user appears to be farming participation events, possibly for future spamming or attempts to inject vulnerabilities into tooling or content.
handrews
marked this pull request as ready for review
August 9, 2026 19:34
Member
Author
|
Clean rebase force-push, no changes to commits. This is ready for review. |
miqui
approved these changes
Aug 11, 2026
miqui
left a comment
miqui
left a comment
Contributor
There was a problem hiding this comment.
looks good to me. Perhaps a few more examples?
ralfhandl
reviewed
Aug 19, 2026
| | Field Name | Type | Description | | ||
| | ---- | :----: | ---- | | ||
| | <a name="oas-version"></a>openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. | | ||
| | <a name="using-features"></a>usingFeatures | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) names, as defined in various companion specifications, to a valid version string for the named SAF. Implementations MUST apply the SAF's rules, such as treating header parameters that are managed by the SAF as illegal in Parameter Objects, while processing the current document. The default is `{"legacySecurity": "3.3.0"}`. | |
Contributor
There was a problem hiding this comment.
What does this default value mean, and where is that meaning described?
Member
Author
There was a problem hiding this comment.
@ralfhandl oh, I don't think I meant to include this yet as it references something we have not decided, but the idea is:
- We should move the existing Security Scheme, OAuth Flows, and OAuth Flow Objects to the SIG-Security specification and treat them as a SAF, which I was calling
legacySecurity - For compatibility with OAS 3.2, if you don't explicitly set
usingFeaturesit assumes you are using the legacy security, as otherwise everyone's OAS 3.2 (or 3.1)-style security would break. - The
3.3.0was me thinking that since the legacy security was coming from the original OAS specification revision stream, it should keep that numbering (implicitly, the security in past OAS versions could be considered a SAF with the matching version... why we'd want to do that idk, I'm just explaining my thought process). - The Security Requirement Object probably stays in the main OAS, although I think that will become clear one way or another as we work with stuff.
I am also happy to take this part (and anything else that suggests we've made a decision on security compatibility) out of this PR. We can add it back when we make a decision there.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is to get conversation started on how we want to explain SAFs in the OAS. I'm not particularly attached to it, but as we get the SIG/SAF repositories up and running, we should figure out how to explain this to readers.