djv

Dynamic JSON-Schema Validator

Official Documentation

Current package supports JSON-Schema v6 and v4. It contains utils to validate objects against schemas.
This is a part of djv packages aimed to work with json-schema.

- djv validate object against schemas
- djvi instantiate objects by schema definition
- jvu utilities for declarative, FP usage
- @djv/draft-04 environment updates to support draft-04

Any contributions are welcome. Check the contribution guide.
Since version 1.2.0 djv package supports draft-06. Version 2.0.0 makes draft-06 the default schema version. To use other versions check the environment section.

Table of contents

* djv
* Table of contents
* Install
* Usage
* API
* Environment
* addSchema
* validate
* removeSchema
* resolve
* export
* import
* addFormat
* setErrorHandler
* useVersion
* Tests
* References

Install

``bash
npm install djv
`

or

`html

`

There are 2 versions of validator

- ./lib/djv.js a default one, not uglified and not transpiled
- ./djv.js a built one with a webpack, babel and uglify (preferable for frontend)

Usage

`javascript
const env = new djv();
const jsonSchema = {
"common": {
"properties": {
"type": {
"enum": ["common"]
}
},
"required": [
"type"
]
}
};

// Use addSchema to add json-schema
env.addSchema('test', jsonSchema);
env.validate('test#/common', { type: 'common' });
// => undefined

env.validate('test#/common', { type: 'custom' });
// => 'required: data'
`

API

$3

To instantiate djv environment

`javascript
const djv = require('djv');
const env = djv({
version: 'draft-06', // use json-schema draft-06
formats: { /.../ }, // custom formats @see #addFormat
errorHandler: () => { /.../ }, // custom error handler, @see #setErrorHandler
});
`

To use a previous version of JSON-Schema draft, use a draft-04 plugin, specified in optionalDependencies of djv package.

`javascript
const env = new djv({ version: 'draft-04' });
`

$3

Add a schema to a current djv environment,

`javascript
env.addSchema('test', jsonSchema);
/* => {
fn: function f0(data){...}
name: 'test'
schema: ...
} */
`

$3

Check if object is valid against the schema

`javascript
env.validate('test#/common', { type: 'common' });
// => undefined

env.validate('test#/common', { type: 'custom' });
// => 'required: data'
`

where

name* - schema path in current environment
object* - object to validate
error* - undefined if it is valid

$3

Remove a schema or the whole structure from the djv environment

`javascript
env.removeSchema('test');
`

$3

Resolve the name by existing environment

`javascript
env.resolve('test');
// => { name: 'test', schema: {} }, fn: ... }
`

$3

Export the whole structure object from environment or resolved by a given name

`javascript
env.export();
// => { test: { name: 'test', schema: {}, ... } }
`

where state is an internal structure or only resolved schema object

$3

Import all found structure objects to internal environment structure

`javascript
env.import(config);
`

$3

Add formatter to djv environment. When a string is passed it is interpreted as an expression which when returns true goes with an error, when returns false then a property is valid. When a function is passed it will be executed during schema compilation with a current schema and template helper arguments.

`javascript
env.addFormat('UpperCase', '%s !== %s.toUpperCase()');
// or
env.addFormat('isOk', function(schema, tpl){
return !${schema.isOk};
});
env.validate('ok', 'valid') // => undefined if schema contains isOk property
`

$3

Specify custom error handler which will be used in generated functions when problem found.
The function should return a string expression, which will be executed when generated validator function is executed. The simplist use case is the default one @see template/defaultErrorHandler
`javascript
function defaultErrorHandler(errorType) {
return return "${errorType}: ${tpl.data}";;
}
`
It returns an expression 'return ...', so the output is an error string.

`javascript
djv({ errorHandler: () => 'return { error: true };' }) // => returns an object
djv({
errorHandler(type) {
return errors.push({
type: '${type}',
schema: '${this.schema[this.schema.length - 1]}',
data: '${this.data[this.data.length - 1]}'
});;
}
});
`
When a custom error handler is used, the template body function adds a error variable inside a generated validator, which can be used to put error information. errorType is always passed to error handler function. Some validate utilities put extra argument, like f.e. currently processed property value. Inside the handler context is a templater instance, which contains this.schema, this.data paths arrays to identify validator position.
@see test/index/setErrorHandler for more examples

$3

To customize environment provide a configure function which will update configuration for djv instance.

`javascript
env.useVersion('draft-04')
// or
env.useVersion('custom', configure)
`

Configure will get internal properties as an argument. Check the @korzio/djv-draft-04 code.

`javascript
exposed = {
properties,
keywords,
validators,
formats,
keys,
transformation,
}
`

!Important Modifying them will affect all djv instances in an application.

Tests

`
npm test
``

References

* JSON-Schema Specification
* JSON-Schema Benchmark