Validate JSON Request Against JSON Schema in Mule 4

JSON (JavaScript Object Notation) is a  type of data format that is widely used in modern technology to interchange data. Validating a JSON schema ensures that the data complies with a predefined structure or schema, which is essential for ensuring data integrity and compatibility between different systems.

Before We Start, Let's Understand What JSON Schema Is

JSON schema is a specification that is written in JSON format. It defines a set of keywords that allow you to express various constraints and formats for JSON data. 

These keywords are used to specify the allowed data types, minimum and maximum values, patterns for string values, and other rules. It serves as a blueprint that defines the expected properties, data types, and constraints for JSON documents. 

JSON schema is particularly useful for ensuring data consistency, compatibility, and data quality in systems that exchange JSON data.

Use Case: JSON Schema Validation

JSON Payload

{
	"Status": true,
	"message": "Response from demo-validation-sapi app",
	"number": 1234
}

For this tutorial, we will pass the above payload with a POST request to the /json endpoint and validate it using a JSON schema. 

I have created a demo project with /json endpoint and /xml endpoint for JSON and XML validation, respectively. In this tutorial, we will use the /json endpoint.

For JSON validation, we will use "json-validation-flow" with /json endpoint. Before configuring the validation module, if we make a call to /json endpoint with the above JSON payload, it gives a 200 status code.

Steps To Validate the Payload Against JSON Schema

Step 1: Add the JSON module in the studio from Anypoint Exchange.

Verify whether the JSON module has been added or not.

Step 2: Prepare the JSON schema. For creating the JSON schema, you can use any free online JSON to JSON schema generator tool available. (For this tutorial, I have used - liquid-technology.)

In the schema generator, add the payload and generate the schema.

Generated Schema for the above JSON payload:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Status": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "number": {
      "type": "integer"
    }
  },
  "required": [
    "Status",
    "message",
    "number"
  ]
}

Step 3: In the project's "src/main/resources" folder, create a folder with the name "schemas" (or any name you prefer). Create a file with the name "json-schema.json" inside the "schemas" folder.

Note: Make sure that the file type of json schema is ".json".

Step 4: Copy and paste the generated JSON schema to the "json-schema.json" file.

Step 5: Add the JSON "Validate schema" processor before the "Transform Message" (or any other processor which needs the validated JSON data). 

Configure the JSON schema path in the "Validate schema" processor.

Step 6: In the "Error handling" section, add an "On Error Propagate" scope and set the type to "JSON:SCHEMA_NOT_HONOURED" error type.

Step 7: Add the "httpStatus" variable and error message in the error handler. (In this tutorial, I have set the "httpStatus" to 400 for error response).

Step 8: Set the "httpStatus" variable in HTTP Listener as "Status code" in the "Responses" section.

Step 9: Deploy the project and send a valid request to the/json endpoint. We should get a successful response with a status code of 200.

Now make some changes to the request payload. We should get an error response with a status code of 400. (Here, I changed the "message" field to "messages").

Step 10: At this point, if we pass any extra fields in the JSON request body, it will allow the extra field to pass.

Note: In the above screenshot, the "id" field is extra, we did not define the "id" field in the JSON schema, but still, the request was successful.

If we want to restrict the extra fields that are not defined in the schema, we have to add "additionalProperties": false" to the schema.

Step 11: Save the schema and redeploy the app. Now make a call to the /json endpoint with extra fields in the request payload. It should return an error message with 400 as the status code.

This way, we can validate a JSON request payload against a JSON schema.

For more information about the Mule JSON module, refer to the MuleSoft documentation here.

You can get the source code of the above application here.

I hope you find this tutorial helpful.