implement OAS3.1 dynamic references

[hesxenon]

Description

Generic data types

Proposal

Apparently since OAS3.1 it is possible to define $dynamicAnchor and $dynamicRef to achieve something resembling higher kinded types.

It appears that this is not possible yet.

Given
EDIT: example below is flawed, see here for official example

paths:
  /foos:
    get:
      responses:
        200:
          description: returns foos
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/List"
                $dynamicAnchor: T
                properties:
                  foo:
                    type: number
                  bar:
                    type: string
components:
  schemas:
    List:
      type: array
      items:
        $dynamicRef: T

I'd expect (if I'm reading the scarce info correctly)

interface paths {
  "/foos": {
    get: {
      responses: {
        200: {
          content: {
            "application/json": Array<{foo: number, bar: string}> // since typescript does not have higher kinded types (yet) I think the anchor should directly merge with the ref?
          }
      }
    }
  }
}

interface components {
  schemas: {
    List: never; // types marked with $dynamicRef should probably be reduced to avoid accidental widening later on
  }
}

Checklist

• I’m willing to open a PR for this (see CONTRIBUTING.md) - sorry, absolutely no time currently, maybe in a week or so

[hesxenon]

it seems my testing method was wrong, I'll investigate further. Have updated the example with a link to the official docs

[drwpow]

This is definitely something we’d love to support. I think this likely looks like something we could do in partnership with the Redocly Core library, since that handles resolution and normalization of the OpenAPI schemas. Plus, adding support there would be a win for many projects using either (did a quick search and it doesn’t seem like they support it today, but I could be mistaken).