Expose original OAS 3.1 $ref fields in resolver meta patches

[adrianodpdiaz]

Content & configuration

Swagger/OpenAPI definition:

openapi: 3.1.0
info:
  title: Example
  version: 1.0.0
paths: {}
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string

    UserList:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"

    UserListWithDescription:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
            description: Users returned by this operation

Swagger-Client usage:

SwaggerClient.resolveSubtree(spec, ["components", "schemas", "UserList"])

Is your feature request related to a problem?

Swagger Client adds $$ref to resolved OAS 3.1 schemas, but $$ref does not tell consumers whether the original schema was only a $ref, or a $ref with sibling keywords.

That matters for renderers like Swagger UI. A plain ref can safely be shown as a reference to User, but this is different:

items:
  $ref: "#/components/schemas/User"
  description: Users returned by this operation

In OAS 3.1, sibling keywords are part of the schema. After resolution, both cases may still have $$ref, so downstream code cannot reliably tell them apart.

Describe the solution you'd like

Today, the resolved plain object only exposes $$ref as the ref-related meta patch:

{
  type: "object",
  properties: {
    id: { type: "string" }
  },
  $$ref: "https://swagger.io/#/components/schemas/User"
}

That output is the same shape whether the original schema was just:

$ref: "#/components/schemas/User"

or had sibling keywords:

$ref: "#/components/schemas/User"
description: Users returned by this operation

It would be helpful to also expose the original ref fields in the resolved plain object when allowMetaPatches is enabled.

For example:

{
  type: "object",
  properties: {
    id: { type: "string" }
  },
  $$ref: "https://swagger.io/#/components/schemas/User",
  $$refFields: {
    $ref: "#/components/schemas/User"
  }
}

And when the original schema had siblings:

{
  type: "object",
  description: "Users returned by this operation",
  properties: {
    id: { type: "string" }
  },
  $$ref: "https://swagger.io/#/components/schemas/User",
  $$refFields: {
    $ref: "#/components/schemas/User",
    description: "Users returned by this operation"
  }
}

The property name does not need to be $$refFields; any clear internal meta field would work.

Describe alternatives you've considered

Swagger UI can infer from $$ref, but that is not reliable enough for OAS 3.1.

Swagger UI can always use $$ref as a label hint, but that can be misleading when the original schema had siblings.

Additional context

The OAS 3.1 dereference strategy already keeps ref-fields as ApiDOM metadata internally. This request is to expose that information, or a small equivalent, through allowMetaPatches.