Native OAS Versioning Support

[perlboy]

Description

Currently the Standards rely upon a header to communicate the version. While this is functional and a number of libraries have been developed to provide it the nature of this approach is that it binds the HTTP layer to the payload layer. This binding isn't particularly common because often the data processing layer (ie. the payload parsing) is done in isolation of the comms layer (ie. the http layer).

With the introduction of OAS3 specifications with the Standards there is now a viable pathway to align specifications in such a way that code generation tools work "out of the box". This involves the introduction of a discriminator allowing for an attribute and it's value to be mapped to a specific schema.

There is some testing required to ensure that the outcome is aligned with the most common codegen tools particularly openapi-generator and swagger-codegen.

Area Affected

All endpoints.

Change Proposed

This isn't a "detailed description" as outlined in the template but more an opening gambit on giving an example of what this would look like.

By way of example if we take a look at Get Banking Account Detail there is a V3 and V4 payload which is intended to be concurrent. As a baseline this would look like adding an attribute of xV to the root object. As a side note I'm not sure meta.version would work as an alternative (ie. not sure if the tools would accept it) but that's worthy of evaluating too so we don't pollute the root object (and Meta finally gets something! 😉 ).

So, assuming that a xV attribute was added to all Response payloads the response definition without a container abstraction added in would look something like this:

responses:
  200:
    description: Success
    content:
      application/json:
        schema:
          discriminator:
            propertyName: xV
            mapping:
              V3: "#/components/schemas/ResponseBankingAccountByIdV3"
              V4: "#/components/schemas/ResponseBankingAccountByIdV3"
          anyOf:
            - "#/components/schemas/ResponseBankingAccountByIdV3"
            - "#/components/schemas/ResponseBankingAccountByIdV4"

Essentially xV value in the response payload would be V3 or V4 allowing a parser to then directly cast to strongly typed models matching the appropriate version. That has lots of "wins" for developers because they can now do code path decisioning based on a solid model, something we are essentially fuzzing based on the header side.

As a footnote the use of anyOf versus oneOf seems a bit confused on expected approach but our testing seems to indicate anyOf is more appropriate here to allow for dynamic polymorphic responses (ie. endpoints that might alternate between the payloads during a blue/green deployment).

[nils-work]

Related discussion - #538 (comment)

[biza-io]

Biza believes the best path forward is to align exclusively to OpenAPI 3.0.

There are two drivers for this suggestion:

1. Supporting backward compatibility to Swagger would risk the DSB publishing a specification that is inaccurate, particularly if/when oneOf is adopted in OpenAPI 3, Swagger would be unable to describe this effectively.

2. OpenAPI 3.1 support within ecosystem tooling is limited with venerable OpenAPI rendering (redocly) and code generators (openapi-generator) not having complete OpenAPI 3.1 support.

[nils-work]

DSB Item - OpenAPI Spec. (OAS) version plan #131 has been raised as a Future-Plan Decision Proposal placeholder to be addressed outside the Maintenance cycle.