XML Schema and JSON Schema Validation in Mule 4

Exposing an API to be consumed by client applications entails a lot of challenges. Apart from a good API definition and documentation, you also need to ensure that the request payload submitted to your API endpoints are valid and conforms to the expected data structure.

Although it is not required, I think some of the advantages to validate a request payload are:

1. Establish a service contract which is a form of agreement between the service provider and the service consumer. This means that, in order to successfully consume an API, a client application needs to strictly follow a specification "for the request payload" called a data schema.
   
   
2. Establish data integrity which ensures that all incoming data submitted to the API are "in a format that is expected". It doesn't make sense to process malformed data. For instance, if you are inserting data to a relational database, it would be more beneficial to first check mandatory (or required) fields before processing the data. It will be a waste of computing power to process invalid data.
   
   
3. Invalid data don't need to be re-processed, such as during a retry mechanism wherein the downstream system is down (or offline). This is especially useful if you're using persistent queues; you just have to discard the bad data right away.
   
   
4. Error reporting in case of bad data. Some client applications make mistakes or typo errors in creating the payload. You don't want many client applications to report to you all the validation errors. A detailed error response itself will suffice for them to figure out the mistake and correct the validation errors on their own.
   

Some of the disadvantages I can think of are:

1. It might be time-consuming to maintain a data schema and may require proper API versioning and backward compatibility.
   
   
2. You are not free to spontaneously extend your payload, especially JSON which is really designed to be an extensible data structure. You may have to consider a few factors before validating a JSON payload if it is really worth it, such as if you are using a NoSQL database.

Why use XML and JSON Schema? You may wonder why, because I know you can also define data types in the RAML.

1. You may have an existing XML or JSON schema files.
   
   
2. At times the data definition is still a work in progress, and you don't want to share the data definitions to your client applications right away.
   
   
3. You may want to leverage certain features that are available in XML and JSON schemas, such as facets, min/ max values, regular expressions, etc. (which may or may not be available in RAML or OAS data types - I need to find out more).

So, XML and JSON schema validation in Mule 4 is really quite impressively easy. You just need to use the XML and JSON modules, and reference the XSD file for XML Schema and the JSON file for the JSON Schema. 

Note: Make sure to add the files in your src/main/resources/schemas project directory. Also I found some weird bug for JSON Validation. You should use a forward slash (/) for your schema path, else you will get a weird error.

How about Error Handling?

 As I mentioned earlier, a good API design should have self-reporting and self-documenting errors especially for data validation errors, so that client applications can figure out the issue on their own. To do this we can simply use On Error Propagate error handler which handles either of the following error types: XML-MODULE:SCHEMA_NOT_HONOURED or JSON:SCHEMA_NOT_HONOURED.

Then, you can have the following DataWeave script to return the error payload. Well, it's up to you how the error structure would look like. But the cool thing here is that, aside from the error description, the XML Validation also returns the specific lineNumber and columnNumber in your XML payload pointing to the exact location of the error. JSON Validation just returns the error message, though.

Here is an example of a Bad Request error response for the XML validation:

If you want to see a sample project, you can check my GitHub page here:

https://github.com/ralph-palomar/xml-json-data-validation-mule4

Feel free to comment or ask questions on this post. :)