fix(no-required-schema-properties-undefined): resolve false positives for bare-required schemas in allOf-composed types

[jeremyfiel]

Summary

Fixes false positives in no-required-schema-properties-undefined for bare required constraints used in parent-property composition contexts.

Problem

The no-required-schema-properties-undefined rule could report false positives for valid JSON Schema patterns where a bare required list is used as a presence constraint on a property sub-schema, while the property’s actual type is defined through a parent composition context.

This affected two cases:

1. Bare-required property sub-schema override

properties:
  personName:
    required: [givenName, familyName]
allOf:
- $ref: '#/components/schemas/PersonBase'

2. Constraint-fragment branches

properties:
  communication:
    oneOf:
    - required: [landlines]
    - required: [mobiles]
allOf:
- $ref: '#/components/schemas/PersonBase'

Both patterns are valid under JSON Schema, where required and properties are independent keywords.

Solution

The rule now checks the parent-property context before reporting a missing required property. When the usual local-property and composition-root checks do not find the required key, it walks up the ancestor chain to find the containing property schema and then evaluates sibling composition branches (allOf/anyOf/oneOf) for that property.

This refactor keeps the logic focused on the parent-property context rather than treating it as a general composition-root lookup. In particular, the new parent-context check is distinct from findCompositionRoot / isCompositionChild: the latter answers whether the current schema belongs to a composition chain, while the new logic answers whether the enclosing property owns the schema and whether a sibling compositional branch defines the required property.

This preserves the existing behavior for misspellings: if a required key is not actually defined in the resolved property type, the rule still reports it as undefined.

Testing

Added regression coverage for:

• bare required constraints on property sub-schemas resolved through a parent allOf sibling
• oneOf-style constraint fragments
• anyOf-style constraint fragments
• existing misspelling behavior and other composition-related cases
• a new test ensuring the rule still reports undefined properties when the required key is not present in the parent-context sibling composition

Documentation

Updated the V2 rule documentation to describe the supported parent-context behavior for oneOf/anyOf constraint fragments.

relates to #2320 #2060 #2061

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Low Risk
Scoped to one lint rule’s property-resolution logic with broad test and doc updates; no auth, runtime API, or data-path changes.

Overview
Fixes false positives in no-required-schema-properties-undefined when schemas use valid JSON Schema patterns: property sub-schemas with only required (no local properties), or oneOf/anyOf branches that are pure required fragments, while the property’s shape comes from a parent allOf sibling (often via $ref).

The rule’s Schema visitor now falls back to hasPropertyInParentContext: it walks ancestor schemas, finds which named property holds the current sub-schema, and checks allOf/anyOf/oneOf siblings for definitions of keys listed in required. Misspelled required keys still fail that check and are reported.

Lint messages from the main schema path use is undefined instead of is not defined. Docs add PersonBase/Person examples for these patterns; a changeset marks @redocly/openapi-core and @redocly/cli as patch.

^{Reviewed by Cursor Bugbot for commit d34a79f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: d34a79f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	Patch
@redocly/client-generator	Patch
@redocly/respect-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jeremyfiel]

cc @baywet @Drowze would appreciate your feedback if you are using these constructs.

[tatomyr]

Finally got my hands on this. It looks mostly okay for me. However, I'd like to ask you to explore the possibility to solve this without introducing a new concept leveraging the existing logic (if possible).

[tatomyr]

Please do not modify V1 docs.

[tatomyr]

This line actually seems like it should do the same as the previous one, but from a different prospective. Maybe it worth modifying findCompositionRoot / isCompositionChild instead?
Also, the existing code has protection against circular references. Does your code have it? (I haven't found that in your tests.)

[jeremyfiel]

I think line 85 is actually a different concern from findCompositionRoot / isCompositionChild.

• isCompositionChild only checks whether the current schema is an item in a parent allOf / anyOf / oneOf.
• findCompositionRoot then walks that composition chain upward to the outer composed ancestor.

The logic at L85 is not just “what composition chain this schema belongs to”; it is “which ancestor property owns this schema, and does a sibling compositional branch define the required property?”

So I’d keep findCompositionRoot for composition-root lookup, and keep the parent-property / sibling-branch logic separate.

I did update the code a bit to reuse some existing utils like getOwn.

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓▓ 1.06x ± 0.01	▓▓ 1.04x ± 0.01	▓▓▓▓▓▓▓ 1.20x ± 0.01
cli-next	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d34a79f. Configure here.}

[cursor]

Sibling property lookup skips composition

Medium Severity

checkSiblings only reads a sibling’s direct properties map and returns false when that map is missing. Property keys defined through nested allOf/anyOf/oneOf on the resolved sibling are ignored, so valid bare-required overrides against composed base schemas still false-positive. This diverges from schemaHasProperty, which already walks composition.

 

^{Reviewed by Cursor Bugbot for commit d34a79f. Configure here.}

[jeremyfiel]

I feel like this could be important for some very advanced schema users but, also a pretty advanced edge case. I'll play with this a bit and see if I can get it working with nested composition but, as it stands, I think I'm ok with the current implementation, if you are.

[cursor]

Inconsistent required-property error text

Low Severity

The Schema enter path now reports is undefined, but reportUndefinedRequired used by the ref leave path still reports is not defined. Same rule, same condition, different user-facing text, and the docs only document the new wording.

Additional Locations (1)

• packages/core/src/rules/common/no-required-schema-properties-undefined.ts#L28-L29

 

^{Reviewed by Cursor Bugbot for commit d34a79f. Configure here.}

[jeremyfiel]

i'll leave this one to you if you want to update the grammar.