readme.md 5.23 KB
Newer Older
Jaap Karan Singh's avatar
Jaap Karan Singh committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
# jsonschema-extra

[![NPM version][npm-image]][npm-url]
[![David deps][david-image]][david-url]
[![node version][node-image]][node-url]
[![npm download][download-image]][download-url]

[npm-image]: https://img.shields.io/npm/v/jsonschema-extra.svg?style=flat-square
[npm-url]: https://npmjs.org/package/jsonschema-extra
[travis-image]: https://img.shields.io/travis/jksdua/jsonschema-extra.svg?style=flat-square
[travis-url]: https://travis-ci.org/jksdua/jsonschema-extra
[coveralls-image]: https://img.shields.io/coveralls/jksdua/jsonschema-extra.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/jksdua/jsonschema-extra?branch=master
[david-image]: https://img.shields.io/david/jksdua/jsonschema-extra.svg?style=flat-square
[david-url]: https://david-dm.org/jksdua/jsonschema-extra
[node-image]: https://img.shields.io/badge/node.js-%3E=_0.10-green.svg?style=flat-square
[node-url]: http://nodejs.org/download/
[download-image]: https://img.shields.io/npm/dm/jsonschema-extra.svg?style=flat-square
[download-url]: https://npmjs.org/package/jsonschema-extra
Jaap Karan Singh's avatar
Jaap Karan Singh committed
20

Jaap Karan Singh's avatar
Jaap Karan Singh committed
21
**Extends jsonschema validator with some common custom types and attributes**
Jaap Karan Singh's avatar
Jaap Karan Singh committed
22 23


Jaap Karan Singh's avatar
Jaap Karan Singh committed
24
## Usage
25

Jaap Karan Singh's avatar
Jaap Karan Singh committed
26 27
### Installation

28
```bash
Jaap Karan Singh's avatar
Jaap Karan Singh committed
29
npm install jsonschema-extra --save
Jaap Karan Singh's avatar
Jaap Karan Singh committed
30 31
```

Jaap Karan Singh's avatar
Jaap Karan Singh committed
32 33
### Example

34
```js
Jaap Karan Singh's avatar
Jaap Karan Singh committed
35
var jsonschema = require('jsonschema');
Jaap Karan Singh's avatar
Jaap Karan Singh committed
36
var extra = require('jsonschema-extra');
Jaap Karan Singh's avatar
Jaap Karan Singh committed
37 38

var validator = new (jsonschema.Validator)();
Jaap Karan Singh's avatar
Jaap Karan Singh committed
39
extra(validator);
40 41 42 43 44 45 46

// regexp
validator.validate(/abc/, { type: 'regexp' });

// error
validator.validate(new Error(), { type: 'error' });

Jaap Karan Singh's avatar
Jaap Karan Singh committed
47 48 49 50 51
// mongodb objectid
validator.validate('123456789012345678901234', { type: 'objectId' });
```


Jaap Karan Singh's avatar
Jaap Karan Singh committed
52
## Attributes
Jaap Karan Singh's avatar
Jaap Karan Singh committed
53 54 55

See `jsonschema` documentation for more detailed documentation on custom attributes.

Jaap Karan Singh's avatar
Jaap Karan Singh committed
56
### validate
Jaap Karan Singh's avatar
Jaap Karan Singh committed
57 58 59 60 61

Custom validator when `jsonschema` just isn't what you are after. This one is my absolute favourite! It comes in handy whenever you are trying to do something complex.

> One of the features of jsonschema is that you can share it across client and server which is exactly what I do! However, if your schema contains a validate attribute it will no longer be valid json. This is not a big issue if you are ok for client side code to not contain all your validation logic if schema is sent from the server. 

62 63
**Single validator**

Jaap Karan Singh's avatar
Jaap Karan Singh committed
64 65 66 67 68 69 70 71 72 73
```js
var schema = {
	validate: function(instance, schema, options) {
		// do your crazy validation here
			// return an error string if not valid
		return 'is not a valid instance';
	}
};
```

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
**Multiple validators**

