Validate requests against API schemas

A WAF policy can carry one API schema of each kind, and checks the requests on the routes it reaches against them:

Kind Upload Checks
OpenAPI An OpenAPI 3.0 or 3.1 document in JSON or YAML Every request that is neither gRPC nor sent to a GraphQL endpoint path
Protobuf A binary FileDescriptorSet gRPC and gRPC-Web calls, including application/grpc-web-text
GraphQL A schema in GraphQL SDL, plus its endpoint paths Requests sent to those paths

Once a policy has any schema, a request whose kind has no schema reports unknown-operation. A gRPC call on a policy with only an OpenAPI document is therefore flagged, as is a request to a path outside a GraphQL-only API. CORS preflights (OPTIONS with Origin and Access-Control-Request-Method and no body) are never schema-checked; the route's CORS policy decides them.

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

Kind OpenAPI pointer gRPC pointer GraphQL pointer
unknown-operation /paths/~1admin/get /shop.Catalog/Delete subscription, /query
unknown-parameter /query/debug — query.user(name), $extra
invalid-type /path/id, /body/items/0/price filter.limit query.search(limit), $input.role, /query
missing-required /header/X-Tenant, /body id query.user(id), $input.name
unknown-property /body/customer 9, filter.7 query.user.email
invalid-content-type /requestBody /headers/content-type /headers/content-type
unexpected-message-count — /shop.Catalog/Get —

Upload a schema

Open WAF → WAF policies, edit a policy, and use API schemas to upload, replace or remove one schema of each kind. You need WAF policies: Write. Policies defined by container labels cannot attach or remove schemas. Uploads apply immediately and are separate from saving other policy fields. Give an API its own Route policy: a schema on the Global policy applies to every route that inherits it.

Through the REST API, send PUT /api/waf-policies/{id}/api-schemas/{kind} with the file as base64 content, and DELETE the same path to remove it. kind is openapi, protobuf or graphql. Every file may be up to 4 MiB. A rejected upload returns invalid-api-schema with the reasons and keeps the previous schema.

OpenAPI

Operations, path, query and header parameters, request content types and JSON bodies are checked. Swagger 2.0 and OpenAPI 3.2 are not supported.

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. Request schemas honor readOnly properties when determining required input; writeOnly properties remain valid request fields.

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. Path and header arrays use comma-separated values; query arrays use repeated parameters. Object parameters and non-default serialization styles are not supported. Pattern matching uses bounded non-backtracking regexes; lookarounds and backreferences are rejected.

gRPC

Produce a descriptor set that includes every imported file:

buf build -o api.binpb
protoc --include_imports --descriptor_set_out=api.binpb api.proto

Edge checks the method path against the descriptor and parses each request message against the method's input type: undeclared field numbers, wrong wire types, malformed or truncated messages and missing proto2 required fields are reported. A method that does not stream requests must receive exactly one message. Enum values and UTF-8 in string fields are not checked. Unknown fields are reported even though newer protobuf clients may send them on purpose, so start in Detection and disable the unknown-property rule for the route if your clients run ahead of the schema.

With a descriptor, the ProtobufString and ProtobufBytes fields of a call are named by their declared paths, such as user.email, instead of field numbers, which makes detections and exclusions readable. Exclusions written with field numbers stop matching once a descriptor covers the method.

Standard services are ordinary methods: include grpc.health.v1.Health or grpc.reflection.v1.ServerReflection in the descriptor set if clients call them through Clearplane. application/grpc+json and other non-protobuf gRPC encodings report invalid-content-type. A call blocked by its method path receives 403; a call blocked by a message receives gRPC status 7.

GraphQL

Upload the schema in SDL, which every GraphQL server can export, and name its endpoint paths; without paths, /graphql is used. Paths are compared exactly.

Edge checks GET requests with a query parameter, POST requests with application/json bodies (one request or a batch array) and application/graphql bodies. Undeclared operation types, unknown fields, unknown arguments and variables, literal argument values of the wrong type, missing required arguments and variable values that do not match their declared types are reported, including enums, lists and input objects. A GET without a query, such as a GraphiQL page, reports unknown-operation. Custom scalar values are not checked.

Introspection fields (__schema, __type, __typename) are not schema violations; the clearplane-graphql ruleset scores introspection, query depth, aliases and batch size. GraphQL subscriptions over WebSocket keep the normal message inspection and are not schema-checked.

Start in Detection

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

Attaching a schema 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 whose violation kinds no active rule scores, and names the kinds, for example unexpected-message-count on an older clearplane-api-schema release.

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.

Descriptor sets may define up to 1,024 methods, 4,096 message types and 1,024 fields per message. GraphQL schemas may define up to 4,096 types, 1,024 fields per type and 64 arguments per field, and up to 8 endpoint paths. OpenAPI documents may define up to 1,024 operations. Compiled schemas count against Edge's shared memory budget, shown as API schemas on the Edge memory budget card; a configuration whose schemas do not fit is refused and the previous one keeps serving.

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