Redocly / Redocly/redocly-cli

illogical oneOf detection missing

Open
#1,486 8 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug

I found an impossible oneOf definition.

I'm constantly trying to educate people about oneOf vs anyOf. In any case, it would be better if the lint tool could catch impossible definitions.

To Reproduce

Most simple reproduction:

oneOf:
  - type: 'object'
  - type: 'object'

Here is the actual place I spotted it:

  1. Given this https://github.com/Rebilly/api-definitions/blob/main/openapi/components/schemas/Subscription.yaml#L119-L132 with a oneOf: $ref to InvoiceTimeShift object, null.
  2. The problem is that the InvoiceTimeShift object itself has a type of object or null.
  3. See error (that there are no lint catch of this problem).

Given that Rebilly is likely to change that before we finish this, here is how to reproduce it.

Excerpt from a schema:

  invoiceTimeShift:
    description: reduced to shorten example
    example: null
    oneOf:
      - $ref: ./InvoiceTimeShift.yaml
      - type: 'null'

Now, let's look at InvoiceTimeShift.yaml (only the first couple of lines needed):

type:
  - 'object'
  - 'null'

Why is this impossible? oneOf needs to match one and only only option. In this case, InvoiceTimeShift can be null, and the second option is also null (both the same). There is no way to distinguish which one was intended. Therefore, this is an impossible oneOf.

Expected behavior

I expected to be alerted to an incorrect oneOf definition. oneOf requires each item must be able to be distinguished from the other items (as opposed to anyOf).

Logs

n/a

OpenAPI description

See link above

Redocly Version(s)

latest (n/a)

Node.js Version(s)

n/a

Additional context

Noticed while debugging something unrelated.

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 schema reproduction in the issue, then locate the existing oneOf linting entry point and its tests. Done means the linter reliably reports overlapping oneOf branches, including the object/null reference example, without treating valid distinguishable branches as errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, tooling
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.