<SchemaDefinition> do not work with remote reference

[exoego]

This is a bug report

What happend

If <SchemaDefinition /> custom element points to remote reference, like below:

  description: 
     Blah blah blah.

     Below is `Foo` definition.
     <SchemaDefinition schemaRef="./shared-components.yaml#/components/schemas/Foo"/>

it fails with a following error:

Something went wrong...
Invalid JSON pointer: ./shared-components.yaml#/components/schemas/Foo

on versions

• redoc@2.0.0-rc.18
• redoc@2.0.0-rc.15

Background

I want to extract components into an external file, so it can be shared among several swagger files, like below:

• swagger-public.yaml
• swagger-private.yaml
• shared-components.yaml

Remote reference feature in standard Swagger/OpenAPI syntaxes, like below, works fine 😄

  schema:
    $ref: "./shared-components.yaml#/components/schemas/Foo"

<SchemaDefinition /> works fine if used with local reference... but fails with remote reference. So I guess this is a bug (or a limitation) of <SchemaDefinition />

A motivation I use <SchemaDefinition schemaRef="..."/> in description is to embed a component definition into some description. Because Redoc currently does not have schemas view unlike official Swagger viewer.

[RomanHotsiy]

This is a limitation caused by how Redoc works with OpenAPI definitions.

The definitions is bundled by Redoc first so all the external file references are lost.

It can be fixed but requires some internal changes..

As a workaround, you can re-reference components from shared-components.yaml in swagger-public.yaml or swagger-private.yaml and then use local reference.

[garygitton]

@exoego To avoid too much duplicate code and keep one main schema, you can also do something like this.

tags:
  - name: error_model
    x-displayName: The Error Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Error" />

components:
  schemas:
    Error:
      $ref: ../models/Error.v1.yaml
      title: Error

It's not the best but we have no other choice for now.

[Blacklands]

I second the wish for this to be added.

While the proposed workaround of "re-reference the components in question within the root spec file and then use those local references" works, it is somewhat awkward. For example, all linting tools (including Redocly's own ones) now complain about those references being unused (since they can't detect their usage within the <SchemaDefinition> tag).

How large and complicated would the "internal changes" be to make external references work? Will these changes be coming anytime soon, maybe as part of other work, or is this fairly low priority for now?

[RomanHotsiy]

Well, the internal changes are large enough. This may be part of the next major 3.0 release (but we haven't published 2.0 yet) so timing is unclear here.

I think the only option that can land quickly is fixing detection in Redocly's own linting tool.

[Blacklands]

I can understand that this doesn't have a very high priority, since it's a very minor issue.

I think making Redocly's linting tool aware of the <SchemaDefinition> tag, so that it can see the usages there, would already be very helpful! Right now I needed to disable the unused-schemas rule for the linter entirely so that the warnings about this weren't drowning out everything else.

[marlon-chagas]

Any updates about this?