reference name is not displayed in OpenApi 3.1.0 renderer

[ivan-klass]

Q&A

• OS: macOS
• Browser: chrome
• Version: 121.0.6167.139
• Method of installation: dist, cloud
• Swagger-UI version: any recent version, (checked from 5.2 to 5.10.3)
• Swagger/OpenAPI version: 3.1.0

A simple example Swagger/OpenAPI definition:

openapi: 3.0.3
info:
  title: Example
  version: 0.0.1
paths:
  /api/v1/example:
    get:
      operationId: example
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
components:
  schemas:
    Node:
      required:
      - id
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NodeId'
        name:
          type: string
        parentId:
          $ref: '#/components/schemas/NodeId'
    NodeId:
      type: integer
      description: Internal ID of a Node
      format: int32

Describe the bug you're encountering

When switching openapi: 3.0.3 to 3.1.0 renderer no more displays references with their names.

Expected behavior

Referenced types are shown with their name so it's easy to see reused components

To reproduce...

Use a provided example and compare results between 3.0.3 and 3.1.0

Actual behavior

Referenced types are inlined without name (e.g. NodeId in provided simple example) - hard to see common components when using complex schemas.

Screenshots

[gdebrauwer]

I'm having the same issue

[Krakozaber]

I'm having the same issue

p.s. To make it easier, you can remove collapsing from scalar types.

[char0n]

Hi everybody,

This explanation is going to be TL;DR.

SwaggerUI currently supports of OpenAPI 3.0.x Schema Object, which uses subset and extension of JSON Schema Draft 4/5. Schema Objects are being referenced by OpenAPI Reference Object and not by JSON Schema native $ref keyword.

This is how referencing using Reference Object in OpenAPI 3.0.x looks like:

{
  "$ref": "file.json#/pointer"
}

No additional fields are allowed to be defined as siblings to the $ref field.

SwaggerUI also supports OpenAPI 3.1.0 Schema Object, which represents extension of JSON Schema 2020-12. Schema Objects are not being referenced by OpenAPI Reference Object anymore, but uses native JSON Schema referencing mechanisms (more about it here).

This is how referencing using native JSON Schema referencing mechanisms in OpenAPI 3.1.0 looks like:

{
  "$id": "./relative-path",
  "$ref": "file.json#/pointer",
  "oneOf": [...],
 "pattern": "abc"
}

Notice that the $ref keyword can be accompanied by other keywords. When file.json#/pointer is eventually referenced, for simplicity let's say that the siblings keywords from referencing schema are merged with the referenced schema using shallow right merge algorithm (referencing schema is merged over the referenced schema). How the merge really works is described in this discussion). Now as you already see the identity of the referening and referenced schema is lost during the merge. Can we consider the merged schema to assume the identity of the referencing or the referenced schema? Technically it's a new schema with completely new identity.

Because of this new implications we've decided in the implementation that we'll no longer consider the old concept of "reference name". I know that in certain simple cases where referencing schema has just single $ref keyword and no siblings we can assume identity of the referenced schema, but we folded this simple use-case under the general umbrella of establishing new identity for every new schema that is created from merge of referenced and referencing schema.

JSON Schema 2020-12 now has a native identity management defined via $id keyword. The "$id" keyword identifies a schema resource with its canonical URI. This URI can be represented by URL or relative URI reference. As you imagine using URIs for "reference names" is a no go...

SwaggerUI is currently the only renderer that I'm aware of, that is capable to render JSON Schema 2020-12. There was no really other implementation, where we could look to get inspired. Currently it's possible to use description keyword to communicate information what the original referenced schema identity was. description keyword from referencing schema will always override description keyword from referenced one.

NOTE: Implementation wise rendering engines for Schema Object from OpenAPI 3.0.x and OpenAPI 3.1.0 are completely different.

[ivan-klass]

we folded this simple use-case under the general umbrella of establishing new identity for every new schema that is created from merge of referenced and referencing schema.

But how do you handle recursive structures such that they're not infinitely nested?

