JSON schema validation

The API Gateway can check that JavaScript Object Notation (JSON) messages conform to the format expected by a web service by validating requests against a specified JSON schema. A JSON schema precisely defines the items that constitute an instance of an incoming JSON message. It also specifies their data types to ensure that only appropriate data is allowed through to the web service.

For example, the following simple JSON schema requires that all requests sent to a particular web service use this format:

If a JSON Schema Validation
filter is configured with this JSON schema, and the API Gateway receives an incorrectly formed message, the API Gateway rejects that message.

For example, the following message would pass because it specifies the coordinates correctly as numbers:

{
"latitude":55.22,
"longitude":117.22
}

However, the following message would fail because it specifies the coordinates incorrectly as strings:

{
"latitude":"55.22",
"longitude":"117.22"
}

You can find the JSON Schema Validation
filter in the Content Filtering
category of filters in the Policy Studio. Drag and drop the filter on to the policy where you want to perform JSON schema validation.

Configuration

Name:Enter an appropriate name for this filter to display in a policy.

Select which JSON schema to validate messages with:Select one of the following options:

Use JSON schema file

Click the button on the right, and select a JSON schema to validate incoming messages from the tree in the dialog. To add a schema, right-click the JSON Schemas
node, and select Add Schema
to load the schema from a .json
file. Alternatively, you can configure schemas under the Resources
> JSON Schemas
node in the Policy Studio tree. By default, the API Gateway provides the example JSON schemas available from http://www.json-schema.org.

Select the Use v4 draft validator to validate against draft version 4 of the JSON Schema specification, or select Use v3 draft validator to validate against draft version 3 of the JSON Schema specification. The default is v4.

Use this class

Enter the Java class name used to specify the JSON schema (for example, com.vordel.samples.GeoLocationTest), and enter the name of message attribute to store the created object (for example, my.geo.location).This option enables you to take incoming JSON message data and deserialize it into a Java object.

Example using a Java class

For example, to use a Java class for the geographical schema used in the previous section, perform the following steps:

Place this class in a JAR file, and put it in the API Gatewayext/lib
directory.

In the JSON Schema Validation
filter window, enter com.vordel.samples.GeoLocationTest in the Use this class
field.

Enter my.geo.location in the Store created object in message attribute
field.

At runtime when the JSON message arrives, the API Gateway takes the JSON data and tries to instantiate a new GeoLocationTest
object. If this succeeds, the JSON Schema Validation
filter passes. However, if the object cannot be instantiated, the filter fails because the incoming data does not conform to the JSON schema specified by the annotated class.

Generate a JSON schema using Jython

The API Gateway also provides a Jython script to enable you to generate a JSON schema based on a specified Java annotated class. This script is available in the following directory of your API Gateway installation:

INSTALL_DIR/apigateway/samples/scripts/json/schemagenerator.py

Given an annotated Java .class
file, you can generate a schema from this and output a .json
schema file. This schema can then be imported into the API Gateway schema library and used subsequently for future validations.

For example, using the Java class from the previous section, you can generate the schema as follows: