feat(openapi-parser): validator overhaul #7171

luke-hagar-sp · 2025-10-24T22:14:32Z

Problem

Currently, …

Solution

With this PR …

Checklist

I've gone through the following:

I've added an explanation why this change is needed.
I've added a changeset (pnpm changeset).
I've added tests for the regression or new feature.
I've updated the documentation.

Note

Upgrades AJV and schemas to improve OpenAPI validation (incl. refs in paths) and delivers clearer, deduplicated errors with expanded tests.

Validator (src/lib/Validator/Validator.ts):
- Add draft-07 support via Ajv; enable discriminator and allErrors options.
- Pass full specification to transformErrors; refine error handling.
Schemas:
- v2.0 (schemas/v2.0): allow paths entries to be oneOf pathItem or jsonReference.
- v3.0 (schemas/v3.0): introduce PathItemOrReference and use it in Paths; add discriminator to SecurityScheme oneOf; clean up PathItem fields.
- v3.1 (schemas/v3.1): use path-item-or-reference for paths.
- v3.2 (schemas/v3.2): use path-item-or-reference across paths, webhooks, and component pathItems; add conditional path-item-or-reference and related structural updates.
Error handling:
- types: extend ErrorObject with optional path.
- betterAjvErrors: add oneOf/if/additionalProperties/unevaluatedProperties handling; smarter redundancy filtering.
- transform-errors: guard invalid specs, try/catch fallback to raw AJV errors, format additionalProperties messages, deduplicate by message+path.
Tests (tests/openapi3-examples/3.0/fail/*):
- Update expectations for new error messages, paths, and counts; skip overly noisy suite (openapi-vue).

^{Written by Cursor Bugbot for commit bb56d7e. This will update automatically on new commits. Configure here.}

changeset-bot · 2025-10-24T22:14:36Z

⚠️ No Changeset found

Latest commit: bb56d7e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

…verable" error

luke-hagar-sp · 2025-10-28T16:38:44Z

Hello Scalar!

Big fan of the tooling you all are building here.

I'm looking to use some of the tools here on our API Specifications at SailPoint and I want to refine the error handling a bit and hopefully get some better output in certain situations, so I took a look at the underlying validation logic and I think I was able to make some good changes here.

Would anyone mind reviewing this PR?

If you are happy with these changes I have some additional changes/improvements in mind.

@hanspagel @marclave @geoffgscott

marclave

passing to @geoffgscott @amritk @DemonHa to review :) but looks cool!

amritk · 2025-10-30T23:34:32Z

@marclave I believe @hanspagel is back! This is parser stuff

hanspagel

NICE

Actually, I‘d love to see a version that doesn’t use ajv somehow, and a functional approach. This was more or less copied from somewhere and has a bunch of flaws.

That said, your PR is a huge improvement over the status quo. 🙏

packages/openapi-parser/tests/openapi3-examples/3.0/fail/invalidSchemaName.test.ts

hanspagel · 2025-11-03T09:21:09Z

packages/openapi-parser/tests/openapi3-examples/3.0/fail/invalidSchemaName.json

      "requestBody1": {
        "content": {
          "application/json": {
-            "description": "Pet object that needs to be added to the store",


why did we remove those comments? 🤔

Descriptions are invalid at these places in the document

packages/openapi-parser/tests/openapi3-examples/3.0/fail/invalidPattern.test.ts

packages/openapi-parser/tests/openapi3-examples/3.0/fail/hasFlowNotFlows.test.ts

hanspagel · 2025-11-03T09:24:10Z

packages/openapi-parser/src/lib/Validator/Validator.ts

-            errors: transformErrors(entrypoint, validateSchema.errors),
+            errors: transformErrors(specification, validateSchema.errors),


can we call it document?

I know, people refer to it as the "specification", but the specification is the actual standard, not the document (or definition).

LukeHagar · 2025-11-03T13:49:12Z

Great feedback!

I'll make some changes when I log on for the day

…idSchemaName.test.ts Co-authored-by: Hans Pagel <hanspagel@users.noreply.github.com>

…idPattern.test.ts Co-authored-by: Hans Pagel <hanspagel@users.noreply.github.com>

…owNotFlows.test.ts Co-authored-by: Hans Pagel <hanspagel@users.noreply.github.com>

luke-hagar-sp added 5 commits October 24, 2025 16:56

correcting schema shapes

8715775

improved error transformations

29e31bc

better error filtering

011f2aa

improved validation flow with more meaningful results

3819844

correcting tests and test data

0eb7ade

luke-hagar-sp requested review from amritk, geoffgscott, hanspagel and marclave as code owners October 24, 2025 22:14

This comment was marked as outdated.

Sign in to view

Merge branch 'main' into validator-overhaul

1aca12c

This comment was marked as outdated.

Sign in to view

luke-hagar-sp and others added 5 commits October 27, 2025 10:15

fix(transform-errors): removed dead code, added a log for the "unreco…

a243abe

…verable" error

Merge branch 'main' into validator-overhaul

21b6d58

refactor(betterAjvErrors): fix silently dropped errors

faa28e7

Merge branch 'main' into validator-overhaul

5115bcc

Merge branch 'main' into validator-overhaul

e4f0333

This comment was marked as outdated.

Sign in to view

Merge branch 'main' into validator-overhaul

b4e6ba7

Merge branch 'main' into validator-overhaul

aef8c5f

marclave reviewed Oct 30, 2025

View reviewed changes

luke-hagar-sp added 2 commits October 30, 2025 18:46

Merge branch 'main' into validator-overhaul

c9a193e

Merge branch 'main' into validator-overhaul

189c433

hanspagel changed the title ~~feat: huge validator overhaul~~ feat(openapi-parser): validator overhaul Nov 3, 2025

hanspagel requested changes Nov 3, 2025

View reviewed changes

Update packages/openapi-parser/tests/openapi3-examples/3.0/fail/inval…

445f893

…idSchemaName.test.ts Co-authored-by: Hans Pagel <hanspagel@users.noreply.github.com>

luke-hagar-sp and others added 2 commits November 3, 2025 09:21

Update packages/openapi-parser/tests/openapi3-examples/3.0/fail/inval…

ab9b20e

…idPattern.test.ts Co-authored-by: Hans Pagel <hanspagel@users.noreply.github.com>

Update packages/openapi-parser/tests/openapi3-examples/3.0/fail/hasFl…

bb56d7e

…owNotFlows.test.ts Co-authored-by: Hans Pagel <hanspagel@users.noreply.github.com>

		errors: transformErrors(entrypoint, validateSchema.errors),
		errors: transformErrors(specification, validateSchema.errors),

feat(openapi-parser): validator overhaul #7171

Are you sure you want to change the base?

feat(openapi-parser): validator overhaul #7171

Uh oh!

Conversation

luke-hagar-sp commented Oct 24, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

luke-hagar-sp commented Oct 28, 2025

Uh oh!

marclave left a comment

Choose a reason for hiding this comment

Uh oh!

amritk commented Oct 30, 2025

Uh oh!

hanspagel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hanspagel Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

LukeHagar Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hanspagel Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

LukeHagar commented Nov 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

luke-hagar-sp commented Oct 24, 2025 •

edited by cursor bot

Loading

changeset-bot bot commented Oct 24, 2025 •

edited

Loading