Validate HTTP requests and responses against an OpenAPI Specification.
The plugin supports Swagger v2 and OpenAPI 3.0.x and 3.1.0 specifications. It uses JSON Schema Draft 4 for Swagger 2.0 and OpenAPI 3.0.x, and JSON Schema Draft 2020-12 for OpenAPI 3.1.0. The JSON Schema version is not configurable.
Starting with Kong Gateway 3.7, the OAS Validation plugin supports the following OpenAPI specification features:
|
Category |
Supported |
Not supported |
|---|---|---|
| Request body |
application/json
|
application/xmlmultipart/form-datatext/plaintext/xml
|
| Response body |
application/json
|
- |
| Request parameters |
pathqueryheadercookie
|
- |
| Schema |
allOfoneOfanyOf
|
- |
| Parameter serialization |
styleexplode
|
- |
Event Hooks are outbound calls from Kong Gateway. With Event Hooks, Kong Gateway can communicate with target services or resources, letting the target know that an event was triggered.
For the OAS Validation plugin, Event Hook events can be enabled when a validation fails for:
To configure an Event Hook for the OAS Validation plugin, you’ll need to pass the following parameters:
|
Event Hook Parameter |
Value |
|---|---|
source
|
oas-validation
|
event
|
validation-failed
|
handler
|
webhook
|
on_change
|
true
|
config.url
|
Your webhook URL |
If validation fails, the webhook URL receives a response with JSON payload, which includes the forwarded IP address, Gateway Service and Consumer information, and the error message.
See the Event Hooks reference for details on how to configure an Event Hook.
By default, when the OAS Validation plugin reports schema violations, it embeds all errors into a single string inside the message field.
This makes it difficult for client applications to parse, display, or log validation failures in a structured way.
The following settings control how validation errors are reported:
|
Parameter |
Default |
Description |
|---|---|---|
structured_errors v3.15+
|
false
|
Enable structured_errors to receive validation errors as an errors array instead of a flat string, following JSON Schema draft 2020-12 Output Structure. Each error includes instanceLocation (the path in the request or response body where the violation occurred), keywordLocation (the path in the schema that triggered the error), and error.
Requires verbose_response to be set to true.
When disabled, the plugin preserves the original non-structured error format. |
max_structured_errors v3.15+
|
unset (all errors returned) |
Caps the number of structured validation errors returned in the response. Must be greater than 0. structured_errors must also be enabled. Any extra errors over the cap are discarded.
|
collect_all_errors
|
false
|
Collects all validation errors instead of stopping at the first error.
Only takes effect when structured_errors is disabled.
|
verbose_response
|
false
|
If set to true, returns a detailed error message for invalid requests and responses. Useful while testing.
|