fix: report properties and items on any mismatched type in no-schema-type-mismatch

[dimitropoulos]

What/Why/How?

no-schema-type-mismatch only reported two specific combinations: properties on type: array and items on type: object. Any other mismatch passed, including this one:

schema:
  type: string
  properties:
    notification_email:
      type: string

This made it into our API description and broke code generation for us. Nothing in recommended, recommended-strict, or all flagged it, even though this rule exists to catch exactly this kind of mistake.

The rule now reports:

• properties on any type other than object
• items on any type other than array

The existing messages for array and object don't change. The rule still only checks schemas where type is a single string, so a 3.1 list such as type: [string, 'null'] is skipped, same as before.

Because the rule is error in recommended, descriptions that passed before can now fail. The changeset includes a note about this.

Reference

Testing

• Added a unit test covering type: string with properties and type: integer with items. The existing tests pass unchanged.
• Ran the built CLI with --extends recommended against the snippet above. It now reports Schema type mismatch: 'string' type should not contain 'properties' field.

Screenshots (optional)

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

Medium Risk
Stricter default lint in recommended can surface new errors on existing OpenAPI descriptions; rule logic change is localized to schema validation.

Overview
Tightens no-schema-type-mismatch so invalid structural keywords are caught for all single-string type values, not only object/array cross-mismatches.

The rule now errors when items appears on any type other than array and when properties appears on any type other than object (e.g. type: string with properties). It skips schemas whose type is not a single string (such as type: [object, 'null']). Diagnostic messages include the actual declared type.

Docs and tests cover primitives and multi-type schemas. The changeset flags that APIs using recommended may newly fail lint where mismatches were previously ignored.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: c4ef559

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

This PR includes changesets to release 6 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	Patch
@redocly/client-generator	Patch
@redocly/recheck	Patch
@redocly/respect-core	Patch
@redocly/reunite-integration	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

[Copilot]

🟡 Changes recommended

Boolean items schemas remain undetected, and the documentation overstates union-type coverage.

2 open findings

• Detect false-valued items on non-array schemas · New
• Limit rule documentation to single-string type schemas · New

What changed in this PR

Expands no-schema-type-mismatch to detect structural keywords on primitive schema types.

Changes:

• Broadens mismatch detection and error messages.
• Adds focused tests and documentation.
• Adds release notes for stricter lint behavior.

File	Description
packages/​core/​src/​rules/​common/​no-schema-type-mismatch.ts	Broadens mismatch checks.
packages/​core/​src/​rules/​common/​__tests__/​no-schema-type-mismatch.test.ts	Tests primitive-type mismatches.
docs/​@v2/​rules/​common/​no-schema-type-mismatch.md	Documents expanded behavior.
.changeset/​quiet-schemas-match.md	Records the behavioral change.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[dimitropoulos]

Leaving this as is. items: false on a non-array schema has no effect, so it can't cause the kind of tooling breakage this rule is meant to catch, and flagging it would just be noise. The truthiness check is also what the rule already did for object + items before this PR, so keeping it leaves existing behavior alone.

[dimitropoulos]

Fixed in c4ef559. The docs now say the rule only checks single-value type, and a new test asserts that type: [object, 'null'] with properties reports nothing.

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
latest	▓░░░░░░░░░░ 1.00x ± 0.01	▓░░░░░░░░░░ 1.00x ± 0.01	▓░░░░░░░░░░ 1.00x
next	▓░░░░░░░░░░ 1.00x	▓░░░░░░░░░░ 1.00x	▓░░░░░░░░░░ 1.01x ± 0.02