Design and Implementation

Updated 3 July 2026

Implementation Details

Jsonschemapayloadsize sequencediagram

The policy checks whether the request's content type complies with the JSON standard. If not, the policy blocks the call and returns an error message.
If the request payload is empty or null, then the policy blocks the call and returns an error message.
If the payload size exceeds the configured value and fail_safe is null or false, the request returns an error message "Payload Too Large".
If the payload exceeds the configurable value and fail_safe is true, the call proceeds to further processing, and a warning message is captured in the debug log.
The policy checks JSON schema link in Content-Type: application/json;profile="schema-url" or in Link: <schema-url>;rel="describedby" header.
If both headers are present, then the Content-Type schema URL location takes precedence.
If the JSON schema link is not found, the policy blocks the call and returns an error message.
After fetching the schema link from the header, the policy checks the schema details in Memcache using the schema link as the cache key.
If schema details are not found in Memcache, the policy reads them from the schema link and stores them in Memcache. In this case, the schema link serves as the cache key, and the value is the schema details.
After fetching schema details from Memcache or the schema link, the policy validates the incoming JSON request against this schema. If validation fails, the policy blocks the call and returns an error message.
On successful JSON validation, the request policy forwards the request to the backend API server.
In post-processing, after receiving the server response from the backend, the policy repeats the validation process performed for an incoming request.
If the response is not successfully validated against the JSON schema, an error response is sent to the user.
If the response is successfully validated against the JSON schema, then the backend server response is sent to the user.

Business Rules Assumptions

REST API request payload should not be null or empty to validate against the JSON schema.
The following Content Types need to be set for a valid REST API request with JSON payload:
- application/json
- application/json;charset=UTF-8
- application/json; profile=<schema-url>
JSON schema URL should be present either in Content-Type: application/json; profile=schema-url or in Link: <schema-url>; rel="describedby" headers.
If both headers are present, then Content-Type: application/json; profile=schema-url takes precedence.
The max_payload_size must be configured in the PreInput and PostInput values if you want to restrict the request or response, depending on the payload size.
If the fail_safe flag is true, the policy ignores payload size validation (provided it is under max_payload_size (1024 KB)), validates the JSON against the schema, and returns a warning message.

Error Messages

Error Name	HTTP Status Code	Cause
InvalidContentTypeForRequest	400	Request `Content-Type` should be accurate for the JSON standard.
RequestShouldNotBeNull	400	API request payload is null.
RequestShouldNotBeEmpty	400	API request payload is empty.
InvalidPreInputMaxPayloadSize	400	Invalid value for `max_payload_size` in pre-input.
RequestPayLoadTooLarge	413	Request payload size is greater than the configured `max_payload_size`.
MissingJsonSchemaInRequestHeader	400	JSON schema is missing in the request header.
RequestJsonValidationFails	400	JSON request validation fails.
InvalidContentTypeForResponse	400	Response `Content-Type` should be accurate for the JSON standard.
ResponseShouldNotBeNull	400	API response payload is null.
ResponseShouldNotBeEmpty	400	API response payload is empty.
InvalidPostInputMaxPayloadSize	400	Invalid value for `max_payload_size` in post-input.
ResponsePayLoadTooLarge	413	Response payload size is greater than the configured `max_payload_size`.
MissingJsonSchemaInResponseHeader	400	JSON schema is missing in the response header.
ResponseJsonValidationFails	400	JSON response validation fails.