Managing SAF versions in an OAD

[handrews]

I had thought this was going to be very difficult, but after writing up a great deal of complicated exploration, it distilled down to something quite simple. The length here is due to showing several examples to handle different possible outcomes of #5349.

---

There are a few things to solve here:

1. Informing tools about what versions of things are involved in a document; this needs to be solved before we can have a viable SAF system
2. Using that information to detect and report conflicts between SAFs and "normal" descriptive behavior; we need to be sure tools can do this, whether or not we nail down all details up front
3. Handling different versions across different documents in a multi-document OAD; we could just require everything to match exactly for now, and formalize cross-version behavior later, either before or after shipping 3.3

Informing about versions

Versions and publications

Deciding on the publication mechanisms and related version granularity is taking place in discussion #5349.

This document assumes that SAFs are versioned somehow, and discusses both proposed possibilities of individual SAF versioning or SIG-level SAF group versioning. For this discussion, it doesn't matter if these versions come from registry entries, formal specifications, or some mix of things.

Semantic versioning

Semantic versioning (semver) is assumed, for reasons . While I have had my concerns with semver and specifications in the past, with SAFs we are moving more towards a standard library (the OAS proper) plus additional libraries (SAFs, or SIG-granularity SAF collections), which is the sort of versioning interaction semver was designed to support.

Declaring versions in a document

We currently have two specification versions that we declare in document-scoped fields in the OpenAPI Object:

• openapi for the OAS version
• jsonSchemaDialect for the JSON Schema dialect, which includes dialects from different drafts/versions; this has a default value if absent

We need to also declare SAF versions to ensure correct parsing and conflict detection, as will be seen further down.

The simplest thing to do would be to add a field where the SAFs in use in the document are listed, together with their versions. The names of the SAFs would be provided by each SAF's specification. This field could be called something like featureVersions, usingFeatures, etc. (just not features as we proably want to reserve that for the actual SAF Objects). Perhaps usingFeatureGroups if the usage is at the SIG granularity.

SAF-granularity example

If we have versioning at the SAF granularity (regardless of whether any of them are grouped into the same specification document), it could look something like:

openapi: 3.3.0
usingFeatures:
  httpAuth: 1.0
  authProfiels: 1.1
  httpSignatures: 2.0
  deprecation: 1.0
  sunset: 1.0
  cacheControl: 1.2
  x-some-ai-thing: 0.1

Pros:

• Very straightforward in structure
• Explicit about which SAFs are in use; tools assumed to implement individually

Cons:

• Not necessarily clear where each SAF is specified, so you probably have to check the registry

SIG-granularity example, explicit SAFs

If we want to have SIG-granularity specifications using only explicitly listed SAFs (and not allow mixing SAFs from different versions of the same specification), we could have something like this:

openapi: 3.3.0
usingFeatureGroups:
  security:
    version: 1.1.0
    features:
    - httpAuth
    - authProfiles
    - httpSignatures
  lifecycle:
    version: 1.0.0
    features:
    - sunset
    - deprecation
  http:
    version: 1.2.1
    features:
    - cacheControl
  registry:
    x-some-ai-thing: 0.1

You'll notice regsitry which is where the experimental/3rd-party SAFs, which I'm assuming here are versioned individually, live. There are various possibilities here depending on the granularity of registered SAFs, but this example shows that a hybrid approach is possible.

Pros:

• Shows where to find each SAF
• Explicit about which SAFs are in use

Cons:

• Lengthy and more complex in structure
• Tools need to version by SIG granularity, but enable/disable at SAF granularity

If SAFs within a SIG grouping interact with each other, allowing individual SAF enabling / disabling might allow users to shoot themselves in the foot. However, we could just make it clear which ones do that and mandate that if tools don't see the right dependencies, they MUST raise an error.

SIG-granularity example, all SAFs in each SIG assumed active

In this approach, using a SAF group means all SAFs are considered to be in use:

openapi: 3.3.0
usingFeatureGroups:
  security: 1.1.0
  lifecycle: 1.0.0
  http: 1.2.1
  registry:
    x-some-ai-thing: 0.1

