# grunt-tv4 [![Build Status](https://secure.travis-ci.org/Bartvds/grunt-tv4.png?branch=master)](http://travis-ci.org/Bartvds/grunt-tv4) [![Dependency Status](https://gemnasium.com/Bartvds/grunt-tv4.png)](https://gemnasium.com/Bartvds/grunt-tv4) [![NPM version](https://badge.fury.io/js/grunt-tv4.png)](http://badge.fury.io/js/grunt-tv4) > Use grunt and [Tiny Validator tv4](https://github.com/geraintluff/tv4) to validate values against [json-schema](http://json-schema.org/) draft v4 ## Getting Started This plugin requires Grunt `~0.4.1` If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command: ```shell $ npm install grunt-tv4 --save-dev ``` Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript: ```js grunt.loadNpmTasks('grunt-tv4'); ``` ## The "tv4" task ### Notes * Uses [Tiny Validator tv4 ](https://github.com/geraintluff/tv4) so schemas must conform to [json-schema draft v4](http://json-schema.org/documentation.html). * Supports automatically resolution and loading remote references by http via `$ref`. * To use `$ref` see the [json-schema](http://json-schema.org/) documentation or [this help](http://spacetelescope.github.io/understanding-json-schema/structuring.html). * For general help with json-schema see this excelent [guide](http://spacetelescope.github.io/understanding-json-schema/) and usable [reference](http://spacetelescope.github.io/understanding-json-schema/reference/index.html). * Errors formatted by the [tv4-reporter](https://github.com/Bartvds/tv4-reporter) library. ### API change As of version `v0.2.0` the API was changed to follow the Grunt options- and file-selection conventions. The old pattern (which abused the destination-specifier) is no longer supported. The readme for the previous API can be found [here](https://github.com/Bartvds/grunt-tv4/tree/71ef1726945d05efd5daca29f26cbf4ab09c858e). The root schema must now to be specified as `options.root`. ### Example * Demo of version `v0.3.0` output on [travis-ci](https://travis-ci.org/Bartvds/grunt-tv4/jobs/14468920) ### Basic usage Validate from .json files: ```js grunt.initConfig({ tv4: { options: { root: grunt.file.readJSON('schema/main.json') } myTarget: { src: ['data/*.json'] } } }) ``` Valdiate values: ```js grunt.initConfig({ tv4: { myTarget: { options: { root: { type: 'object', properties: { ... } } }, values: [ { ... }, { ... } ] } } }) ```` ### Advanced usage ```js grunt.initConfig({ tv4: { options: { // specify the main schema, one of: // - path to json // - http-url // - schema object // - callback that returns one of the above root: grunt.file.readJSON('schema/main.json'), // show multiple errors per file (off by default) multi: true, // create a new tv4 instance for every target (off by default) fresh: true, // add schemas in bulk (each required to have an 'id' property) (can be a callback) add: [ grunt.file.readJSON('schema/apple.json'), grunt.file.readJSON('schema/pear.json') ], // set schemas by URI (can be a callback) schemas: { 'http://example.com/schema/apple': grunt.file.readJSON('schema/apple.json'), 'http://example.com/schema/pear': grunt.file.readJSON('schema/pear.json') }, // map of custom formats passed to tv4.addFormat() formats: { date: function (data, schema) { if (typeof data !== 'string' || !dateRegex.test(data)) { return 'value must be string of the form: YYYY-MM-DD'; } return null; } }, // passed to tv4.validate() checkRecursive: false // passed to tv4.validate() banUnknownProperties: false // passed tv4.language() language: 'de' // passed tv4.addLanguage() languages: { 'de': { ... } } }, // load json from disk myFiles: { src: ['data/*.json', 'data/fruit/**/*.json'] }, myValues: { // validate values values: [ grunt.file.readJSON('data/apple.json'), grunt.file.readJSON('data/pear.json') ], }, myValueMap: { // alternately pass as object and the keys will be used as labels in the reports values: { 'apple': grunt.file.readJSON('data/apple.json'), 'pear': grunt.file.readJSON('data/pear.json') }, }, myCallback: { // alternately pass a function() to return a collection of values (array or object) values: function() { return { 'apple': grunt.file.readJSON('data/apple.json'), 'pear': grunt.file.readJSON('data/pear.json') } } } } }) ``` ## History * 0.4.0 - Updated some depedencies. `root`, `add` and `schemas` can be a callback function (for lazy init). * 0.3.0 - Big internal rewrite: * Added `.values` option. * Extracted reporting to [tv4-reporter](https://github.com/Bartvds/tv4-reporter), [miniwrite](https://github.com/Bartvds/miniwrite) and [ministyle](https://github.com/Bartvds/ministyle). * Moved loader logic to own stand-alone module (for later extraction) * Extracted test-running logic to own module (for later extraction) * 0.2.1 - Added support to report subErrors (for anyOf/oneOf) * 0.2.0 - Updated to follow the Grunt conventions. * 0.1.4 - Updated `tv4` to version `1.0.11` * Added support for `tv4.addFormat()` / `languages` / `checkRecursive` / `banUnknownProperties`. * 0.1.3 - Support for loading remote references (JSON Schema's `$ref`). * 0.1.1 - Bugfixes and improved reporting * 0.1.0 - First release with synchronous validation ## Contributing In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [Grunt](http://gruntjs.com/). [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/Bartvds/grunt-tv4/trend.png)](https://bitdeli.com/free "Bitdeli Badge")