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

Enabling the plugin on a service

1
2
3
4
5
6
$ curl -X POST http://<admin-hostname>:8001/services/<service>/plugins \
    --data "name=request-validator"  \
    --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]' \
    --data "config.allowed_content_types=application/json" \
    --data "config.version=kong" \
    --data "config.verbose_response=false"

1
2
3
4
5
6
7
8
9
10
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-validator-example>
config: 
  body_schema: '[{"name":{"type": "string", "required": true}}]'
  allowed_content_types: application/json
  version: kong
  verbose_response: false
plugin: request-validator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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>

1
2
3
4
5
6
7
8
plugins:
- name: request-validator
  service: <service>
  config: 
    body_schema: '[{"name":{"type": "string", "required": true}}]'
    allowed_content_types: application/json
    version: kong
    verbose_response: false

Enabling the plugin on a route

1
2
3
4
5
6
$ curl -X POST http://<admin-hostname>:8001/routes/<route>/plugins \
    --data "name=request-validator"  \
    --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]' \
    --data "config.allowed_content_types=application/json" \
    --data "config.version=kong" \
    --data "config.verbose_response=false"

1
2
3
4
5
6
7
8
9
10
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-validator-example>
config: 
  body_schema: '[{"name":{"type": "string", "required": true}}]'
  allowed_content_types: application/json
  version: kong
  verbose_response: false
plugin: request-validator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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

1
2
3
4
5
6
7
8
plugins:
- name: request-validator
  route: <route>
  config: 
    body_schema: '[{"name":{"type": "string", "required": true}}]'
    allowed_content_types: application/json
    version: kong
    verbose_response: false

Enabling the plugin on a consumer

1
2
3
4
5
6
$ curl -X POST http://<admin-hostname>:8001/consumers/<consumer>/plugins \
    --data "name=request-validator"  \
    --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]' \
    --data "config.allowed_content_types=application/json" \
    --data "config.version=kong" \
    --data "config.verbose_response=false"

1
2
3
4
5
6
7
8
9
10
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-validator-example>
config: 
  body_schema: '[{"name":{"type": "string", "required": true}}]'
  allowed_content_types: application/json
  version: kong
  verbose_response: false
plugin: request-validator

1
2
3
4
5
6
7
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: <consumer>
  annotations:
    konghq.com/plugins: <request-validator-example>
    kubernetes.io/ingress.class: kong

1
2
3
4
5
6
7
8
plugins:
- name: request-validator
  consumer: <consumer>
  config: 
    body_schema: '[{"name":{"type": "string", "required": true}}]'
    allowed_content_types: application/json
    version: kong
    verbose_response: false

Enabling the plugin globally

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.

1
2
3
4
5
6
$ curl -X POST http://<admin-hostname>:8001/plugins/ \
    --data "name=request-validator"  \
    --data 'config.body_schema=[{"name":{"type": "string", "required": true}}]' \
    --data "config.allowed_content_types=application/json" \
    --data "config.version=kong" \
    --data "config.verbose_response=false"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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}}]'
  allowed_content_types: application/json
  version: kong
  verbose_response: false
plugin: request-validator

1
2
3
4
5
6
7
plugins:
- name: request-validator
  config: 
    body_schema: '[{"name":{"type": "string", "required": true}}]'
    allowed_content_types: application/json
    version: kong
    verbose_response: false

Parameters

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

Examples

Overview

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

1
2
3
4
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}}]'

1
2
3
4
5
6
7
8
9
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:

Additionally, specific types may have their own required fields:

Map:

Example string-boolean map:

1
2
3
4
5
6
7
8
9
{
  "type": "map",
  "keys": {
    "type": "string"
  },
  "values": {
    "type": "boolean"
  }
}

Array:

Example integer array schema:

1
2
3
4
5
6
{
  "type": "array",
  "elements": {
    "type": "integer"
  }
}

Record:

Example record schema:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "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:

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:

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

Example date schema:

1
2
3
4
{
  "type": "string",
  "format": "date"
}

Kong Schema Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[
  {
    "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:

1
2
3
4
5
6
7
8
9
10
{
  "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

Examples

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

1. Add a Service to Kong:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   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:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   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:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
    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:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
    {
      "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
          }
        ]
      }
    }
   

4. In these step examples, validation makes sure that status_code is a number.

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

   1
   2
   3
   4
   5
    curl -i -X GET http://kong:8000/status/abc
    HTTP/1.1 400 Bad Request
    ...
   
    {"message":"request param doesn't conform to schema"}
   

   A proxy request with a numeric status code is allowed:

   1
   2
   3
   4
   5
   6
    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

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