feat: stricter document path validation

[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.29%. Comparing base (b1808fe) to head (d26c829).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #329      +/-   ##
==========================================
+ Coverage   98.27%   98.29%   +0.02%     
==========================================
  Files          80       81       +1     
  Lines        9481     9592     +111     
==========================================
+ Hits         9317     9428     +111     
  Misses        139      139              
  Partials       25       25              

Flag	Coverage Δ
unittests	98.29% <100.00%> (+0.02%)	⬆️

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.