[handrews]

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.

• schema changes are included in this pull request

This user appears to be farming participation events, possibly for future spamming or attempts to inject vulnerabilities into tooling or content.

[handrews]

Clean rebase force-push, no changes to commits. This is ready for review.

[miqui]

looks good to me. Perhaps a few more examples?

[miqui]

@handrews looks good. Can we add another example using more than one SAF?

usingFeatures:
  legacySecurity: 3.3.0
  lifeCycle: 1.0.0
$self: https://example.com/openapi
info:
  title: Example Pet Store App

[miqui]

btw, i am open to other names for the life cycle SAF.

[handrews]

@miqui we need to figure out whether we're going to really do feature-level SAFs (as we originally decided) or specification-level SAFs (which would make the versioning story substantially easier; we could always go more complex later if there is demand.

Here's examples of it both ways (the exact SAF/specification names are unimportant right now).

The way we originally decided (rar is both OAuth Rich Authorization Requests and GNAP's Resource Access Rights — they were developed together with the same structure and acronym on purpose):

usingFeatures:
  legacySecurity: 3.3.0  # SIG-security, migrated from the OAS
  rar: 1.0.0             # SIG-security, enhancement to Security Requirements
  deprecation: 1.0.0.    # SIG-lifecycle
  sunset: 1.0.0          # SIG-lifecycle

Simplified: the version number is the version of the SIG specification, and you use the specification all-or-nothing.

usingFeatures:
  security: 1.0.0  # Includes legacy, RAR, anything else we add
  lifecycle: 1.0.0 # Includes sunset, deprecation, and anything else we add

[handrews]

Rebased the original commit unchanged and added a new commit in response to comments above.

[miqui]

Thanks @handrews for your feedback. I am going to nudge @ralfhandl to finish his review.

[SensibleWood]

@miqui we need to figure out whether we're going to really do feature-level SAFs (as we originally decided) or specification-level SAFs (which would make the versioning story substantially easier; we could always go more complex later if there is demand.

Here's examples of it both ways (the exact SAF/specification names are unimportant right now).

The way we originally decided (rar is both OAuth Rich Authorization Requests and GNAP's Resource Access Rights — they were developed together with the same structure and acronym on purpose):

usingFeatures:
  legacySecurity: 3.3.0  # SIG-security, migrated from the OAS
  rar: 1.0.0             # SIG-security, enhancement to Security Requirements
  deprecation: 1.0.0.    # SIG-lifecycle
  sunset: 1.0.0          # SIG-lifecycle

Simplified: the version number is the version of the SIG specification, and you use the specification all-or-nothing.

usingFeatures:
  security: 1.0.0  # Includes legacy, RAR, anything else we add
  lifecycle: 1.0.0 # Includes sunset, deprecation, and anything else we add

@handrews my opinion on this is that the simplified version is the best match for how the discussion has evolved. My gut reaction on seeing rar as a feature is that this is too granular, and will take a lot of composition to manifest a bunch of features correctly.

Also rar doesn't really make sense on its own, as it should be considered in the context of something that implements it i.e. GNAP, OAuth, etc. It needs to be part of the wider security SAF to give it the right context i.e. this is used by a GNAP Object (however that manifests itself), this is used by an OAuth Profile Object, etc.

You could of course compose these relationships at a feature level, but then that requires a bunch of scaffolding that might be hard to maintain. Also humans would "probably" understand this stuff better as part of a larger "whole".

[baywet]

Collecting some notes from the meeting

There's a general agreement that we should do SAF level entries, as opposed of feature level entries to reduce the overhead in terms of publishing etc...

So something closer to this to take the earlier examples

usingFeatures:
  security: 1.0.0  # Includes legacy, RAR, anything else we add
  lifecycle: 1.0.0 # Includes sunset, deprecation, and anything else we add

Additionally: we need to review the name usingFeatures to have a more explicit name.

And more people should review this pull request :)

[miqui]

pending a few nits...looks good to me as a first pass.

[mikekistler]

Looks good. 👍

Changes were applied