Also, the subject is only about display, even after the merge and de-referencing we can have a UI hint about original ref, can we? Because we have an original schema at hand. Like debuggers have a sourcemap for languages compiled into another one (say, TS to JS), we can have a mapping between de-referenced structure and the original one.
If there was a merge changes, we can display it with change mark, but if there were not - why not using a reference link?

[char0n]

But how do you handle recursive structures such that they're not infinitely nested?

This is handled by dereferencing. It's implemented as a state machine that implements advanced cycle detection and if the cycle is detected, reference is absolutified (if possible) and left unresolved.

Also, the subject is only about display, even after the merge and de-referencing we can have a UI hint about original ref, can we? Because we have an original schema at hand. Like debuggers have a sourcemap for languages compiled into another one (say, TS to JS), we can have a mapping between de-referenced structure and the original one.
If there was a merge changes, we can display it with change mark, but if there were not - why not using a reference link?

You cannot longer think in these simple term. Reference Object is not longer used to reference Schema Object in OpenAPI 3.1.0. In OpenAPI 3.1.0 only Schema Object can reference another Schema Object. Even when there is Schema Object with only $ref keyword referencing another Schema Object the result is not what you imagine. Observe:

#OpenAPI 3.0.x

schemaA.json

{
  "$ref": "/schemaB.json",
}

schemaB.json

{
  "properties": {
    "baz": true
  }
}

dereferenced.json

{
  "properties": {
    "baz": true
  }
}

Reference Object is replaced by Schema Object, no merging is involved.

OpenAPI 3.1.0

schemaA.json

{
  "$id": "identity",
  "$ref": "/schemaB.json",
}

schemaB.json

{
  "properties": {
    "baz": true
  }
}

dereferenced.json

{
  "allOf": [
    {
      "$id": "identity"
    },
    {
      "properties": {
        "baz": true
      }
    }
  ]
}

Referenced Schema Object is applied to the referencing Schema Object in spec compliant way. From two Schema Objects (referencing and referenced) we now have 3 Schema Objects.

---

Because of this complexities we opted not to implement the "reference name" concept as we determined that it's no longer applicable.

And yes, we could probably do what you describe - check if the referencing Schema Object has single $ref keyword and is directly referencing Schema Object from components.schemas and annotate new merged Schema Object with established "reference name". We just considered it not that important in the context of all things we needed to do.

[plesingr-aeb]

And yes, we could probably do what you describe - check if the referencing Schema Object has single $ref keyword and is directly referencing Schema Object from components.schemas and annotate new merged Schema Object with established "reference name". We just considered it not that important in the context of all things we needed to do.

Yes, please do!

[p-bakker]

Result when adding description and $id to a component in OAS 3.1.0 in https://editor-next.swagger.io/

Don't quite like the double inclusion of the $id value (BasicInfo in this case)
And also not great that you need to expand in order to see the additional info (see second screenshot) compared to how it was with OAS 3.0.0 (3rd screenshot)

OAS 3.1.0

OAS 3.0.0

[p-bakker]

If I replace $id property with a title, then the title property is used in the same way as $id was in the first screenshot (and the $id=.... obviously disappears)

However, it breaks the display of the schema in the Schemas section: cannot expand it anymore
And it doesnt do anything to improve the display situation of the schema under the Request Body

[adrianodpdiaz]

@lukaszzazulak I opened a related feature request in swagger-js that I think could be a good way to solve this properly from the client side:

swagger-api/swagger-client#4201

The idea is to expose a little more ref metadata when OAS 3.1 schemas are resolved, so Swagger UI can tell the difference between a plain $ref and a $ref with sibling keywords. That would bring back useful reference-name hints for the simple cases, without pretending every resolved schema still has the old OAS 3.0-style reference identity.

This could work as suggested on this thread, if the referencing Schema Object has single $ref keyword and is directly referencing Schema Object from components.schemas - annotate new merged Schema Object with established "reference name".

If this makes sense I could work on it.