Request Validator plugin

Validate requests before they reach their upstream Service. Supports validating the schema of the body and the parameters of the request using either Kong’s own schema validator (body only) or a JSON Schema Draft 4-compliant validator.

Configuration Reference

Example plugin configuration

Enable on a service

Enable on a route

Enable on a consumer

Enable globally

The following examples provide some typical configurations for enabling the request-validator plugin on a service.

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Kong Manager

Make the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=request-validator"  \
    --data "config.body_schema=[{"name":{"type": "string", "required": true}}]" \
    --data "config.version=kong"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-validator-example>
config: 
  body_schema: [{"name":{"type": "string", "required": true}}]
  version: kong
plugin: request-validator

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <request-validator-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

Add this section to your declarative configuration file:

plugins:
- name: request-validator
  service: {SERVICE}
  config: 
    body_schema: [{"name":{"type": "string", "required": true}}]
    version: kong

SERVICE is the id or name of the service that this plugin configuration will target.

In Konnect Cloud, select the service on the ServiceHub page.
Scroll down to Versions and select the version.
Scroll down to Plugins and click New Plugin.
Find and select the Request Validator plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Body Schema: [{"name":{"type": "string", "required": true}}]
- Config.Version: kong
Click Create.

In Kong Manager, select the workspace.
From the Dashboard, scroll down to Services and click View for the service row.
Scroll down to plugins and click Add Plugin.
Find and select the Request Validator plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Scoped.
Add the service name and ID to the Service field if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Body Schema: [{"name":{"type": "string", "required": true}}]
- Config.Version: kong
Click Create.

The following examples provide some typical configurations for enabling the request-validator plugin on a route.

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Kong Manager

Make the following request:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=request-validator"  \
    --data "config.body_schema=[{"name":{"type": "string", "required": true}}]" \
    --data "config.version=kong"

ROUTE is the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-validator-example>
config: 
  body_schema: [{"name":{"type": "string", "required": true}}]
  version: kong
plugin: request-validator

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <request-validator-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

ROUTE is the id or name of the route that this plugin configuration will target.

Add this section to your declarative configuration file:

plugins:
- name: request-validator
  route: <route>
  config: 
    body_schema: [{"name":{"type": "string", "required": true}}]
    version: kong

ROUTE is the id or name of the route that this plugin configuration will target.

In Konnect Cloud, select the service from the ServiceHub page.
Scroll down to Versions and select the version.
Select the route.
Scroll down to Plugins and click Add Plugin.
Find and select the Request Validator plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Body Schema: [{"name":{"type": "string", "required": true}}]
- Config.Version: kong
Click Create.

In Kong Manager, select the workspace.
From the Dashboard, select Routes in the left navigation.
Click View for the route row.
Scroll down to plugins and click Add Plugin.
Find and select the Request Validator plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Scoped.
Add the Route ID if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Body Schema: [{"name":{"type": "string", "required": true}}]
- Config.Version: kong
Click Create.

The following examples provide some typical configurations for enabling the request-validator plugin on a consumer.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

Make the following request:

$ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
    --data "name=request-validator"  \
    --data "config.body_schema=[{"name":{"type": "string", "required": true}}]" \
    --data "config.version=kong"

CONSUMER is the id or username of the consumer that this plugin configuration will target.

You can combine consumer.id, service.id, or route.id in the same request, to further narrow the scope of the plugin.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-validator-example>
config: 
  body_schema: [{"name":{"type": "string", "required": true}}]
  version: kong
plugin: request-validator

Then, apply it to a consumer by annotating the KongConsumer resource as follows:

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: {CONSUMER}
  annotations:
    konghq.com/plugins: <request-validator-example>
    kubernetes.io/ingress.class: kong

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any Service, Consumer, or Route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

Add this section to your declarative configuration file:

plugins:
- name: request-validator
  consumer: {CONSUMER}
  config: 
    body_schema: [{"name":{"type": "string", "required": true}}]
    version: kong

CONSUMER is the id or username of the consumer that this plugin configuration will target.

In Kong Manager, select the workspace.
From the Dashboard, scroll down to Consumers and click View for the consumer row.
Select the Plugins tab.
Click Add Plugin.
Find and select the Request Validator plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Global.
Enter the following parameters, updating the default or sample values as needed:
- Config.Body Schema: [{"name":{"type": "string", "required": true}}]
- Config.Version: kong
Click Create.

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

The following examples provide some typical configurations for enabling the request-validator plugin globally.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

Make the following request:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=request-validator"  \
    --data "config.body_schema=[{"name":{"type": "string", "required": true}}]" \
    --data "config.version=kong"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-request-validator>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  body_schema: [{"name":{"type": "string", "required": true}}]
  version: kong
plugin: request-validator

Add a plugins entry in the declarative configuration file:

