Request Validator Policy

Related Documentation
Made by
Kong Inc.
Priority
999
Minimum Version
AI Gateway - 2.0

The Request Validator Policy validates incoming requests against a schema you define, and rejects any request that doesn’t conform with a 400 Bad Request response before it reaches the upstream service. Use it to enforce a request shape at the AI Gateway layer instead of relying on the upstream service to reject malformed input itself.

You can validate:

At least one of body_schema or parameter_schema must be set.

How it works

config.version selects which validator evaluates your schema:

  • kong (the default): Kong’s own schema format. See Schema format.
  • draft4, draft6, draft7, draft201909, or draft202012: the matching JSON Schema Draft-compliant validator.

By default, a failed validation returns a generic 400 Bad Request. Enable config.verbose_response to have the response name the specific field that failed instead.

The Policy can restrict which Content-Type values it accepts, using config.allowed_content_types (default application/json). A request with a Content-Type that isn’t in this list is rejected with 400 Bad Request and {"message":"specified Content-Type is not allowed"}, regardless of whether the body itself would otherwise have passed schema validation. Use config.content_type_parameter_validation to control whether Content-Type parameters (like ; charset=UTF-8) are also validated.

Schema format

When config.version is kong (the default), config.body_schema is a JSON-encoded array of single-key field definitions, using Kong’s own schema types rather than plain JSON Schema:

  • array requires an elements sub-schema describing each item’s type.
  • record requires a fields array of single-key {field_name: {type: ...}} objects, describing an object’s shape.
  • map requires keys and values sub-schemas.

See Validate an LLM chat request body for an example that combines array and record.

Example: Validate an LLM chat request body

A common use for this Policy in AI Gateway is enforcing that a chat completion request has the shape an AI Model expects before AI Gateway forwards it upstream. This rejects a malformed request at the gateway instead of letting it fail against the AI Model Provider:

kongctl
policy.yaml
ai_gateway_policies:
  - ref: my-request-validator
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: my-request-validator
    name: my-request-validator
    type: request-validator
    enabled: true
    global: false
    config:
      version: kong
      body_schema: '[{"model":{"type":"string","required":true}},{"messages":{"type":"array","required":true,"elements":{"type":"record","fields":[{"role":{"type":"string","required":true}},{"content":{"type":"string","required":true}}]}}}]'

Make sure to replace the following placeholders with your own values:

  • AI_GATEWAY_ID: The id of your AI Gateway.

This requires the request body to contain both a model field (a string) and a messages field (an array of {role, content} records): the two fields every OpenAI-format chat completion request needs. A request missing either field is rejected with 400 Bad Request before it ever reaches the AI Model’s upstream target. A request with both fields passes through unchanged.

Looking for on-prem configuration? Convert the kongctl configuration to a decK yaml file and use deck file ai2kong. See Configure Kong AI Gateway on-prem for more information.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!