Note that we still need the registry field as individually registered SAFs wouldn't have a group to list.

Pros:

• Short
• Simpler for tooling vendors- all or nothing per SIG-based SAF group
  Cons:
• Some "exception" logic might be unexpected, as the OAD author was not intending to use every SAF in the group, and might not realize that it's all or nothing.

This shifts more responsibility away from the tools and to the OAD author, which feels a bit questionable to me.

To make the "con" more concrete, let's say you included the http SAF group specification because you wanted its cache control feature, but your API also uses rate limiting. But your rate limiting usage is very simple so you just want to use a const schema for the RateLimit-Policy response header (assuming we allow headers at the API scope as discussed in #5314, just to make this example easier):

openapi: 3.3.0
usingFeatureGroups:
  http: 1.2.1 # includes Cache Control and Rate Limiting
features:
  cacheControl:
    ...
headers:
  RateLimit-Policy:
    schema:
      const: "..."

This would cause a problem because using the Rate Limiting SAF (implicitly included in the http group) creates an exception for the RateLimit-Policy header. If we fail-fast (see below), this is not too bad. The OAD author may have wasted some effort and need to refactor, but it would be clear how to do so. But this would remove some flexibility.

Detecting and reporting conflicts

Fail-fast

When introducing this amount of complexity, the best UX is for conflicts between SAFs and the "regular" way of doing things to immediately cause a clear error.

This is not what happens today with Security Schemes. You can have an in: header, name: Authorization parameter and it is silently ignored. Multiple of us in a recent TDC call affirmed that this has led to production OADs that have this error, without OAD authors realizing the problem at all.

Let's never do this again, please.

Document scope conflict checking

The openapi and jsonSchemaDialect fields are document-scoped, so usingFeature[Group]s (or whatever we call it) needs to be as well. The document is the unit of parsing, so this is the only thing that really makes sense (see farther down for how this works with multi-document OADs).

Each SAF would specify what exceptions it creates and how to handle them. For example, the Rate Limiting SAF might specify that it

• pre-empts describing the RateLimit-Policy and RateLimit headers
• requires (MUST) tools to raise an error if those headers are described in a document using the SAF

This example assumes headers is available at all levels as proposed (but not necessarily agreed-to) in #5314.

First, let's look at it without SAFS:

openapi: 3.3.0
headers:
  RateLimit-Policy:
    ... 
paths:
  /foos:
    headers:
      RateLimit:
        ...

With SAFs in use, but not changing the rest of the OAD.

openapi: 3.3.0
usingFeatureGroups:
  http:
    version: 1.0
    features:
    - rateLimiting
headers:
  RateLimit-Policy:  # Causes an error at parse time
    ... 
paths:
  /foos:
    headers:
      RateLimit:  # Causes an error at parse time
        ...

Using SAFs correctly, assuming a features field at multiple levels (levels per #5314) — please do not take this syntax too seriously, I just made it up right now:

openapi: 3.3.0
usingFeatureGroups:
  http:
    version: 1.0
    features:
    - rateLimiting
features:
  rateLimiting:
    ... # somehow sets global policy
paths:
  /foos:
    features:
      rateLimiting:
        ... # somehow puts constraints on runtime values

Handling multiple documents and versions

For OAS 3.2, we decided that since updating from 3.1 is so trivial (aside from extensions), we did not need to specify how to mix 3.1 and 3.2 documents in the same OAD.

With SAFs, the simplest thing to do, and perhaps where we should start even if we revisit it before shipping 3.3, is to just require that all major and minor (X.Y) versions across an OAD match exactly (except JSON Schema dialects, which are already well-defined for cross-version behavior).

• all documents MUST have the same X.Y in their openapi: X.Y.Z field
• for any SAF or SAF group, if it appears in more than one document (whether it is in the entry document or not), all appearances MUST have the same X.Y version numbers

Anything else MUST be treated as an error.

I have thoughts on how we could handle multiple compatible versions, but let's discuss that separately if/when we think it's reasonable to add. We are already adding complexity by allowing SAFs to version more-or-less independently. And initially, we won't have a bunch of versions of the same SAF anyway.