plugins:
- name: request-validator
  config: 
    body_schema: [{"name":{"type": "string", "required": true}}]
    version: kong

In Kong Manager, select the workspace.
From the Dashboard, select Plugins in the left navigation.
Click New Plugin.
Find and select the Request Validator plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, set the plugin scope to Global.
Enter the following parameters, updating the default/sample values as needed:
- Config.Body Schema: [{"name":{"type": "string", "required": true}}]
- Config.Version: kong
Click Create.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter	Description
`name` required Type: string	The name of the plugin, in this case `request-validator`.
`service.id` Type: string	The ID of the Service the plugin targets.
`route.id` Type: string	The ID of the Route the plugin targets.
`consumer.id` Type: string	The ID of the Consumer the plugin targets.
`enabled` required Type: boolean Default value: `true`	Whether this plugin will be applied.
`config.body_schema` required	Array of schema fields
`config.allowed_content_types` optional Default value: `application/json`	List of allowed content types. Note: Body validation is only done for `application/json` and skipped for any other allowed content types.
`config.version` required Default value: `kong`	What validator to use. Supported values are `kong` (default) for using Kong’s own schema validator, or `draft4` for using a JSON Schema Draft 4-compliant validator.
`config.parameter_schema` optional	Array of parameter validator specifications

Examples

Overview

By applying the plugin to a Service, all requests to that Service will be validated before being proxied.

With a database

Without a database

Use a request like this:

curl -i -X POST http://kong:8001/services/{service}/plugins \
  --data "name=request-validator" \
  --data "config.version=kong" \
  --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]'

Add the following entry to the plugins: section in the declarative configuration file:

plugins:
- name: request-validator
  service: {service}
  config:
    version: kong
    body_schema:
      name:
        type: string
        required: true

In this example, the request body data would have to be valid JSON and conform to the schema specified in body_schema - i.e., it would be required to contain a name field only, which needs to be a string.

In case the validation fails, a 400 Bad Request will be returned as the response.

Schema Definition

For using the JSON Schema Draft 4-compliant validator, see the JSON Schema website for details on the format and examples. The rest of this paragraph will explain the Kong schema.

The config.body_schema field expects a JSON array with the definition of each field expected to be in the request body; for example:

Each field definition contains the following attributes:

Attribute	Required	Description
`type`	yes	The expected type for the field
`required`	no	Whether or not the field is required

Additionally, specific types may have their own required fields:

Map:

Attribute	Required	Description
`keys`	yes	The schema for the map keys
`values`	yes	The schema for the map values

Example string-boolean map:

{
  "type": "map",
  "keys": {
    "type": "string"
  },
  "values": {
    "type": "boolean"
  }
}

Array:

Attribute	Required	Description
`elements`	yes	The array’s elements schema

Example integer array schema:

{
  "type": "array",
  "elements": {
    "type": "integer"
  }
}

Record:

Attribute	Required	Description
`fields`	yes	The record schema

Example record schema:

{
  "type": "record",
  "fields": [
    {
      "street": {
        "type": "string",
      }
    },
    {
      "zipcode": {
        "type": "string",
      }
    }
  ]
}

The type field assumes one the following values:

string
number
integer
boolean
map
array
record

Each field specification may also contain “validators”, which perform specific validations:

Validator	Applies to	Description
`between`	Integers	Whether the value is between two integer. Specified as an array; e.g., `{1, 10}`
`len_eq`	Arrays, Maps, Strings	Whether an array’s length is a given value
`len_min`	Arrays, Maps, Strings	Whether an array’s length is at least a given value
`len_max`	Arrays, Maps, strings	Whether an array’s length is at most a given value
`match`	Strings	True if the value matches a given Lua pattern **
`not_match`	String	True if the value doesn’t match a given Lua pattern **
`match_all`	Arrays	True if all strings in the array match the specified Lua pattern **
`match_none`	Arrays	True if none of the strings in the array match the specified Lua pattern **
`match_any`	Arrays	True if any one of the strings in the array matches the specified Lua pattern **
`starts_with`	Strings	True if the string value starts with the specified substring
`one_of`	Strings, Numbers, Integers	True if the string field value matches one of the specified values
`timestamp`	Integers	True if the field value is a valid timestamp
`uuid`	Strings	True if the string is a valud UUID

Note: To learn more, see Lua patterns.

Kong Schema Example

[
  {
    "name": {
      "type": "string",
      "required": true
    }
  },
  {
    "age": {
        "type": "integer",
        "required": true
      }
  },
  {
    "address": {
      "type": "record",
      "required": true,
      "fields": [
        {
          "street": {
            "type": "string",
            "required": true
          }
        },
        {
          "zipcode": {
            "type": "string",
            "required": true
          }
        }
      ]
    }
  }
]

