Validate HTTP requests and responses against an OpenAPI Specification.
The plugin supports Swagger v2 and OpenAPI 3.0.x and 3.1.0 specifications with a JSON Schema validator that supports Draft 2019-09.
OAS Validation
Enterprise only
Related Documentation
Made by
Kong Inc.
Minimum Version
Kong Gateway - 3.1
Tags
Related Resources
Supported OpenAPI 3.1.0 specification features
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
|
- |
Using Event Hooks with OAS Validation
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:
- All request parameters, including: URI, header, query parameters, and request body
- The response body from the upstream service
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.
Error handling
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.
|
FAQs
How can I prevent the OAS Validation plugin from validating the ETag header with the If-Match header?
If a request contains the If-Match request header, the OAS Validation plugin follows RFC 2616 to validate the Etag response header.
If you don’t want the plugin to validate the Etag with the If-Match request header,
send the If-Match header with a wildcard (*) to skip validation.
For example:
curl http://localhost:8000/example-route \
-H 'If-Match:*'