happy-ferret / grunt-tv4

Use Grunt and Tiny Validator tv4 to validate files against json-schema draft v4

grunt-tv4

Use grunt and Tiny Validator tv4 to validate values against json-schema draft v4

Getting Started

This plugin requires Grunt >=0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

$ npm install grunt-tv4 --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-tv4');

The "tv4" task

Notes

• Uses Tiny Validator tv4 so schemas must conform to json-schema draft v4.
• Supports automatically resolution and loading remote references by http via $ref.
• To use $ref see the json-schema documentation or this help.
• For general help with json-schema see this excelent guide and usable reference.
• Errors formatted by the 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.

The root schema must now to be specified as options.root.

Example

• Demo of version v0.3.0 output on travis-ci

Basic usage

Validate from .json files:

grunt.initConfig({
	tv4: {
		options: {
		    root: grunt.file.readJSON('schema/main.json')
		},
		myTarget: {
			src: ['data/*.json']
		}
	}
})

Valdiate values:

grunt.initConfig({
	tv4: {
		myTarget: {
			options: {
				root: {
					type: 'object',
					properties: { ... }
				}
			},
			values: [
				{ ... },
				{ ... }
			]
		}
	}
})

Advanced usage

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.5.0
  • Bring travis node targets up to date
  • Remove grunt-cli as a devDependency (it should be installed globally)
  • devDependencies: grunt 1.0.1
  • peerDependencies: grunt >= 0.4.1
• 0.4.2
  • Typos fixed in code examples.
  • Update grunt in peerDependencies to support grunt v1.
  • Update docs to reflect change of project ownership.
• 0.4.0 - Updated some dependencies. 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, miniwrite and 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 Schemas $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.