Redocly / Redocly/redocly-cli

False positive no-required-schema-properties-undefined when required used inside not

Open
#3,104 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug

no-required-schema-properties-undefined false positive: required inside not (absence assertions / mutual exclusion).

The rule flags required entries inside a not subschema as "Required property 'x' is not defined." But required under not is the standard JSON Schema idiom for asserting a property's absence (or mutual exclusion of properties) — there is intentionally nothing to declare in a sibling properties, and the properties may even be declared on the enclosing object schema. The rule's purpose (catching typos where required names an undeclared property) doesn't apply to these assertion-only subschemas.

To Reproduce
redocly.yaml

extends: []
rules:
  no-required-schema-properties-undefined: warn

openapi.yaml

openapi: 3.1.0
info:
  title: Repro
  version: 1.0.0
paths:
  /contacts:
    post:
      operationId: createContact
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '201':
          description: Created.
components:
  schemas:
    Contact:
      type: object
      properties:
        email:
          type: string
        phone:
          type: string
      # email and phone are mutually exclusive
      not:
        required:
          - email
          - phone

Root cause: in no-required-schema-properties-undefined, findCompositionRoot walks up only through allOf/anyOf/oneOf parents (isCompositionChild), so any schema reached via not never resolves a composition root and its own (usually empty) properties is the only thing checked.

Actual behavior

#/components/schemas/Contact/not/required/0  Required property 'email' is not defined.
#/components/schemas/Contact/not/required/1  Required property 'phone' is not defined.

Expected behavior

No warnings. Either (a) required occurrences inside a not subschema (at any depth) are exempt, since they are presence/absence assertions rather than shape declarations, or (b) property resolution traverses the not boundary to the enclosing object schema the way it already traverses allOf/anyOf/oneOf.

Logs

OpenAPI description

Redocly version(s)

@redocly/cli 2.51.2

Node.js version(s)

OS, environment

Additional context

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 at the no-required-schema-properties-undefined rule and reproduce the issue with the redocly.yaml and openapi.yaml examples. Add regression coverage for required inside not, then run the rule's tests and confirm the example produces no warnings while existing undefined-property checks remain covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.