Skip to content

Commit

Permalink
fix: Request Validator incorrectly refers to Kong format schema (#8111)
Browse files Browse the repository at this point in the history 
* fix mention of Kong schema vs json schema; clean up page

* Apply suggestions from code review
  • Loading branch information
@lena-larionova
lena-larionova authored Nov 25, 2024
1 parent 6be9ab5 commit ffed1fd
Showing 1 changed file with 34 additions and 106 deletions.
140 changes: 34 additions & 106 deletions app/_hub/kong-inc/request-validator/overview/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
nav_title: Overview
---

Validate requests before they reach their upstream service. Supports validating
Validate requests before they reach their upstream service. This plugin 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.

## Content-Type Validation
## Content-Type validation

The request Content-Type header is validated against the plugin's [`allowed_content_types`](/hub/kong-inc/request-validator/configuration/#config-allowed_content_types) setting. If the request Content-Type is not listed, the request will be rejected with an HTTP/400 error: `{"message":"specified Content-Type is not allowed"}`

Expand All @@ -15,7 +15,7 @@ The parameter is strictly validated, which means a request with a parameter (for
{:.important}
> When setting this configuration, the `Content-Type` header only gets validated when `body_schema` is configured.
## Body Validation
## Body validation

{% if_version lte:3.5.x %}
Request body validation is only performed for requests with `application/json` Content-Type.
Expand All @@ -30,7 +30,7 @@ For requests with any other allowed Content-Type, body validation is skipped. In

### Overview

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

{% navtabs %}
Expand Down Expand Up @@ -70,7 +70,7 @@ 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
### Schema definition

*For using the JSON Schema Draft 4-compliant validator, see the [JSON Schema website](
https://json-schema.org/) for details on the format and examples. The rest of
Expand All @@ -97,7 +97,7 @@ Map:

Example string-boolean map:

```
```json
{
"type": "map",
"keys": {
Expand All @@ -117,7 +117,7 @@ Array:

Example integer array schema:

```
```json
{
"type": "array",
"elements": {
Expand All @@ -134,7 +134,7 @@ Record:

Example record schema:

```
```json
{
"type": "record",
"fields": [
Expand Down Expand Up @@ -184,7 +184,7 @@ validations:

**Note**: To learn more, see [Lua patterns][lua-patterns].

#### Semantic validation for `format` attribute
#### Semantic validation for the JSON Schema `format` attribute

{:.important}
> This feature is only supported in JSON Schema Draft 4.
Expand All @@ -205,16 +205,16 @@ external specifications. The following attributes are available:

Example `date` schema:

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

### Kong Schema Example
### JSON Schema example

```
```json
[
{
"name": {
Expand Down Expand Up @@ -260,7 +260,7 @@ Example `date` schema:

Such a schema would validate the following request body:

```
```json
{
"name": "Gruce The Great",
"age": 4,
Expand All @@ -273,14 +273,14 @@ Such a schema would validate the following request body:
```

### Parameter Schema Definition
### Parameter schema definition

You can setup definitions for each parameter based on the OpenAPI Specification and
You can set up 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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameter-object)
or the [OpenAPI examples](https://swagger.io/docs/specification/serialization/).

#### Fixed Fields
#### Fixed fields

|Field Name | Type | Description|
| --- | --- | --- |
Expand All @@ -295,107 +295,31 @@ or the [OpenAPI examples](https://swagger.io/docs/specification/serialization/).

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

1. Add a Service to Kong:
1. Add a service to Kong:

```
```sh
curl -i -X POST http://localhost:8001/services \
--data name=httpbin \
--data url=https://httpbin.konghq.com
HTTP/1.1 201 Created
..
{
"host":"httpbin.konghq.com",
"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](/gateway/latest/how-kong-works/routing-traffic/#capturing-groups):
2. Add a route with [named capture group](/gateway/latest/how-kong-works/routing-traffic/#capturing-groups):

```
```sh
curl -i -X POST http://localhost: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:

```
```sh
curl -i -X POST http://localhost: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`:
Content of the file `parameter_schema.json`:

```json
{
Expand All @@ -419,13 +343,17 @@ In this example, use the plugin to validate a request's path parameter.

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:
For example, if you try to send a request to an existing route with the path `/status/abc`:

```
```sh
curl -i -X POST \
--url http://localhost:8000/status/abc \
--header 'Content-Type: application/json' \
--data '{ "name": "foo" }'
```

The proxy request is blocked because the path has a non-numerical status code, which doesn't conform to the schema:
```
HTTP/1.1 400 Bad Request
...
Expand All @@ -434,19 +362,19 @@ In this example, use the plugin to validate a request's path parameter.

A proxy request with a numeric status code is allowed:

```
```sh
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
...
```

Response:
```
HTTP/1.1 200 OK
```

### Further References
### Further references

The Kong schema validation format is based on the plugin schemas.
For more information, see the Kong plugin docs on
Expand Down

0 comments on commit ffed1fd

Please sign in to comment.