```js
var schema = {
	validate: [
		function(instance, schema, options) {
			// do your crazy validation here
				// return an error string if not valid
			return 'is not a valid instance';
		},
		function(instance, schema, options) {
			// do your crazy validation here
				// return an error string if not valid
			return 'is not a valid instance';
		}
	]
};
```

Jaap Karan Singh's avatar
Jaap Karan Singh committed
93

Jaap Karan Singh's avatar
Jaap Karan Singh committed
94
## Types
Jaap Karan Singh's avatar
Jaap Karan Singh committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113

Supported types:

- error (instanceof Error)
- regexp (instanceof RegExp)
- function (Function - also works for Generator Function)
- generatorFunction (ES6 Generator Function)
- objectId (MongoDb objectId)
- plainObject (calls _.isPlainObject)

```js
validator.validate(new Error(), { type: 'error' });

validator.validate(/regexp/, { type: 'regexp' });

validator.validate(function() {}, { type: 'function' });

validator.validate(function *() {}, { type: 'generatorFunction' });

114
validator.validate('123456789012345678901234', { type: 'objectId' });
Jaap Karan Singh's avatar
Jaap Karan Singh committed
115 116 117
validator.validate(new ObjectID(), { type: 'objectId' });

validator.validate({ a: 'a', b: 'b' }, { type: 'plainObject' });
118 119
```

120 121
### js-quantities types

Jaap Karan Singh's avatar
Jaap Karan Singh committed
122
Quantity types supported by [js-quantities](https://www.npmjs.com/package/js-quantities)
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171

- qty.acceleration
- qty.activity
- qty.angle
- qty.angular_velocity
- qty.area
- qty.capacitance
- qty.charge
- qty.conductance
- qty.currency
- qty.current
- qty.energy
- qty.force
- qty.frequency
- qty.illuminance
- qty.inductance
- qty.length
- qty.luminous_power
- qty.magnetism
- qty.mass
- qty.mass_concentration
- qty.memory
- qty.molar_concentration
- qty.potential
- qty.power
- qty.pressure
- qty.radiation
- qty.resistance
- qty.speed
- qty.substance
- qty.temperature
- qty.time
- qty.unitless
- qty.viscosity
- qty.volume

```js
validator.validate('1 meter', { type: 'qty.length' });

validator.validate('45.3 seconds', { type: 'qty.time' });


// can also validate Qty instances
var Qty = require('js-quantities');
var qty = Qty.parse('2 meters');

validator.validate(qty, { type: 'qty.length' });
```

172

Jaap Karan Singh's avatar
Jaap Karan Singh committed
173
## Testing
174 175 176 177 178 179 180 181 182 183 184 185 186 187

Install `mocha` globally

```bash
$ npm install mocha -g
```

Run tests

```bash
$ npm test
```


Jaap Karan Singh's avatar
Jaap Karan Singh committed
188 189
## Changelog

190 191 192 193
### v1.2.0 (22 Dec 2014)
- Added quantity types backed by [js-quantities](https://www.npmjs.com/package/js-quantities)

### v1.1.1 (19 Dec 2014)
Jaap Karan Singh's avatar
Jaap Karan Singh committed
194
- Minor doc updates
Jaap Karan Singh's avatar
Jaap Karan Singh committed
195

196 197 198
### v1.1.0 (18 Sep 2014)
- Allow multiple validators in the `validate` property

199 200 201 202
### v1.0.2 (30 Sep 2014)
- Fixed so it works on non-Windows systems
- Removed mongodb dev dependency

Jaap Karan Singh's avatar
Jaap Karan Singh committed
203 204 205 206
### v1.0.1 (27 Sep 2014)
- Updated docs
- Updated package.json

Jaap Karan Singh's avatar
Jaap Karan Singh committed
207
### v1.0.0 (27 Sep 2014)
Jaap Karan Singh's avatar
Jaap Karan Singh committed
208
- Changed public API - jsonschema is no longer a dependency. This lets jsonschema to be updated in userland without this module requiring an update.
Jaap Karan Singh's avatar
Jaap Karan Singh committed
209 210
- Name of module changed to jsonschema-extra
- Removed conditionalEnum custom attribute since this has been fixed in the latest versions of jsonschema
Jaap Karan Singh's avatar
Jaap Karan Singh committed
211
- Removed `speed` type