[TT-16410] add OAS 3.1 validation

[pvormste]

This pull request improves OpenAPI 3.1 (OAS 3.1) support by ensuring that JSON Schema 2020-12 validation is automatically enabled for OAS 3.1+ documents, and adds comprehensive tests for various OAS 3.1 null and nullable type scenarios. It also updates dependencies to use the latest internal fork of kin-openapi and adds a new version of the jsonschema library.

OAS 3.1 Validation Improvements:

• The Validate method in oas.go now automatically enables JSON Schema 2020-12 validation for OAS 3.1+ documents, ensuring correct validation behavior for new schema features.

Enhanced Test Coverage:

• Added a new test file oas_31_test.go with a suite of tests covering OAS 3.1 features, especially handling of null types and the interplay between type: ["null", ...] and the deprecated nullable: true syntax.
• Introduced helper functions in oas_test.go to simplify the creation of OAS documents and test scenarios, improving test maintainability and readability.

Dependency Updates:

• Updated the kin-openapi dependency to a new internal fork version to support improved OAS 3.1 validation.
• Added github.com/santhosh-tekuri/jsonschema/v6 as an indirect dependency, preparing for advanced JSON Schema validation features.

Ticket Details

TT-16410

Status	In Code Review
Summary	OAS 3.1: Implement document validation for OAS 3.1

Generated at: 2026-01-30 15:31:23

[probelabs]

This pull request enhances OpenAPI 3.1 (OAS 3.1) support by automatically enabling JSON Schema 2020-12 validation for OAS 3.1+ documents. This ensures that modern schema features, such as using null as a type, are correctly validated. The implementation updates the kin-openapi dependency to a newer internal fork and adds the jsonschema/v6 library to support this functionality.

A comprehensive test suite has been added to verify the new validation behavior, focusing on null type handling and its interplay with the deprecated nullable keyword. Additionally, new test helper functions have been introduced to improve the readability and maintainability of the tests.

Files Changed Analysis

• apidef/oas/oas.go: The core logic is modified in the Validate method to conditionally add the openapi3.EnableJSONSchema2020Validation() option for documents with version 3.1.0 or newer.
• apidef/oas/oas_31_test.go: A new test file containing a thorough suite of tests for various OAS 3.1 null and nullable type scenarios.
• apidef/oas/oas_test.go: Updated with new helper functions (createBaseOAS, addPostOperationWithRequestBodySchema, etc.) to simplify the creation of OAS documents for testing.
• go.mod & go.sum: These files are updated to replace the kin-openapi dependency with a newer version from a private fork and to add the new github.com/santhosh-tekuri/jsonschema/v6 dependency.

Architecture & Impact Assessment

• What this PR accomplishes: It aligns the gateway's validation capabilities with the OAS 3.1 specification, allowing developers to use modern JSON Schema features in their API definitions and ensuring correct validation behavior.
• Key technical changes introduced: The primary change is the conditional logic in OAS.Validate that injects a new validation option for OAS 3.1+ documents. This is supported by updating the forked kin-openapi dependency which contains the necessary functionality.
• Affected system components: This change affects the API definition validation component. Any system process that loads and validates an OpenAPI definition will be impacted, including the gateway's API loading/reloading mechanism and API imports via the Dashboard or Management API.

graph TD
    A[Start Validation] --> B{Is OAS 3.1+?};
    B -- Yes --> C[Add JSON Schema 2020-12 Option];
    B -- No --> D[Use Default Options];
    C --> E[Validate Document];
    D --> E;

Loading

Scope Discovery & Context Expansion

• The changes are centered in the apidef/oas package, but the impact extends to all parts of the system that rely on this package for OAS validation, including the Tyk Gateway and Dashboard.
• To fully assess the impact, one could search the codebase for all usages of the (s *OAS) Validate method to identify all entry points for API validation. Investigating the changes in the TykTechnologies/kin-openapi fork would also provide deeper context on the underlying implementation that enables this feature.

Metadata

• Review Effort: 3 / 5
• Primary Label: enhancement

---

Powered by Visor from Probelabs

Last updated: 2026-01-30T15:32:50.704Z | Triggered by: pr_updated | Commit: d864582

💡 TIP: You can chat with Visor using /visor ask <your question>

[github-actions]

API Changes

--- prev.txt	2026-01-30 15:32:27.583096556 +0000
+++ current.txt	2026-01-30 15:32:17.145912832 +0000
@@ -3960,8 +3960,9 @@
 
 func (s *OAS) Validate(ctx context.Context, opts ...openapi3.ValidationOption) error
     Validate validates OAS document by calling openapi3.T.Validate() function.
-    In addition, it validates Security Requirement section and it's requirements
-    by calling OAS.validateSecurity() function.
+    For OAS 3.1+ documents, JSON Schema 2020-12 validation is automatically
+    enabled. In addition, it validates Security Requirement section and its
+    requirements by calling OAS.validateSecurity() function.
 
 type OAuth struct {
 	// Enabled activates the OAuth middleware.

[probelabs]

Security Issues (1)

Severity	Location	Issue
🟡 Warning	go.mod:573	The `kin-openapi` dependency is a fork based on an outdated version (v0.92.0) that is vulnerable to CVE-2023-22462, a Denial of Service vulnerability. The upstream fix is in v0.113.0. Maintaining an old fork of a security-critical library is a significant risk, making it difficult to apply security patches and increasing maintenance overhead. 💡 Suggestion Rebase the fork on a recent, non-vulnerable version of the upstream `kin-openapi` library (>= v0.113.0), or migrate away from the fork entirely and use the official release. This will ensure all upstream security fixes are included.

✅ Architecture Check Passed

No architecture issues found – changes LGTM.

Performance Issues (1)

Severity	Location	Issue
🟡 Warning	apidef/oas/oas.go:546-551	A new slice is allocated for validation options on every call to `Validate` for an OAS 3.1+ document. This allocation is unnecessary in the common case where no additional options are passed by the caller, as demonstrated by the new tests. 💡 Suggestion To optimize, handle the case where `opts` is empty separately. A pre-allocated, package-level slice can be used to avoid allocations in this common path. The current logic of creating a new slice should be kept for the `else` branch (when `opts` is not empty) to correctly avoid modifying the caller's slice.

Quality Issues (2)

Severity	Location	Issue
🟢 Info	apidef/oas/oas_31_test.go:11	The comment `// These tests will initially fail as OAS 3.1 validation is not yet fully implemented` is outdated now that the implementation is complete. It should be removed to avoid confusion. 💡 Suggestion Remove the outdated comment line.
🟡 Warning	apidef/oas/oas_31_test.go:12	The test suite for OAS 3.1 validation is missing negative test cases. All added tests verify that valid schemas are accepted, but there are no tests to confirm that a schema that is invalid under JSON Schema 2020-12 rules is correctly rejected. This makes it difficult to confirm that the new validator is fully active and effective beyond simply allowing `type: "null"`. 💡 Suggestion Add at least one test case with a schema that is intentionally invalid according to JSON Schema 2020-12 (e.g., by misusing a new keyword like `prefixItems` or `unevaluatedProperties`) and assert that `oas.Validate` returns an error. This will provide stronger confidence that the intended validation is being enforced.

---

Powered by Visor from Probelabs

Last updated: 2026-01-30T15:32:57.516Z | Triggered by: pr_updated | Commit: d864582

💡 TIP: You can chat with Visor using /visor ask <your question>

[pvormste]

Regarding visor:

• The CVE fix has been cherry-picked into the fork some time ago

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
2 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud