Redocly / Redocly/redocly-cli

Bundler and linter fail when discriminator value is component name

Open
#1,877 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

$ref p3 Type: Bug
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Describe the bug

The OAS 3.1 spec states that the value of a discriminator mapping can be be a string that is the name of a component schema in the file:

The mapping entry maps a specific property value to either a different schema component name, or to a schema identified by a URI

And the spec provides examples like:

discriminator:
propertyName: petType
mapping:
dog: Dog

However when such a OAS schema is sent to the redocly cli linter or bundler it results in an error: "Can't resolve $ref"

To Reproduce
Pass this file to redocly lint or redocly bundle

openapi: "3.1.0"
info:
  title: pets
  version: 1.0.0
  license:
    name: Apache 2.0
    identifier: Apache-2.0

servers:
  - url: http://not.real.com/pets.yaml

paths:
  /get-pets:
    get:
      description: get pets
      summary: get pets
      operationId: get_pets
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Animals"
        400:
          description: not ok

components:
  schemas:
    Animals:
      type: object
      properties:
        elements:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/Cat"
              - $ref: "#/components/schemas/Dog"
            discriminator:
              propertyName: species
              mapping:
                dog: Dog
                cat: Cat

    Dog:
      type: object
      required:
        - species
      properties:
        species:
          type: string
          const: dog
        rating:
          type: number

    Cat:
      type: object
      required:
        - species
      properties:
        species:
          type: string
          const: cat
        tuxedo:
          type: boolean

  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: JWT auth0 token (without the word 'Bearer')
      bearerFormat: JWT

security:
  - Bearer: []

Expected behavior

The linter should not report errors.

Logs

OpenAPI description

Redocly Version(s)

1.28.0

Node.js Version(s)

v20.18.1

OS, environment

Mac OS 14.7.2

Additional context

The linter and bundler can be made to pass by changing the file:

            discriminator:
              propertyName: species
              mapping:
                dog: "#/components/schemas/Dog"
                cat: "#/components/schemas/Cat"

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

Reproduce the issue with the provided OpenAPI file using redocly lint and redocly bundle, focusing on discriminator mappings whose values are component names such as Dog and Cat. Trace the linter and bundler resolution entry points, then verify that both commands accept the schema without errors while preserving support for explicit $ref mappings.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.