Allow $refs for vendor extensions

[jordanebelanger]

Hi,

I could be wrong, but it looks like vendor extensions can only be resolved as AnyCodable dictionaries of [String: Any]. It would be great if we could use $refs in vendor extensions, i.e be able to do something like this:

openapi: 3.1.0
...
x-vendor-extension-cors: "#/components/schemas/cors"
...
components:
  schemas:
    cors:
      allowedOrigins: 
        - "*"
      allowedMethods:
        - GET
        - POST
        - PUT
        - OPTIONS
        - PATCH
        - DELETE
      allowedHeaders:
        - Accept 
        - Authorization 
        - Content-Type 
        - Origin 
        - X-Requested-With,
        - Application-ID
    

[mattpolzin]

That's an interesting idea. Have you seen OpenAPI tooling support this before? It seems to me it might need to be specifically supported per-extension if it was the assumed behavior but it may be reasonable to offer a function in OpenAPIKit that resolves arbitrary strings as references so that a programmer could force that string to resolve as a reference.

At least according to the OpenAPI specification, any handling of refs inside extensions is undefined as far as I can tell (please correct me if I am missing anything).

Something that would still be unspecified under OpenAPI but possibly a bit less ambiguous under different types of specification extensions might be to use a full reference object:

x-cors:
  $ref: '#/components/schemas/cors'

For now I'll leave this ticket open unless you let me know the spec calls this out as being a feature of such extensions. It's certainly a nice-to-have capability if it can be done unambiguously (i.e. with guarantees that it doesn't break any vendor extensions, which probably means using the full Reference Object rather than a string value).

[mattpolzin]

I should clarify, in case your original question was about being able to put refs in extensions rather than being able to interpret extensions as refs: It is possible as of today to encode refs as AnyCodable in OpenAPIKit. This is possible because JSONReference (in v2 of OpenAPIKit) and OpenAPIReference (in v3 alpha releases) conform to Encodable.

[jordanebelanger]

This is my bad, I did not understand the way $refs work properly before, to be fair the openapi specifications are pretty extensive and I was getting confused by the way the security field works with its implicit linking😅

x-cors:
  $ref: '#/components/schemas/cors'

Is definitely how this should be done 😬