Redocly / Redocly/redoc

Two $ref containing "~1" (escaped slash) cause "Invalid reference token:"

Open
#2,337 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

p1 Type: Bug
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

Describe the bug
Redoc shows an error screen when,

  • there are two $ref pointing external file (I'm not sure about more than two)
  • both of them include ~1, escaped slash character, in its JSON pointer tokens
  • both of them referencing different files (or JSON pointer tokens?)

This does not happen if the value of two $refs references are same or the path does not include ~1.
The error message for

$ref: "./responses.yml#/StringResponse/application~1json/schema"

is

Something went wrong...

Invalid reference token: application/json-schema 

(Reproduction CodeSandbox)

Expected behavior
Docs appears without an error, or shows an error that a user can fix or work-around the problem.

Minimal reproducible OpenAPI snippet(if possible)

# oas.yml
openapi: "3.1.0"

info:
  title: "Redoc JSON pointer parsing bug"
  version: "0.0.1"

paths:
  /foo:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "./responses.yml#/StringResponse/application~1json/schema"

  /bar:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "./responses.yml#/NumberResponse/application~1json/schema"
                # Using this ref instead of the NumberResponse works
                #$ref: "./responses.yml#/StringResponse/application~1json/schema"
                # Using this (no slash in pointer tokens) ref instead of the NumberResponse works
                #$ref: "./responses.yml#/ObjectResponse/application-json/schema"
# responses.yml
StringResponse:
  application/json:
    schema:
      type: string

NumberResponse:
  application/json:
    schema:
      type: number

ObjectResponse:
  application-json:
    schema:
      type: object
      properties:
        foo:
          type: string

Screenshots
None.

Additional context
None.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the minimal oas.yml and responses.yml reproduction, then trace Redoc's handling of external $ref values and JSON Pointer tokens containing ~1. Done means both StringResponse and NumberResponse render without an "Invalid reference token" error, while equivalent references without ~1 continue to work.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.