Themis is a blazing fast, compiled JSON Schema v4 validator. Themis was created for use in environments where there is a large amount of data that has to be validated against the same schema multiple times. Eg: REST API Servers.
Themis (Greek: Θέμις) is an ancient Greek Titaness, the goddess of divine order, law, natural law and custom, and a prophetic goddess — the divine voice who first instructed mankind in the primal laws of justice and morality.
Themis was inspired by the z-schema and json-model validators and tries to provide the best of both worlds. Many thanks to Martin Zagora for his work on z-schema 3 from which most of the validation logic was adapted.
Installation
npm install themis
Example
Validating a single schema
var Themis = require('themis');var schema = {
"id": "basicSchema",
"type": "array",
"items": {
"title": "Product",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "number"
},
"name": {
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
},
"dimensions": {
"type": "object",
"properties": {
"length": {"type": "number"},
"width": {"type": "number"},
"height": {"type": "number"}
},
"required": ["length", "width", "height"]
},
"warehouseLocation": {
"description": "Coordinates of the warehouse with the product"
Themis allows you to create custom validation keywords. This can be useful in a number of scenarios where the keywords provided by the json-schema specification are just not enough.
At present custom validator must by sync. To create a custom validator you must specify three pieces of information.
When will the validation be applied ?
You can specify when the validation must be applied by providing an array containing two parameters to the order key:
The relative position (before or after)
An existing validation keyword
Themis performs all its validations in a specific order for optimization reasons. Hence you must ensure that you correctly specify the order in which your validation must be performed relative to others.
The current ordering of validation is as follows
default
$schema
$ref
title
description
definitions
type
multipleOf
minimum
exclusiveMinimum
maximum
exclusiveMaximum
minLength
maxLength
pattern
format
additionalItems
items
minItems
maxItems
uniqueItems
required
additionalProperties
patternProperties
properties
minProperties
maxProperties
dependencies
allOf
anyOf
oneOf
not
enum
What type of data type can the validation be applied to ?
The validators in Themis are grouped together by the type of data they are applied to. You must specify the type in the type key:
The allowed values are:
string
number
array
object
any
The generated code which will actually perform the validation
Themis generates a validation function for each schema. Hence your validation function must return an array of code statements which will be compiled into the final validation function.
The validation function generator will receive the following arguments:
schema - The schema document
path - The path to the schema
schema_id - The id of the schema
options - The options object passed in when creating the validator
The compiled validation function will have access to the following variable which it can use to perform the validation:
data - The actual json data that is being validated
parent - The parent object/array of the data. This could be null if no parent exists.
report - The report object on which any errors can be attached and whose valid key must be set to reflect the result of the validation.
Applying default values
The default keyword is an extremely useful but often unimplemented feature in most json validators. Even the ones that implement it make a half hearted attempt at doing it properly. Themis hopes to change this trend. Themis tries its best to implement complete support for the default keyword including handling its usage in complex scenarios with anyOf, allOf, oneOf, items, additionalItems and not. You can even assign default values to array items.
This allows a lot of potentially complex behaviours using your validator. You can check the tests for all the different cases that are supported.
To use this functionality in your validator you must set the enable_defaults value to true in the options object when creating the validator.
Themis applies the default values using a rollback mechanism. This allows us to rollback any changes we have performed on the original data in case we later find out that the data does not pass validation by the schema. This allows us to handle the messy anyOf, allOf, oneOf scenarios. At present the way themis applies defaults for each keyword is as follows:
allOf - All the default values for all schemas are applied. If the data is invalid nothing is applied.
oneOf - Exactly one set of default values are applied. If the data is invalid nothing is applied.
anyOf - The default values of the first schema which successfully validates the data is applied. If the data is invalid then nothing is applied. The order of validation of schemas is the same as the order in which it is specified in the schema document.
not - None of the default values are ever applied.
items - Default values are applied to an item if it equals undefined. If the data is invalid nothing is applied.
additionalItems - All additional items whose value equals undefined get assigned the default value. If the data is invalid then nothing is applied.
Methods
The Themis object contains methods to create validators and register formats.
validator(schemas, options)
Generate a new compiled validator from the provided schemas. The returned validator function can be reused any number of times. Check the examples above to see its usage.
The available options are:
enable_defaults (default: false) - Allow the validator to apply default values. Enabling this imposes a significant performance overhead as can the seen in the benchmark results.
registerFormat(format, validation_func)
Register a new format and its associated validation function.
Register a new validation generator. Check out the example given above to see usage.
Performance
Themis achieves its high performance by generating custom optimized validation functions for every json schema document provided to it. For most types of data Themis is atleast 5-10 times faster than Z-Schema 3 and atleast twice as fast as json-model.
Basic Object Validation-----------------------z-schema#basicObject x 15,421 ops/sec ±7.07% (56 runs sampled)jayschema#basicObject x 205 ops/sec ±6.95% (59 runs sampled)jjv#basicObject x 3,385 ops/sec ±5.43% (56 runs sampled)jsonschema#basicObject x 388 ops/sec ±5.11% (59 runs sampled)tv4#basicObject x 9,746 ops/sec ±2.81% (70 runs sampled)json-model#basicObject x 29,009 ops/sec ±7.28% (69 runs sampled)themis#basicObject x 96,757 ops/sec ±2.80% (55 runs sampled)Fastest is themis#basicObjectAdvanced Object Validation--------------------------z-schema#advancedObject x 2,704 ops/sec ±8.09% (60 runs sampled)jayschema#advancedObject x 24.79 ops/sec ±5.88% (35 runs sampled)jjv#advancedObject x 933 ops/sec ±6.32% (57 runs sampled)jsonschema#advancedObject x 90.19 ops/sec ±6.21% (53 runs sampled)tv4#advancedObject x 148 ops/sec ±8.47% (64 runs sampled)json-model#advancedObject x 3,730 ops/sec ±2.04% (65 runs sampled)themis#advancedObject x 10,173 ops/sec ±3.04% (65 runs sampled)Fastest is themis#advancedObject
For a more detailed analysis of performance check out the benchmarks against the other popular json schema validators available today.