[ySnoopyDogy]

While using the lib, I notice that the document validation is not strict enough. The OpenAPI spec does not allow to have path parameters defined that diverge from the path templates of an operation.

I checked against the kin-openapi, and their lib correctly validate the document that do not include the correct path templates:

go run cmd/validate/main.go example.json 
2026/10/02 13:32:22 Validation error: invalid paths: operation GET /users/{userIds}/posts must define exactly all path parameters (missing: [userId userIds])
exit status 1

To make the libopenapi-validator more strict following the OpenAPI spec without adding a breaking change, there is a new option called ValidateDocumentPathParams, with its function WithPathParameterDocumentValidation to enable the config.

With this config, we run another validation just to catch the missing and extra path parameters.

All tests pass, and the new ones ensure that the stricter path checking is working as intended.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.67%. Comparing base (d7a43ec) to head (1baab9f).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #329      +/-   ##
==========================================
+ Coverage   98.66%   98.67%   +0.01%     
==========================================
  Files          94       95       +1     
  Lines       12310    12423     +113     
==========================================
+ Hits        12146    12259     +113     
  Misses        139      139              
  Partials       25       25              

Flag	Coverage Δ
unittests	98.67% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[daveshanley]

Thanks for adding this. The opt-in approach makes sense, and the full test suite passes at ef761b3. There is one correctness issue we need to fix before merging.

In schema_validation/validate_document.go, the new check only runs when BuildV3Model() returns no error. If model building reports an error, we silently skip path validation and can return valid=true with no validation errors.

I reproduced this with /pets/{petId} and a GET operation that has no petId parameter:

• Add an unrelated schema with $ref: '#/components/schemas/DoesNotExist': document validation passes, even with the new option enabled.
• Add a Node object schema with a required child property referencing #/components/schemas/Node: the first validation call passes, but a second call on the same document fails with the missing path parameter error.

Both cases also reproduce with this change applied to current main.

Please make these changes:

1. Separate model availability from the model-building error. When a usable model is returned, run the path checks even if the build also reports an error, such as a circular-reference diagnostic.
2. Handle a failed model build explicitly. If the model is unavailable and the requested check cannot run, return a structured validation error with the cause. We must not report successful validation when the check was skipped.
3. Add regression tests for the two cases above, including repeated calls on the same document. The missing parameter must be rejected on the first and subsequent calls. Keep the existing test that proves this remains disabled by default.
4. Update against current main and rerun the full tests, lint, and coverage.

The existing checks are green, but they don't cover this failure path yet. Thanks for working on this — let's close that gap before it goes in :)

[ySnoopyDogy]

Good catch!

Now the validation runs even if building the model returns some errors.

If the model can't be built, an explicit error is returned.

I'm ignoring the build error when the model is still available, because ValidateDocument never checked whether BuildV3Model returned errors. If you think it makes sense to also return a validation error when the build returns an error, even though the model is available, just let me know and I'll adjust it.

[daveshanley]

Please make model initialization safe for concurrent calls. BuildV3Model mutates the shared document without synchronization: eight concurrent ValidateOpenAPIDocument calls fail under -race with this option enabled; the same test passes without it. Add a regression test for concurrent validation of the same document.

[ySnoopyDogy]

Sorry for the delay, I was on vacation. I’ve just pushed a new commit with that

[daveshanley]

Thanks for fixing the concurrent validation case. I found two remaining edge cases and a small diagnostic-order issue.

[daveshanley]

Could we scope this lock to each document? A slow BuildV3Model call currently blocks validation of every other document using this option. I reproduced this with two separate documents. Please keep the same-document race test and add a test that unrelated documents can proceed independently.

[daveshanley]

Could we limit this exemption to an actually empty Path Item? /pets/{id} with only a summary currently passes without an id parameter. The OpenAPI exemption applies to empty items. A test for a summary-only item alongside the existing {} case would cover this.

[daveshanley]

Could we emit these errors in path order, or sort the names first? Map iteration changes the error order between runs; I saw four orders for the same document. Please apply the same ordering to the branch below so reports stay stable.