-
Notifications
You must be signed in to change notification settings - Fork 683
[3.6 M3] Draft v4 compatible Json Schema validation
- Jira: https://www.mulesoft.org/jira/browse/MULE-7919
- Forum discussion: pending
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.
- 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
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 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)
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" />Draft v4 defines two dereferencing modes: canonical and inline. Canonical will be the default option but INLINE can also be specified
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> 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 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
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
N/A
Studio does not currently support the schema filter so the only impact would be an enhancemet requrest to support this new element
No impact
No impact
No impact
No impact
- Current filter gets deprecated
- Dependency changes
- Update docs reflecting this new feature
- Update docs deprecating the existing filter
- Update training documents