Such a schema would validate the following request body:

{
  "name": "Gruce The Great",
  "age": 4,
  "address": {
    "street": "251 Post St.",
    "zipcode": "94108"
  }
}

Parameter Schema Definition

You can setup definitions for each parameter based on the OpenAPI Specification and the plugin will validate each parameter against it. For more information see the OpenAPI specification or the OpenAPI examples.

Fixed Fields

Field Name	Type	Description
name	`string`	REQUIRED. The name of the parameter. Parameter names are case sensitive, and corresponds to the parameter name used by the `in` property. If `in` is `"path"`, the `name` field MUST correspond to the named capture group from the configured `route`.
in	`string`	REQUIRED. The location of the parameter. Possible values are `query`, `header`, or `path`.
required	`boolean`	REQUIRED Determines whether this parameter is mandatory.
style	`string`	REQUIRED when schema and explode are set Describes how the parameter value will be serialized depending on the type of the parameter value.
schema	`string`	REQUIRED when style and explode are set The schema defining the type used for the parameter. It is validated using `draft4` for JSONschema draft 4 compliant validator.
explode	`boolean`	REQUIRED when schema and style are set When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect.

Examples

In this example we will use the plugin to validate a request’s path parameter.

Add a service to Kong

curl -i -X POST http://kong:8001/services \
  --data name=httpbin \
  --data url=http://httpbin.org

HTTP/1.1 201 Created
..

{
  "host":"httpbin.org",
  "created_at":1563479714,
  "connect_timeout":60000,
  "id":"0a7f3795-bc92-43b5-aada-258113b7c4ed",
  "protocol":"http",
  "name":"httpbin",
  "read_timeout":60000,
  "port":80,
  "path":null,
  "updated_at":1563479714,
  "retries":5,
  "write_timeout":60000
}

Add a route with named capture group

curl -i -X POST http://kong:8001/services/httpbin/routes \
  --data paths="/status/(?<status_code>\d%+)" \
  --data strip_path=false

HTTP/1.1 201 Created
..

{
  "created_at": 1563481399,
  "methods": null,
  "id": "cd78749a-33a3-4bbd-9560-588eaf4116d3",
  "service": {
    "id": "0a7f3795-bc92-43b5-aada-258113b7c4ed"
  },
  "name": null,
  "hosts": null,
  "updated_at": 1563481399,
  "preserve_host": false,
  "regex_priority": 0,
  "paths": [
    "\\/status\\/(?<status_code>\\d+)"
  ],
  "sources": null,
  "destinations": null,
  "snis": null,
  "protocols": [
    "http",
    "https"
  ],
  "strip_path": false
}

Enable request-validator plugin to validate body and parameter

 curl -i -X POST http://kong:8001/services/httpbin/plugins \
   --header "Content-Type: application/json" \
   --data @parameter_schema.json

 HTTP/1.1 201 Created
 ..

 {
   "created_at": 1563483059,
   "config": {
     "body_schema": "{\"name\":{\"type\": \"string\", \"required\": false}}",
     "parameter_schema": [
       {
         "style": "simple",
         "required": true,
         "in": "path",
         "schema": "{\"type\": \"number\"}",
         "explode": false,
         "name": "status_code"
       }
     ],
     "version": "draft4"
   },
   "id": "ad91a2d4-6217-4d34-9133-4a2508ddda9f",
   "service": {
     "id": "0a7f3795-bc92-43b5-aada-258113b7c4ed"
   },
   "enabled": true,
   "run_on": "first",
   "consumer": null,
   "route": null,
   "name": "request-validator"
 }

Content of file parameter_schema.json:

 {
   "name": "request-validator",
   "config": {
     "body_schema": "{\"name\":{\"type\": \"string\", \"required\": false}}",
     "version": "draft4",
     "parameter_schema": [
       {
         "name": "status_code",
         "in": "path",
         "required": true,
         "schema": "{\"type\": \"number\"}",
         "style": "simple",
         "explode": false
       }
     ]
   }
 }

Here validation will make sure status_code is a number.

A proxy request with a non-numerical status code will be blocked

 curl -i -X GET http://kong:8000/status/abc
 HTTP/1.1 400 Bad Request
 ..

 {"message":"request param doesn't conform to schema"}

but it will be allowed with a numeric status code

 curl -i -X GET http://kong:8000/status/200
 HTTP/1.1 200 OK
 X-Kong-Upstream-Latency: 163
 X-Kong-Proxy-Latency: 37
 ..

Further References

See the Kong docs on storing custom entities here.

About this Plugin
Plugin Version	0.36-x
Made by	Kong Inc.
Categories	Traffic Control
Konnect Cloud compatible?	See latest plugin version
Version Compatibility
Kong Gateway 0.36-x 0.35-x