feat: add new `schema` assertion by AlbinaBlazhko17 · Pull Request #3063 · Redocly/redocly-cli

AlbinaBlazhko17 · 2026-08-31T09:59:41Z

What/Why/How?

Added new schema assertion to be able to force specific schema for the property.

Reference

Resolves #3060

Testing

Tests, ran locally and tested in VS code extension.

Screenshots (optional)

CLI:

VS Code:

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
Touches core lint assertion plumbing and AJV validation defaults (allowAdditionalProperties: false); behavior changes for rules using schema and for how multi-location assertion failures are grouped into messages.

Overview
Adds a schema configurable-rule assertion so lint rules can validate a subject property’s value against JSON Schema (2020-12) via the existing AjvValidator path used for OpenAPI 3.1.

Rule authors can embed a full schema in redocly.yaml (for example on x-* extensions); violations emit one diagnostic per issue at the failing path. undefined values are skipped; invalid assertion schemas throw at config/use time. When the subject is a $ref, problems are reported against the resolved document location.

Config typing replaces the minimal Schema stub in the Redocly config type tree with Oas3_1Types.Schema (and related nodes), so IDE/schema validation accepts real JSON Schema keywords for assertions.schema.

Assertion reporting groups sub-problems by source + pointer (groupProblemsByLocation) instead of pointer alone, so multi-file/$ref cases don’t merge unrelated issues.

Docs, changeset (minor for @redocly/openapi-core and @redocly/cli), and unit/integration tests cover happy path, additional/unevaluated properties, refs, and end-to-end lint output.

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

changeset-bot · 2026-08-31T09:59:50Z

🦋 Changeset detected

Latest commit: 6a386db

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	Minor
@redocly/cli	Minor
@redocly/client-generator	Patch
@redocly/respect-core	Minor

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

github-actions · 2026-08-31T10:02:02Z

Performance Benchmark (Lower is Faster)

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

github-actions · 2026-08-31T10:02:53Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	78.56% (🎯 77%)	13965 / 17775
🔵	Statements	78.34% (🎯 77%)	15057 / 19218
🔵	Functions	82.31% (🎯 81%)	2877 / 3495
🔵	Branches	71.62% (🎯 71%)	10374 / 14484

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/core/src/rules/common/assertions/asserts.ts	84.84%	80.62%	89.65%	91.86%	80, 103, 122, 162, 179-187, 196, 199-205, 258, 351, 383
packages/core/src/rules/common/assertions/utils.ts	84.31%	66.29%	69.23%	88.54%	51, 55, 59, 84-86, 90-92, 143, 164-166, 179, 191-199, 259, 279-280, 296
packages/core/src/types/redocly-yaml.ts	89.32%	77.35%	92.85%	89%	493, 525, 531, 569-576, 578, 717-727, 737-753

Generated in workflow #11568 for commit 6a386db by the Vitest Coverage Report Action

… broken, add strict schema

… and properties

tatomyr

Didn't check the code yet.

tatomyr · 2026-08-31T14:10:30Z

+'@redocly/cli': minor
+---
+
+Added the `schema` assertion for configurable rules.


Suggested change

Added the `schema` assertion for configurable rules.

Added new `schema` assertion for configurable rules to be able ...

?

tatomyr · 2026-08-31T14:13:10Z

+
+The assertion reports one problem for each violation, at the location of the value that fails.
+
+The assertion keeps standard JSON Schema behavior:


Do we need to explain how json schema works? Maybe yes... I often see people get confused with that.

Added for two purposes:

User could think that if he add property to the schema in assertion it is required

Some users miss by default additionalProperties: true

I will change the behavior to additionalProperties: false

tatomyr · 2026-08-31T14:15:23Z

+
+Two limits apply to the schema itself:
+
+- A `$ref` is resolved against `redocly.yaml` before the assertion runs, not against the schema.


The rule could reside in a file other than redocly.yaml (e.g. could be referenced from it).

We support external refs.
e.g.

rules: rule/audit: subject: type: Info property: x-audit assertions: schema: type: object properties: status: $ref: './audit-status.yaml'

against the current file

