Category: WSO2

JSON Data Services Using WSO2 DSS

NOTE: The following approach is only needed until DSS 3.0.0, after DSS 3.0.0, JSON support works without any special content types.

JSON is a popular data format used frequently because of its simplicity and ease of use. WSO2 DSS has built-in support for querying data using JSON. When sending an HTTP request to a data service endpoint, the server identifies the format of the data, i.e. SOAP, JSON etc.., using the “Content-Type” HTTP header. Below contains the content types for some of the well-known formats:

  • text/xml – SOAP
  • application/xml – POX
  • application/json – JSON (mapped notation)
  • application/json/badgerfish – JSON (badgerfish notation)

Here, the two JSON notations represents how the JSON <-> XML conversion happens, this is because, internally in data services, we deal with handling XML element/attributes and namespaces. The “mapped” notation does not support namespaces, only “badgerfish” does. So when using data services, we should use the content type “application/json/badgerfish”. A quick reference on translating XML to badgerfish JSON can be found here [1].

So now for  a small demo, if we deploy the “RDBMSSample” [2] which ships with WSO2 DSS, we will get an HTTP endpoint “http://localhost:9763/services/RDBMSSample/&#8221;. So now we can send an HTTP request to this EPR with a JSON payload. We can use the “curl” tool for this. Below shows a sample run of this.

$ curl --data '{"employeesbynumber":{"employeenumber":{"$":"1002"}}}' http://localhost:9763/services/RDBMSSample --header Content-Type:"application/json/badgerfish" --header SOAPAction:"urn:employeesByNumber"

In the request, we see that, we set the “Content-Type” header to “application/json/badgerfish”, and also we set another HTTP header called “SOAPAction” to “urn:employeesByNumber”, this is basically passed in as the SOAP action to the internal SOAP engine to resolve the operation of the service, and this can be found in the service WSDL. This must be passed here because, the service EPR itself, does not provide any clue about the service operation, it only identifies the service, so the SOAPAction must be provided for the service dispatch to happen properly. The SOAPAction can be omitted, if we mention the service operation in the EPR itself. Then the service endpoint URL should be changed to “http://localhost:9763/services/RDBMSSample/employeesByNumber&#8221;. Below contains a sample run with this configuration.

$ curl --data '{"employeesbynumber":{"employeenumber":{"$":"1002"}}}' http://localhost:9763/services/RDBMSSample/employeesByNumber --header Content-Type:"application/json/badgerfish"




In WSO2 DSS, while we have the option of using several in-built input validators, we also have the facility of writing our own custom validators. This is done by simply implementing the Java interface “org.wso2.carbon.dataservices.core.validation.Validator”, which can be found in the core data services jar, namely “org.wso2.carbon.dataservices.core-x.y.z.jar”.

Below contains the definition of the Validator interface.

public interface Validator {
    public void validate(ValidationContext context, String name,
            ParamValue value) throws ValidationException;

So here, we are presented with several parameters. Below contains the usage.

  • context : This is the “validation context”, which means, you get access to the environment the validation is taken place. This is essentially giving access to the other variables in the input
  • name : The name of the validating parameter
  • value : The value of the validating parameter

I will be showing a simple example on how to write a custom validator and data service which uses it.

The validator is based on the sample H2 database that ships with WSO2 DSS, so you wont have to worry about creating a database. Here, the Employee table will be used to insert records and to validate it. The validation criteria is as follows,

  1. If both first/last name are not there, email must be there
  2. Only one of the first/last name cannot be given, both must be given, or neither
  3. If both first/last names and email are there, then email should be in a specific format, email = lowercase(first four letters of last name + first letter of first name) +

The Java code for org.acme.EmployeeEmailValidator class can be found at

The data service “AddEmployeeDS.dbs” definition can be found at

You will have to compile the “” file and create a jar file out of it. When doing the compile, point your build path to “/wso2dataservices-x.y.z/repository/components/plugins/org.wso2.carbon.dataservices.core-x.y.z.jar”. So after building and creating the jar file, copy it to “/wso2dataservices-x.y.z/repository/components/lib”, and restart the server. After that, you can upload the “AddEmployeeDS.dbs” data service and use the try-it tool to play around with it, and test the different validation scenarios.