Skip to content
|
search
Plugin Hub
header icon

Request Validator

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

This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

  • Setting a target's health status in the load balancer
  • Validating configurations against schemas
  • Uploading the declarative configuration using the /config endpoint

Example plugin configuration

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

Make the following request:

curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
    --data "name=request-validator"  \
    --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]'

Replace SERVICE_NAME|SERVICE_ID with 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}}]'
plugin: request-validator

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

apiVersion: v1
kind: Service
metadata:
  name: SERVICE_NAME|SERVICE_ID
  labels:
    app: SERVICE_NAME|SERVICE_ID
  annotations:
    konghq.com/plugins: request-validator-example
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: SERVICE_NAME|SERVICE_ID
  selector:
    app: SERVICE_NAME|SERVICE_ID

Replace SERVICE_NAME|SERVICE_ID with 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_NAME|SERVICE_ID
  config: 
    body_schema: '[{"name":{"type": "string", "required": true}}]'

Replace SERVICE_NAME|SERVICE_ID with the id or name of the service that this plugin configuration will target.

You can configure this plugin through the Konnect UI.

From the servicehub icon Service Hub, select a service version, then set up the plugin:

  1. In the Plugins section, click Add Plugin.
  2. Find and select the Request Validator plugin.
  3. Click Create.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. From the Services section, click View for the service row.
  3. From the plugin section, click Add Plugin.
  4. 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.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already pre-filled.
  7. Click Create.

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

Make the following request:

curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
  --data "name=request-validator"  \
    --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]'

Replace ROUTE_NAME|ROUTE_ID with 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}}]'
plugin: request-validator

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ROUTE_NAME|ROUTE_ID
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: request-validator-example
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          service:
            name: echo
            port:
              number: 80

Replace ROUTE_NAME|ROUTE_ID with the id or name of the route 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
  route: ROUTE_NAME
  config: 
    body_schema: '[{"name":{"type": "string", "required": true}}]'

Replace ROUTE_NAME|ROUTE_ID with the id or name of the route that this plugin configuration will target.

You can configure this plugin through the Konnect UI.

From the servicehub icon Service Hub, select a service version, then set up the plugin:

  1. Select a route.
  2. In the Plugins section, click Add Plugin.
  3. Find and select the Request Validator plugin.
  4. Click Create.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. Open Routes from the menu, then click View for the route row.
  3. From the plugin section, click Add Plugin.
  4. 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.
  5. If the option is available, select Scoped.
  6. Add the route ID if it is not already prefilled.
  7. Click Create.

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

Make the following request:

curl -X POST http://localhost:8001/consumers/CONSUMER_NAME|CONSUMER_ID/plugins \
  --data "name=request-validator"  \
    --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]'

Replace CONSUMER_NAME|CONSUMER_ID with the id or name 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}}]'
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_NAME|CONSUMER_ID
  annotations:
    konghq.com/plugins: request-validator-example
    kubernetes.io/ingress.class: kong

Replace CONSUMER_NAME|CONSUMER_ID with the id or name 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_NAME|CONSUMER_ID
  config: 
    body_schema: '[{"name":{"type": "string", "required": true}}]'

Replace CONSUMER_NAME|CONSUMER_ID with the id or name of the consumer that this plugin configuration will target.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. From the Consumers section, click View for the consumer row.
  3. Select the Plugins tab, then click Add Plugin.
  4. 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.
  5. If the option is available, select Scoped.
  6. Add the consumer ID if it is not already prefilled.
  7. 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.

Make the following request:

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

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}}]'
plugin: request-validator

Add a plugins entry in the declarative configuration file:

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

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. Open Plugins from the menu, then click New Plugin.
  3. 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.
  4. If the option is available, set the plugin scope to Global.
  5. 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.name or service.id

Type: string		 The name or ID of the service the plugin targets.

Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.

Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins.
route.name or route.id

Type: string		 The name or ID of the route the plugin targets.

Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.

Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins.
consumer.name or consumer.id

