Skip to navigation

Validator plugin

The Validator plugin checks fields of the request, or of the upstream’s response, against a list of rules. A rule set fails when any rule fails. On a failure, the plugin denies the request, adds a marker header, or only logs. Validator is a Preview plugin.

On an Enterprise data plane, Validator needs the OPA policy sidecar (opa.enabled in the Helm chart), and the data plane must allow Preview plugins with the global.plugins.allow_preview: true gateway setting, which is off by default. The Helm chart has no value for this setting. For more information, see Helm values.

Where it runs

ProtocolsRequest rules: all. Response rules: HTTP routes only, for responses that aren’t streamed and are at most 1 MiB.
Scope kindsglobal, service, route. The API also accepts consumer, but the console doesn’t offer it.
PhaseRequest and response

Configuration

rules
array of objects

The rules to check.

rules[].field
stringRequired

The field to check, for example request.method, request.path, request.header.<name>, request.query.<name>, request.body.<path>, response.status, or response.body.<path>. A field that starts with response. is a response rule.

rules[].op
stringRequired

One of exists, absent, eq, neq, one_of, matches, glob, prefix, suffix, contains, gt, gte, lt, lte, between, len_lte, len_gte, format.

rules[].value
string, number, or boolean

The operand for a single value. format takes uuid or email. A matches pattern can be up to 4,096 characters.

rules[].values
array

The operands for a rule that needs more than one value. between needs two values.

rules[].message
string

A note stored with the rule. It isn’t returned to the client, which gets a generic validation_failed error.

rules[].view
stringDefaults to upstream

For response rules only: check the upstream’s response (upstream) or the response sent to the client after response plugins ran (client).

on_fail
stringDefaults to deny

deny refuses the request. mark adds a marker header and continues.

fail_on_validate
booleanDefaults to true

Set to false for audit mode, which logs failures but never acts on them.

deny_status
numberDefaults to 422

The status for a request-phase denial, and for a response-phase denial unless response_deny_status is set.

response_deny_status
numberDefaults to 502

The status for a response-phase denial.

mark_header
stringDefaults to X-Fabric-Validation

The marker header that mark adds.

mark_value
stringDefaults to failed

The value of the marker header.

On MCP routes, a denial is a JSON-RPC error with HTTP 200.

Example

{
"name": "orders-validation",
"plugin_id": "validator",
"scope": { "kind": "route", "name": "orders-api" },
"config": {
"rules": [
{ "field": "request.header.x-request-id", "op": "format", "value": "uuid" },
{ "field": "request.body.quantity", "op": "between", "values": [1, 100] }
],
"on_fail": "deny"
}
}