validate-request

The internal:validate-request interceptor validates incoming request bodies against a JSON Schema. It uses the schema from your OpenAPI spec’s requestBody automatically, or an explicit schema from options.

Registration

actions:
  - target: "$.paths['/items'].post"
    update:
      x-plenum-interceptor:
        - module: "internal:validate-request"
          hook: on_request
          function: validateRequest

Hook

Hook	Function	Can short-circuit
`on_request`	`validateRequest`	Yes

The on_request hook is required so the full request body is available for validation.

Options

Field	Type	Default	Description
`schema`	`object`	—	JSON Schema to validate against. If not set, reads from the operation’s `requestBody.content.application/json.schema`.

When options.schema is provided, it takes precedence over the spec schema.

Schema resolution

If no options.schema is given, the interceptor resolves the schema from:

operation.requestBody.content["application/json"].schema

This includes $ref references to components/schemas in the spec.

Behaviour

Skips validation if the request body is null, undefined, or an empty string.
Parses string bodies as JSON. Returns 400 if parsing fails.
Uses AJV with draft-07 support.
Validators are cached per schema (keyed by JSON.stringify(schema)) for performance.
Returns { action: "continue" } if validation passes.

Error response

On validation failure, returns 400 with a structured error body:

{
  "type": "request-validation-error",
  "title": "Request Validation Failed",
  "status": 400,
  "errors": [
    {
      "path": "/name",
      "message": "must be string"
    }
  ]
}

The errors array maps to AJV’s standard error output, with instancePath as the path and message as the error description.

Example

# Valid request — passes validation
curl -X POST http://localhost:6188/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Widget", "quantity": 5}'
# => 201

# Missing required field — rejected by gateway
curl -X POST http://localhost:6188/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Widget"}'
# => 400 {"type":"request-validation-error",...}

Overriding the schema

x-plenum-interceptor:
  - module: "internal:validate-request"
    hook: on_request
    function: validateRequest
    options:
      schema:
        type: object
        properties:
          name:
            type: string
          quantity:
            type: integer
        required:
          - name
          - quantity