[3.6 M3] Draft v4 compatible Json Schema validation

• Jira: https://www.mulesoft.org/jira/browse/MULE-7919
• Forum discussion: pending

Motivation / Context

Json schema draft v4 is out (http://json-schema.org/) but Mule currently only provides partial support for draft v3 (plus the library we're currently using for performing that validation has important bugs).

The current support for json schema validation is done in the form of a filter:

<json:json-schema-validation-filter schemaLocations="match-schema.json"/>

We don't want to build on top of this element because:

• From a XSD point of view it extends the xml schema validation filter, reason why it inherits attributes like resourceResolver-ref, errorHandler-ref, returnResult, etc. Those attributes make no sense in the context of json schema validation
• That filter accepts both a json schema and an XSD. If an XSD is provided, then the json is transformed to XML and then validated against the XSD. It is confused to offered the users this option, specially since there're capabilities mismatches between these two options.
• A filter is not the most proper solution since it doesn't provide feedback.

Uses cases

• As a developer, I want to validate json using both draft 3 and draf 4 json schemas
• As a developer, I want to get feedback in case the validation fails
• As a developer, I also want to be able to use this validator as a filter in the cases that I don't care about feedback

Behaviour

The current filter will maintain its current behavior but will be deprecated.

A new element will be created according to the following sintax:

<json:validate-schema schemaLocation="http://my.site/schemas/fstab.json" dereferencing="CANONICAL|INLINE">
	<json:schema-redirects>
		<json:schema-redirect from="http://my.site/schemas/fstab.json#" to="resource:/org/mule/json/examples/fstab.json#" />
	</json:schema-redirects>
</json:validate-schema>	

The above element will look for a json in the payload and will validate it agains 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.

Processor attributes

schemaLocation (required)

A 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:

<json:validate-schema schemaLocation="http://my.site/schemas/fstab.json" />

• These two examples gets the schema from a local resource:

<json:validate-schema schemaLocation="fstab.json" />
<json:validate-schema schemaLocation="resource://fstab.json" />

dereferencing (optional)

Draft v4 defines two dereferencing modes: canonical and inline. Canonical will be the default option but INLINE can also be specified

schema-redirect (optional)

Because we support referencing the schema from the internet and because scheams might reference each other, we'll also support URI redirection for the schemas so that they don't necesarily got out to the internet:

<json:validate-schema schemaLocation="http://my.site/schemas/fstab.json">
	<json:schema-redirects>
		<json:schema-redirect from="http://my.site/schemas/fstab.json#" to="resource:/org/mule/json/examples/fstab.json#" />
	</json:schema-redirects>
</json:validate-schema>	

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

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

Using as filter

Because this element deprecates json-schema-validation-filter, there should be a way to easily use it as a filter even though we don't want this element to contain filtering semmantics. To do so, we'll also introduce a new type of filter to be used with elements which throw exception when a validation fails:

<exception-filter>
	<json:validate-schema schemaLocation="someSchema.json" dereferencing="CANONICAL|INLINE" />
</exception-filter>

This filter will reject the message if the inner chain throws exception, which in this particular case, is equivalent to reject the message if the json does not conform the schema

Dependencies

To perform the validation we will use the json-schema-validator project by fge (https://github.com/fge/json-schema-validator). This is by far the most robust and mature open source validator available for the Java platform and it's the only one actually referenced at http://json-schema.org/implementations.html

This library is the latest version of org.kitchen-eel:json-schema-validator which we currently use at the deprecated filter (it changed package and group names but it's the same project). It is safe to use this new library at the deprecated filter as well since from a behavior point of view it's backwards compatible in terms of draft v3 validation (compatible minus the bugs that is).

Using this library requires additional transitive dependency upgrades:

• joda-time will be upgraded to version 2.5
• com.fasterxml.jackson.core:jackson-databind will be upgraded to 2.4.3
• org.kitchen-eel:json-schema-validator will be removed

Risks

N/A

Impact

Studio Impact

Studio does not currently support the schema filter so the only impact would be an enhancemet requrest to support this new element

DevKit Impact

No impact

MMC Impact

No impact

CH Impact

No impact

Service Registry Impact

No impact

Migration Impact

• Current filter gets deprecated
• Dependency changes

Documentation Impact

• Update docs reflecting this new feature
• Update docs deprecating the existing filter
• Update training documents