JSON schema validation

Contents

Overview
Configuration
Generate a JSON schema using Jython

Overview

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: 

{"description":"A geographical coordinate",
 "type":"object",
 "properties":{
    "latitude":{"type":"number"},
    "longitude":{"type":"number"}
    }
}

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.

For more details on JSON schemas, see http://www.json-schema.org.

Configuration

Configure the following settings:

Name:

Enter an appropriate name for this filter.

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 main Policy Studio tree. By default, the API Gateway provides the example JSON schemas available from http://www.json-schema.org.

  • Use this class

    Enter the Java classname 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.

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

    1. Create the annotated Java class as follows: 

      package com.vordel.samples;
import java.lang.String;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class GeoLocationTest {
    public GeoLocationTest() { }
    public int latitude;
    public int longitude;
}

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

    3. In the JSON Schema Validation filter screen, enter the following classname in the Use this class field: com.vordel.samples.GeoLocationTest.

    4. In the Store created object in message attribute field, enter my.geo.location.

    Now 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/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:

  • Windows 

    run.bat json\schemagenerator.py com.vordel.samples.GeoLocationTest 
MyLocationSchema.json

  • UNIX/Linux 

    sh run.sh json/schemagenerator.py com.vordel.samples.GeoLocationTest 
MyLocationSchema.json

[Note] Note

This script requires that you specify the location of your JAR file. You can do this by setting the JYTHONPATH environment variable, for example:

  • Windows 

    set JYTHONPATH=C:\home\user\mylocation.jar

  • UNIX/Linux 

    export JYTHONPATH=/home/user/mylocation.jar

Alternatively, if you have compiled your classes to /home/user/classes, specify the following: 

export JYTHONPATH=/home/user/classes

For more details on using Jython, see http://www.jython.org/.

Prev  Up  Next
  Home