Spec / Protocol versioning

[tulshi]

In order for Receivers to detect capabilities of the Transmitter and appropriately talk with them, the Transmitter must indicate the features / version of the protocol it supports.

Following is the context from a discussion with Mike Jones and Mark Haine on 10/2/2023:

• Mike proposed that we do not actually version the protocol, because of two reasons:

  • Versions may not be linear. People may add different features and may support different features in the future, so a linear version scale may not make sense. For instance, the OAuth spec is not versioned, but it has many additional features such as PKCE, DPoP, CIBA etc. Participants can individually support these features.
  • We already have draft numbering, and protocol version numbers may be hard to distinguish from that.

• Mike proposed that we add specific feature flags in the Transmitter Configuration Metadata. We currently have two things that require versioning:

  • Sub_id at top level
  • API style (previous API has differences with the current API)

• Mark pointed out some parallels (and pitfalls) with other specs such as Identity Assurance, where they are using this approach.

[tulshi]

Shayne's comments on above proposal:

• What should we do about features that might be dependent on one another? Let's say we move forward with the API style feature (which I might call the "multiple streams feature" instead) and then later we make further breaking changes to the API. It might be impossible to have that new API change feature without also having the multiple streams feature in place.
• I think we might have more than those two breaking changes. The fact that we removed subject status comes to mind as a third example. Do we need to do an audit of the PRs that have been merged since the last draft?