How to publish SAF specifications

[handrews]

TL;DR: We should use the SIG concept to define companion specification granularity for SAFs.

---

In the last TDC call, we discussed how to publish SAFs. Everyone on the call agreed (or at least failed to object within a reasonable amount of time) that:

• The JSON/YAML describing a SAF belongs in the OAD, not in any mandated-to-be-separate document(s)
• SAFs, as new features sometimes tied to fast-moving technology areas, need to iterate more quickly than the core OAS
• SAFs likely need different contributors and have a different audience of experts

There are concerns about how to ensure OAS readers understand that SAFs exist and can be used, but this is an orthogonal concern being discussed in #TBD.

Possible mechanisms

We briefly discussed several possible delivery mechanisms in the TDC call, but did not attempt to settle on one. This discussion builds on what was discussed there with a deeper examination of how the mechanisms relate to the above requirements.

Note that all of the mechanisms involve one or more registries somehow, but the way registries are used differ.

Note also that registry entries are always opt-in unless madated (MUST/SHALL or SHOULD/RECOMMENDED) by the OAS itself; to make any or all entries mandatory on their own effectively makes them the same as formal specifications, but with a different publishing format. This is the worst of both worlds (all the approval overhead, none of the familiar look and feel) and not worth considering (although see "one spec per SAF" below).

In the OAS itself

Registries would only be used for experimental or 3rd-party extension SAFs, as with experimental or 3rd-party extension keywords today.

This was universally rejected. @baywet noted that he already gets feedback that the OAS is too long, making it difficult to read and digest. SAFs would explode the size of the OAS. It also by definition fails the "iterate quickly" requirement, and does nothing to support the "different contributors/audience" requirement.

Using only a registry

All SAFs would be defined in a registry, and the OAS would simply point to it and note which SAFs MUST or SHOULD be supported (all others are implicitly MAY).

This would allow different / more focused contributor groups and review audiences. However...

While this allows fast iteration on experimental or 3rd-party SAFs, it fails the "iterate quickly" requirement for formally required SAFs. My interpretation of "iterate quickly" is that it applies to formal requirements, as that is the only way to ensure interoperability, especially for highly-regulated areas like finance and security.

One specification per SAF

In this approach, the registry would just point to the specifications, whether they are formal OpenAPI Initiative specifciations or experimental/3rd-party extensions.

This would allow both quick iteration and specific contributors/audiences.

However, it seems incredibly high-overhead given the potentially large number of SAFs and the fact that some are quite simple and small. I'm open to counter-arguments, but just managing the GitHub repos and release processes at this granularity feels overwhelming to me.

SIG-granularity specifications grouping related SAFs

In this approach, the registry is used for experimental and 3rd-party extension SAFs, and as an index to which SAF is specified where (just as the current Media Types Registry is an index of which OAS section requires each media type).

This approach is appealing as it re-uses a governance and release structure that has been successful for us in the past (Workflows/Arazzo and Overlays).

The only logistical difference from Workflows/Arazzo is that the resulting specifications directly impact OAD structure instead of producing companion documents. But that is also the case for Moonwalk, which we had started treating as a SIG.

We can have SIGs that do not have dedicated meetings (currently true of Moonwalk), but we have a framework for running meetings if we need them.

There are also existing dormant SIGs for the two most readily identifiable groups of SAFs:

• SIG-security, which we've been looking at already for prior art in this area, spanning:
  • Authentication
  • Authorization
  • Message security (content digests, cryptographic signatures, proof-of-posession, etc.)
• SIG-lifecycle, which has an empty repo but is the obvious home for:
  • Deprecation
  • Sunset
  • some other lifecyle-related requests in various issues

The fact that this approach lines up with what we had already been doing, with governance structures and precedent for publishing specifications, suggests that it is the correct approach to me.

It meets both the "iterate more quickly" requirement and the "different audiences" requirenents — no surprise as these are among the reasons we created SIGs. There is some penalty to "iterate more quickly" as a complex SIG specification like Security may not be as rapid as a single SAF, but SAFs that really need to move extremly fast probably ought to be considered experimental and managed through the registry until they stabilize. (It might also be feasible to have a few security-related specifications as it is such a big area).

We would need at least a 3rd SIG/SAF group specification to cover all of what has been requested. We don't need to nail that down here, but to give a sense, here are some requests that have come up:

• Rate limiting (could make an argument for security, but I feel it's different?)
• Cache control
• Retries (arguably both too runtime-oriented and too easily described by the Header Object as-is to be a SAF)
• Preferences (which we discussed in the lead-up to the SAF concept)

These are all arguably HTTP behavioral modifiers of some sort, so maybe SIG-http? Preferences are a little different as they are more about resource semantics... SIG-resources? We do not need to solve this problem now, I just wanted to acknowledge that not everything fits into an existing SIG, which lets us poke at how the SIG framework may or may not work for them.