json-schema-valid
Please note this library is not ready for production use.
A modular javascript JSON Schema v4 validator.
Suitable for standalone use (see "simple function" mode below), or together with other components to handle dereferencing, correlation, hypermedia, etc. functions.
If you are looking for a (mostly) complete JSON Schema toolkit, see json-schema-suite.
Installation
$ component install ericgj/json-schema-valid
npm:
$ npm install json-schema-valid-component
Examples
There are two basic modes: as a validator object, and as a Correlation binding.
Validator object:
var Validator = var validator = // if schema has already been parsed var valid = validator; // if raw schema object var valid = validator; // checking state validator; // boolean validator; // validation errors wrapped in an Error object validator; // array of error messages with indented levels validator; // array of all assertions made on instance validator; // tree structure of validation errors validator; // tree structure of all assertions
Correlation binding:
var core = Schema = coreSchema plugin = // attach plugin to Schema Schema; // now once you have a correlation, you can call validate() on it var valid = correlation; // handling validation errors correlation
Note that assertion data beyond valid()
and error()
(errorTree()
,
errorTrace()
, assertionTree()
, assertionTrace()
) are not currently
available using the 'correlation binding' mode.
API
Validator.prototype.validate( schema:Schema, instance:Object, [desc:String], [callback:Function] )
Validate given instance against given schema. Takes optional description string (for error handling) and/or callback function. Callback receives array of valid schemas (i.e., the root-level schema plus any schemas valid through combination conditions). Callback is only run if validation succeeds (valid).
Validator.prototype.validateRaw( schema:Object, instance:Object, [desc:String], [callback:Function] )
Validate given instance against given raw schema (parsing schema first).
Validator.prototype.valid()
Result of the last validate()
call (boolean).
Validator.prototype.errors()
If the last validate()
call returned false (invalid), then returns a tree of
context objects of the form { assertions: [ ], contexts: [ ] }
, where
assertions
contains assertion (error) objects, and contexts
contains other
(sub-)context objects.
This structure can be used to build custom error messaging.
Validator.prototype.errorTrace()
If the last validate()
call returned false (invalid), then returns an array
of error messages for invalid branches, indented according to context level.
Validator.prototype.assertionTrace()
Returns array of assertion messages for all validated branches of the last
validate()
call (regardless of whether valid or invalid).
Validator.addType( key:String, validator:Function )
Add custom validation function. See type/*.js
for examples of how
to write validation functions.
Validator.addFormat( format:String, validator:Function|Regexp )
Add custom format validation function or regular expression to match.
Note specifying a regular expression here is essentially like having
named schema pattern
properties.
Correlation#validate( [desc:String], [callback:Function] )
Validate correlation instance against correlation schema.
Correlation#resolveLinks()
Validate, and return links merged from all valid schemas, if valid.
Intended to be used with the hyperschema plugin, to provide
links()
, rel()
, etc. methods to the correlation, when combination
conditions are specified. If the hyperschema plugin is not used, this
method returns undefined.
See test/tests.js
for usage examples.
Correlation#subschema( property:String )
Validate, and get the subschema describing the given instance property. If multiple subschemas are valid, the subschema is normalized as a single allOf condition.
Intended to be used as the basis for correlation.getPath()
for
co-traversing the schema and instance, when combination conditions are
specified.
See test/tests.js
for usage examples.
Correlation#coerce()
Validate, and coerces instance (applies type and default) according to:
- the first valid schema that specifies either
type
ordefault
or both; - the "top-level schema", otherwise
Note that the ordering of valid schemas cannot be relied on, so it is recommended that either the top-level schema specify type and/or default, or only one combination schema specify these.
Events
Correlation#emit('error', fn[err])
On validation failure, the correlation emits 'error' with the error.
err.message
is the first "top-level" error. err.trace
is the error trace
(equivalent of validator.errorTrace()
).
Running tests
In browser:
-
Run
make
to generate JSON Schema test suite files and build the component. -
Browse the file
test/index.html
. Tests are run via in-browser mocha.
In node:
-
Run
make node
to generate JSON Schema test suite files. -
npm test
A note on dereferencing
Dereferencing schemas is not implemented here. It is assumed that schemas
with JSON references ($ref
) will have already been dereferenced, making
use of an http client library. See for example json-schema-agent,
which provides both correlation (via HTTP headers) and schema dereferencing.
My view is that dereferencing necessarily involves external resources (the HTTP stack) and thus should be cleanly separated from validation.
However, if you know that your schema files will only have internal (fragment) references, it is possible to dereference without loading external resources (what the spec refers to as inline vs. canonical dereferencing). For convenience, in the future I will add inline dereferencing to json-schema-core. For now, the underlying Schema data structure does provide an interface for manipulating references, so it is also possible to roll your own inline dereferencing.
TODO
- add common format validators
- make error data compatible with tv4 errors
consider emitting schema-level errors or 'error trees' / rework internal Context objects- more complete walk-through of how to use with json-schema-hyper, json-schema-agent, etc. (add to json-schema-suite).
- bower
and npminstallation
Acknowledgements
The validation logic used in this library is about 90% cribbed from the geraintluff/tv4 javascript reference implementation. Thanks for that Geraint 🍻 , and thanks equally for your always-excellent documentation of how JSON Schema is supposed to work, both in the specs and on the json-schema email list.
License
MIT