Reading Time: 9 minutes

Sometimes you’re expecting a JSON, specially when publishing or consuming a REST API. But you need to make sure it’s a good JSON, not the kind of JSON that would kill you with a machete. Since the Javascript Object Notation format (JSON for short) can be used to described pretty much anything, validating that the one you received actually complies with what you expected is no simple task. Or at least it wasn’t until the JSON schema specification came out. Just like XSD schemas are XML documents used to describe how a valid XML looks like, a JSON schema is a JSON document used to make sure that yours doesn’t come with a machete. You gotta love the recursion of it!

Mule already supports version 3 of the JSON schema validation through a filter component called <JSON:JSON-schema-validation-filter />. Version 4 is out now and starting with Mule 3.6 we’re adding support for it. However, we decided not to add that new functionality to the existing filter. You see, although filtering when schema is not met can be useful in some scenarios, we realized that most of the time, you actually want to raise a meaningful error that explains exactly why the validation failed. Because the purpose of Filters is to silently discard invalid messages, this can’t be achieved in a natural way using the existing filter (for more background on Mule Filters »).

All hail the Validator!

latest report
Learn why we are the Leaders in API management and iPaaS
Read reports

Long story short, in Mule 3.6 we’re deprecating <JSON:JSON-schema-validation-filter /> and introducing a new element to replace it (the old filter will stick around until Mule 4.0 though). In its simpler form, the new element looks like this:

The validator will look for a JSON in the current message payload and will validate it against the given schema. If the validation is successful then control is passed to the next processor in the chain. Otherwise a JsonSchemaValidationException is thrown containing validation feedback on the message. This exception will not only contain a message with a detailed explanation of what went wrong, it also has a property called “invalidJSON” in which the invalid payload is available on its String representation.

GOTCHA: If you’re trapping that exception with Java, you can get the invalidJSON property by using the getInvalidJSON() method. If you’re doing it with MEL (most likely inside a exception strategy block, then you can simply do e.invalidJSON)

Unlike its deprecated predecessor, this validator can handle both v4 and v3 schemas so that you can use its new goodies without being required to migrate to the new schema specification.

The simple snippet above shows a layout that’s useful and simple enough most of the times, but there’s a lot more you can do with it:

Let’s take a look at what this all means:

schemaLocation

This is the only required parameter in the validator. It points to the location in which the JSON schema is present. It allows both local and external resources. For example, all of the following are valid:

  • This example gets the schema from the internet directly:
  • These two examples get the schema from a local resource in the classpath:

dereferencing

Draft v4 defines two dereferencing modes: canonical and inline. Canonical will be the default option but INLINE can also be specified. When validating a v3 draft this attribute is ignored.

schema-redirect

Because we support referencing the schema from the internet and because schemas might reference each other, it also supports URI redirection for the schemas so that they don’t necessarily got out to the internet:

Accepted payload types

This validator will accept the input JSON to be expressed on any of the following formats:

  • String
  • java.io.Reader
  • InputStream
  • byte[]
  • com.fasterxml.jackson.databind.JSONNode
  • org.mule.module.JSON.JSONData

If the payload is not any of these types, then it will try to transform whatever the payload to a usable type in the following order:

  • org.mule.module.JSON.JSONData
  • com.fasterxml.jackson.databind.JSONNode
  • String

If the payload could not be transformed to any of these types then a JsonSchemaValidationException will also be thrown, although this time the message won’t contain information about the schema validation but an explanation about how the message payload couldn’t be transformed to a type that can be used in validation and therefore it couldn’t be performed. Also, since a JSON document could not be extracted, the invalidJSON property will be null on that exception.

Notice that cases in which validating the JSON requires consuming a streaming resource (InputStream, Reader, etc), the message payload will be changed to the fully consumed JSON.

Takeaways

  • The old schema validation filter is deprecated in favor of this new validator.
  • The validator supports v3 and v4 of the JSON schema specification.
  • The validator also adds cool features like URI redirection.
  • We recommend you to replace the old filter with the new validator in your applications. However do notice that this is not a filter. It will throw an exception if validation fails.
  • For more information in v4 of the JSON schema spec, please follow this link »:

That’s all folks, hope you enjoyed it!