Validate requests against an API schema

Attach one OpenAPI 3.0 or 3.1 document to a WAF policy to check requests on the routes it reaches: operations, path/query/header parameters, request content types and JSON bodies. Upload JSON or YAML. Swagger 2.0 and OpenAPI 3.2 are not supported.

How violations become decisions

Validation adds SchemaViolation fields to the normal request inspection stages. Each field has a violation kind as its name and a JSON pointer as its value. Rules in clearplane-api-schema, or your own custom rules, assign scores. Policy mode, ruleset mode, scoring mode, paranoia levels, disabled rules and exclusions apply as usual.

Unknown query parameters are flagged. Unknown headers are allowed because browsers and proxies add headers. Use additionalProperties: false on JSON objects that should reject extra properties, such as fields that could otherwise enable mass assignment.

JSON bodies use the schema declared for their matching application/json or +json media type. OpenAPI request schemas honor readOnly properties when determining required input; writeOnly properties remain valid request fields.

Upload a document

Open Firewall → WAF policies, edit a policy, and use API schema to select and upload a file. You need WAF policies: Write. Policies defined by container labels cannot attach or remove documents. The upload is a separate operation from saving other policy fields. Give an API its own Route policy: a document on the Global policy applies to every route that inherits it.

A successful upload displays the original document hash, format, upload time and operation count. Upload another file to replace it, or remove the attached document to stop schema validation. Failed uploads retain the selected file for correction or retry and preserve the previous schema.

References must stay inside the document's components. External URLs and files are refused, and the compiler performs no network resolution. Recursive references, dynamic references, custom schema identifiers and unsupported parameter serialization are refused with an upload error. Path/header arrays use comma-separated values; query arrays use repeated parameters. Object parameters and non-default serialization styles are not supported.

Start in Detection

Use Detection while comparing normal application traffic with the document. Review schema findings, correct the document or apply narrow exclusions, and then consider Prevention.

Attaching a document does not by itself block traffic. An active ruleset must score SchemaViolation, and its score must reach the policy's blocking threshold. The dashboard warns when an enabled route's policy has a schema but no active ruleset contains schema-violation rules.

The handshake or request metadata can be checked for WebSocket and gRPC requests. Their streamed messages are inspected by the corresponding WAF protocol support; this feature does not treat those messages as OpenAPI JSON request bodies.

Limits

If validation cannot finish within its limits, the WAF emits ParserFact named schema-validation-limit-exceeded and continues normal inspection. That fact and any completed violations remain available to scoring rules. An incomplete validation is not a clean result.

Pattern matching uses bounded non-backtracking regexes; unsupported constructs such as lookarounds and backreferences are rejected during compilation.

The SchemaViolation target and schema validation facts are part of the rule language; attaching a schema supplies facts for active rules to score.