Validating response payloads against additional constraints

Serialization of the HTTP response is one of the final steps in handling a request. Both the response body and response headers need to be serialized, with the response body written to the HttpServletResponse output stream and the response headers turned into Strings that the servlet container is responsible for writing to the response. The system APIs support serialization of a number of different Java object types that can be returned directly from an API handler method, set as the value of the body of a Response object, or added as the value of a header on the Response object.

There are several types of response objects whose serialized format is JSON. This includes JsonObject, JsonWrapper, and TransformResult. By default, a JsonObject or JsonWrapper is validated only against the declared response schema to ensure that all properties on the object are declared in the schema and have the correct data type. TransformResult objects are "implicitly validated", given that the mapping file that produces them must conform to the associated JSON schema.

It is possible to request that the framework also validate a JsonObject, JsonWrapper, or TransformResult against additional constraints defined in the schema, such as minLength, the set of required fields, or any custom validators that have been defined. These additional validations are not done by default because they can potentially be an unnecessary expense in a production situation where the assumption is that the API has been implemented correctly and will only return valid data. It is also possible that the constraints defined in the schema are intended to only apply to inputs, and that the response may violate some of them.

You can use the GW-ValidateResponseHandling header to have the system API validate its responses against the declared schema. To do this, include the header and set its value to true.