tatomyr · 2026-08-31T14:17:09Z

+- A `$ref` is resolved against `redocly.yaml` before the assertion runs, not against the schema.
+  A pointer such as `#/$defs/Status` therefore looks inside the configuration file, not inside the assertion.
+- A keyword that JSON Schema does not define fails the rule, so a typo such as `tpe` instead of `type` is reported instead of being ignored.
+  The OpenAPI annotations `example`, `nullable`, `externalDocs`, `discriminator`, and `xml` are accepted.


There's no nullable keyword. Moreover, none of that keys are useful for schema validating, so I wouldn't mention them.

I've added those keywords, because i need to have option in ajv strictSchema: true to be able to throw a typo error. But ajv with strictSchema don't support those keywords and throws an error, so i needed to extend the ajv with addKeyword.

tatomyr · 2026-08-31T14:17:37Z

+
+- A `$ref` is resolved against `redocly.yaml` before the assertion runs, not against the schema.
+  A pointer such as `#/$defs/Status` therefore looks inside the configuration file, not inside the assertion.
+- A keyword that JSON Schema does not define fails the rule, so a typo such as `tpe` instead of `type` is reported instead of being ignored.


It's just a regular behaviour when validating Redocly config, no need to mention it specificaly in this assertion.

No, the error goes from the ajv validator, where i put strictSchema: true.

Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

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

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

feat: add new assertion

06a70bd

AlbinaBlazhko17 added 2 commits August 31, 2026 14:20

chore: remove sentence from changelog

f5cde5f

feat: add report even if there is no subject, but in config schema is…

9f58c56

… broken, add strict schema

AlbinaBlazhko17 marked this pull request as ready for review August 31, 2026 11:50

AlbinaBlazhko17 requested review from a team as code owners August 31, 2026 11:50

cursor Bot reviewed Aug 31, 2026

View reviewed changes

Comment thread packages/core/src/types/redocly-yaml.ts Outdated

Comment thread packages/core/src/rules/common/assertions/asserts.ts Outdated

AlbinaBlazhko17 added 2 commits August 31, 2026 15:06

fix: an issue with the wrong type of items, not, additionalProperties…

4c57388

… and properties

fix: issue with wrong ref location in report

21649d0

cursor Bot reviewed Aug 31, 2026

View reviewed changes

Comment thread packages/core/src/rules/common/assertions/asserts.ts

fix: grouping refs in report

7d1352a

JLekawa reviewed Aug 31, 2026

View reviewed changes

Comment thread docs/@v2/rules/configurable-rules.md Outdated

Update docs/@v2/rules/configurable-rules.md

5768413

JLekawa approved these changes Aug 31, 2026

View reviewed changes

tatomyr reviewed Aug 31, 2026

View reviewed changes

AlbinaBlazhko17 and others added 3 commits August 31, 2026 17:30

Apply suggestion from @tatomyr

c457c40

Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>

docs: enrich changesest

be6a4da

refactor: general refactoring

57c7c5a

cursor Bot reviewed Aug 31, 2026

View reviewed changes

Comment thread packages/core/src/rules/common/assertions/asserts.ts Outdated

AlbinaBlazhko17 added 2 commits August 31, 2026 19:07

fix: pin the spec version

7850029

docs: remove sentence

6a386db

	Added the `schema` assertion for configurable rules.
	Added new `schema` assertion for configurable rules to be able ...


		The assertion reports one problem for each violation, at the location of the value that fails.

		The assertion keeps standard JSON Schema behavior:


		Two limits apply to the schema itself:

		- A `$ref` is resolved against `redocly.yaml` before the assertion runs, not against the schema.

Uh oh!

Conversation

AlbinaBlazhko17 commented Aug 31, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Benchmark (Lower is Faster)

Uh oh!

github-actions Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tatomyr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AlbinaBlazhko17 commented Aug 31, 2026 •

edited by cursor Bot

Loading

changeset-bot Bot commented Aug 31, 2026 •

edited

Loading

github-actions Bot commented Aug 31, 2026 •

edited

Loading

github-actions Bot commented Aug 31, 2026 •

edited

Loading