Type: string		 The name or ID of the consumer the plugin targets.

Set one of these parameters if adding the plugin to a consumer through the top-level /plugins endpoint.

Not required if using /consumers/CONSUMER_NAME|CONSUMER_ID/plugins.
enabled

Type: boolean

Default value: true		 Whether this plugin will be applied.
config.body_schema
semi-optional

Type: string

The request body schema specification. One of body_schema or parameter_schema must be specified.
config.allowed_content_types
required

Type: Set of string elements

Default value: [“application/json”]

List of allowed content types. The value can be configured with the charset parameter. For example, application/json; charset=UTF-8.
Note: Body validation is only done for application/json and skipped for any other allowed content types. Only one parameter is supported at the most. If a request is sending more than one parameter with the Content-Type header, only the first parameter is evaluated and the rest are truncated. Note that application/json doesn’t match with application/json; charset=UTF-8. The type, subtype, parameter names, and the value of the charset parameter are not case sensitive based on the RFC explanation.
config.version
required

Type: string

Default value: kong

Which 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
semi-optional

Type: Array of record elements

Array of parameter validator specifications. For details and examples, see Parameter Schema Definition. One of body_schema or parameter_schema must be specified.
config.verbose_response
required

Type: boolean

Default value: false

If enabled, the plugin returns more verbose and detailed validation errors (for example, the name of the required field that is missing).

Examples

Overview

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

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 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 integers. Specified as an array; for example, {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 valid UUID

Note: To learn more, see Lua patterns.

Semantic validation for format attribute

Structural validation alone may be insufficient to validate that an instance meets all the requirements of an application. The format keyword is defined to allow interoperable semantic validation for a fixed subset of values that are accurately described by authoritative resources, be they RFCs or other external specifications. The following attributes are available:

Attribute Description
date defined by RFC 3339, sections 5.6 and further validated by 5.7
date-time defined by RFC 3339, sections 5.6
time defined by RFC 3339, sections 5.6 and further validated by 5.7

Note: The value of the format attribute must be a string.

Example date schema:

{
  "type": "string",
  "format": "date"
}

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
          }
        }
      ]
    }
  },
  {
    "born": {
      "type": "string",
      "format": "date-time",
      "required": true
    }
  }
]

Such a schema would validate the following request body:

{
  "name": "Gruce The Great",
  "age": 4,
  "address": {
    "street": "251 Post St.",
    "zipcode": "94108"
  },
  "born": "2009-07-20T08:30:37.012Z"
}

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, use the plugin to validate a request’s path parameter.

  1. 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
}

  2. 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
}

  3. 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": "{\"properties\":{\"name\":{\"type\":\"string\"}},\"required\":[\"name\"]}",
     "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": "{\"properties\":{\"name\":{\"type\":\"string\"}},\"required\":[\"name\"]}",
     "version": "draft4",
     "parameter_schema": [
       {
         "name": "status_code",
         "in": "path",
         "required": true,
         "schema": "{\"type\": \"number\"}",
         "style": "simple",
         "explode": false
       }
     ]
   }
 }

  4. In these step examples, validation ensures that status_code is a number and the body contains a parameter called name.

    A proxy request with a non-numerical status code is blocked:

     curl -i -X POST \
 --url http://localhost:8000/status/abc \
 --header 'Content-Type: application/json' \
 --data '{ "name": "foo" }'
 HTTP/1.1 400 Bad Request
 ...

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

    A proxy request with a numeric status code is allowed:

     curl -i -X POST \
 --url http://localhost:8000/status/123 \
 --header 'Content-Type: application/json' \
 --data '{ "name": "foo" }'
 HTTP/1.1 200 OK
 X-Kong-Upstream-Latency: 163
 X-Kong-Proxy-Latency: 37
 ...

Further References

The Kong schema validation format is based on the plugin schemas. For more information, see the Kong plugin docs on storing custom entities.