Merge branch 'feature/custom-formats' into develop

Author: natesilva

README.md

@@ -5,6 +5,7 @@ A [JSON Schema](http://json-schema.org/documentation.html) validator for Node.js
 * Complete validation coverage of JSON Schema Draft v4.
 * Optional dynamic loader for referenced schemas (load schemas from a database or the web)
 * Useful error messages.
+* **NEW:** Supports custom validators for the `format` keword.
 
 ## Install
 
@@ -53,6 +54,27 @@ js.validate(instance, schema, function(errs) {
 });
 ```
 
+### Custom format validators
+
+Create a custom validator for the JSON Schema `format` keyword:
+
+```js
+var JaySchema = require('jayschema');
+var js = new JaySchema();
+
+js.addFormat('phone-us', function(value) {
+  var PHONE_US_REGEXP = /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/;
+  if (PHONE_US_REGEXP.test(value)) { return null; }
+  return 'must be a US phone number';
+});
+
+var instance = '212-555-';
+var schema = { "type": "string", "format": "phone-us" };
+
+console.log(js.validate(instance, schema));
+// fails with error description: must be a US phone number
+````
+
 ## Why JSON Schema?
 
 * Validate JSON server-side:
@@ -79,7 +101,7 @@ function loader(ref, callback) {
     // [ load your schema! ]
     if (errorOccurred) {
         callback(err);
-    } else {      
+    } else {
         callback(null, schema);
     }
 }
@@ -116,6 +138,12 @@ Return boolean indicating whether the specified schema id has previously been re
 
 See [Schema loading](#schema-loading).
 
+### JaySchema.prototype.addFormat(formatName, handler)
+
+Add a custom handler for the `format` keyword. Whenever a schema uses the `format` keyword, with the given by `formatName`, your handler will be called.
+
+The handler receives the value to be validated, and returns `null` if the value is valid, or a `string` (description of the error) if the value is not valid.
+
 ### Loaders
 
 A loader can be passed to the constructor, or you can set the `loader` property at any time. You can define your own loader. **JaySchema** also includes one built-in loader for your convenience:
@@ -153,7 +181,7 @@ Pass a `loader` callback to the `JaySchema` constructor. When an external schema
 This works with synchronous or async code.
 
 1. First, `register()` the main schemas you plan to use.
-2. Next, call `getMissingSchemas`, which returns an array of externally-referenced schemas. 
+2. Next, call `getMissingSchemas`, which returns an array of externally-referenced schemas.
 3. Retrieve and `register()` each missing schema.
 4. Repeat from step 2 until there are no more missing schemas.
 
@@ -169,7 +197,7 @@ If, instead, you want the list of *all* missing schemas referenced by all regist
 
 ## Format specifiers
 
-**JaySchema** supports the following values for the optional `format` keyword:
+For the `format` keyword, **JaySchema** allows you to add custom validation functions (see [`addFormat`](#jayschemaprototypeaddformatformatname-handler)). In addition, the following built-in formats are supported:
 
 * `date-time`: Must match the `date-time` specification given in [RFC 3339, Section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). This expects *both* a date and a time. For date-only validation or time-only validation, JaySchema supports the older draft v3 `date` and `time` formats.
 * `hostname`: Must match the “Preferred name syntax” given in [RFC 1034, Section 3.5](https://tools.ietf.org/html/rfc1034#section-3.5), with the exception that hostnames are permitted to begin with a digit, as per [RFC 1123 Section 2.1](http://tools.ietf.org/html/rfc1123#section-2.1).

Release Notes.md

@@ -1,10 +1,14 @@
+#0.3.0
+
+* **FEATURE:** [Custom `format` validators](https://github.com/natesilva/jayschema#jayschemaprototypeaddformatformatname-handler) are now supported. The syntax is compatible with that of [tv4](https://github.com/geraintluff/tv4#addformatformat-validationfunction). Thanks to [alexkwolfe](https://github.com/alexkwolfe) for the suggestion.
+
 # 0.2.8
 
-* **BUGFIX:** `enum` properties with `null` values now work. Thanks to [alexkwolfe](https://github.com/alexkwolfe).
+* **BUGFIX**: `enum` properties with `null` values now work. Thanks to [alexkwolfe](https://github.com/alexkwolfe).
 
 # 0.2.7
 
-* **BUGFIX:** Handle falsy values correctly in `ValidationError`. Thanks to [larose](https://github.com/larose).
+* **BUGFIX**: Handle falsy values correctly in `ValidationError`. Thanks to [larose](https://github.com/larose).
 * Other code cleanups. Thanks again to [larose](https://github.com/larose).
 
 # 0.2.6

lib/jayschema.js

@@ -30,6 +30,7 @@ var JaySchema = function(loader) {
 
   // internal
   this._schemaRegistry = new SchemaRegistry();
+  this._customFormatHandlers = {};
 
   // _refsRequested is an object where the key is the normalized ID
   // of the schema ref that was requested, and the value is a
@@ -73,6 +74,33 @@ JaySchema.prototype.register = function() {
   return this._schemaRegistry.register.apply(this._schemaRegistry, arguments);
 };
 
+// ******************************************************************
+// Register a handler for the format keyword. Handlers have the
+// following signature:
+//
+//  function handler(value) -> returns null (if value is valid) or
+//                             error description string (if value is
+//                             not valid)
+// ******************************************************************
+JaySchema.prototype.addFormat = function(attributeName, handler) {
+  // Wrap the format handler to make its signature match that of the
+  // internal handlers.
+  var handlerWrapper = function(config) {
+    var errors = [];
+    var result = handler(config.inst, config.schema);
+    if (typeof result === 'string') {
+      errors.push(new Errors.FormatValidationError(config.resolutionScope,
+        config.instanceContext, 'format', attributeName, config.inst, result));
+    } else if (result !== null) {
+      var desc = 'failed custom format validation';
+      errors.push(new Errors.FormatValidationError(config.resolutionScope,
+        config.instanceContext, 'format', attributeName, config.inst, desc));
+    }
+    return errors;
+  };
+  this._customFormatHandlers[attributeName] = handlerWrapper;
+};
+
 // ******************************************************************
 // [static] Return a hash for an object. We rely on JSON.stringify
 // to always return the same value for a given object. (If it
@@ -169,11 +197,20 @@ JaySchema.prototype._validateImpl = function(instance, schema, resolutionScope,
 
   // run the tests
   var config = {
+    clone: function() {
+      var result = {};
+      var keys = Object.keys(this);
+      for (var index = 0, len = keys.length; index !== len; ++index) {
+        result[keys[index]] = this[keys[index]];
+      }
+      return result;
+    },
     inst: instance,
     schema: schema,
     resolutionScope: resolutionScope,
     instanceContext: instanceContext || '#',
-    schemaRegistry: this._schemaRegistry
+    schemaRegistry: this._schemaRegistry,
+    customFormatHandlers: this._customFormatHandlers
   };
 
   var testRunner = testRunners[schema.$schema || DEFAULT_SCHEMA_VERSION];

lib/suites/draft-04/index.js

@@ -51,8 +51,8 @@ function getApplicableTests(config) {
     }
   }
 
-  // for objects, the properties, patternProperties, and
-  // additionalProperties validations are inseperable
+  // for objects: the properties, patternProperties, and
+  // additionalProperties validations are inseparable
   if (result.indexOf('properties') !== -1 ||
       result.indexOf('patternProperties') !== -1 ||
       result.indexOf('additionalProperties') !== -1)
@@ -73,6 +73,7 @@ function getApplicableTests(config) {
 //   resolutionScope: resolutionScope,
 //   instanceContext: current position within the overall instance
 //   schemaRegistry: a SchemaRegistry
+//   customFormatHandlers: custom handlers for the "format" keyword
 //
 // ******************************************************************
 function run(config)

lib/suites/draft-04/keywords/_propertiesImpl.js

@@ -35,27 +35,25 @@ module.exports = function(config) {
     var applyAdditionalProperties = true;
 
     if (Object.prototype.hasOwnProperty.call(p, m)) {
-      subTestConfig = {
-        inst: config.inst[m],
-        schema: p[m],
-        resolutionScope: config.resolutionScope + '/properties/' + m,
-        instanceContext: context,
-        schemaRegistry: config.schemaRegistry
-      };
+      subTestConfig = config.clone();
+      subTestConfig.inst = config.inst[m];
+      subTestConfig.schema = p[m];
+      subTestConfig.resolutionScope =
+        config.resolutionScope + '/properties/' + m;
+      subTestConfig.instanceContext = context;
       errors = errors.concat(testRunner(subTestConfig));
       applyAdditionalProperties = false;
     }
 
     for (var y = 0; y < pp.length; ++y) {
       var rx = pp[y][0];
       if (m.match(rx)) {
-        subTestConfig = {
-          inst: config.inst[m],
-          schema: pp[y][1],
-          resolutionScope: config.resolutionScope + '/patternProperties/' + m,
-          instanceContext: context,
-          schemaRegistry: config.schemaRegistry
-        };
+        subTestConfig = config.clone();
+        subTestConfig.inst = config.inst[m];
+        subTestConfig.schema = pp[y][1];
+        subTestConfig.resolutionScope =
+          config.resolutionScope + '/patternProperties/' + m;
+        subTestConfig.instanceContext = context;
         errors = errors.concat(testRunner(subTestConfig));
         applyAdditionalProperties = false;
       }
@@ -68,13 +66,12 @@ module.exports = function(config) {
         errors.push(new Errors.ObjectValidationError(config.resolutionScope,
           config.instanceContext, 'additionalProperties', undefined, m, desc));
       } else if (additionalProperties !== true) {
-        subTestConfig = {
-          inst: config.inst[m],
-          schema: additionalProperties,
-          resolutionScope: config.resolutionScope + '/additionalProperties',
-          instanceContext: context,
-          schemaRegistry: config.schemaRegistry
-        };
+        subTestConfig = config.clone();
+        subTestConfig.inst = config.inst[m];
+        subTestConfig.schema = additionalProperties;
+        subTestConfig.resolutionScope =
+          config.resolutionScope + '/additionalProperties';
+        subTestConfig.instanceContext = context;
         errors = errors.concat(testRunner(subTestConfig));
       }
     }

lib/suites/draft-04/keywords/allOf.js

@@ -10,13 +10,9 @@ module.exports = function(config) {
   for (var index = 0; index < config.schema.allOf.length; ++index) {
     var schema = config.schema.allOf[index];
 
-    var subTestConfig = {
-      inst: config.inst,
-      schema: schema,
-      resolutionScope: config.resolutionScope + '/allOf/' + index,
-      instanceContext: config.instanceContext,
-      schemaRegistry: config.schemaRegistry
-    };
+    var subTestConfig = config.clone();
+    subTestConfig.schema = schema;
+    subTestConfig.resolutionScope = config.resolutionScope + '/allOf/' + index;
 
     errors = errors.concat(testRunner(subTestConfig));
   }

lib/suites/draft-04/keywords/anyOf.js

@@ -13,13 +13,9 @@ module.exports = function(config) {
 
   for (var index = 0, len = config.schema.anyOf.length; index !== len; ++index)
   {
-    var subTestConfig = {
-      inst: config.inst,
-      schema: config.schema.anyOf[index],
-      resolutionScope: config.resolutionScope + '/anyOf/' + index,
-      instanceContext: config.instanceContext,
-      schemaRegistry: config.schemaRegistry
-    };
+    var subTestConfig = config.clone();
+    subTestConfig.schema = config.schema.anyOf[index];
+    subTestConfig.resolutionScope = config.resolutionScope + '/anyOf/' + index;
 
     var nestedErrors = testRunner(subTestConfig);
 

lib/suites/draft-04/keywords/dependencies.js

@@ -42,13 +42,11 @@ module.exports = function(config) {
     } else {
       // schema dependency: validates the *instance*, not the value
       // associated with the property name.
-      var subTestConfig = {
-        inst: config.inst,
-        schema: dep,
-        resolutionScope: config.resolutionScope + '/dependencies/' + index,
-        instanceContext: config.instanceContext + '/' + key,
-        schemaRegistry: config.schemaRegistry
-      };
+      var subTestConfig = config.clone();
+      subTestConfig.schema = dep;
+      subTestConfig.resolutionScope =
+        config.resolutionScope + '/dependencies/' + index;
+      subTestConfig.instanceContext = config.instanceContext + '/' + key;
       errors = errors.concat(testRunner(subTestConfig));
     }
   }

lib/suites/draft-04/keywords/format.js

@@ -16,7 +16,10 @@ var SUPPORTED_FORMATS = {
 module.exports = function(config) {
   var errors = [];
 
-  if (SUPPORTED_FORMATS.hasOwnProperty(config.schema.format)) {
+  if (config.customFormatHandlers.hasOwnProperty(config.schema.format)) {
+    errors =
+      errors.concat(config.customFormatHandlers[config.schema.format](config));
+  } else if (SUPPORTED_FORMATS.hasOwnProperty(config.schema.format)) {
     errors = errors.concat(SUPPORTED_FORMATS[config.schema.format](config));
   }
 

lib/suites/draft-04/keywords/items.js

@@ -16,13 +16,12 @@ module.exports = function(config) {
       var item = config.inst[index];
       var itemSchema = config.schema.items[index];
 
-      subTestConfig = {
-        inst: item,
-        schema: itemSchema,
-        resolutionScope: config.resolutionScope + '/items/' + index,
-        instanceContext: config.instanceContext + '/' + index,
-        schemaRegistry: config.schemaRegistry
-      };
+      subTestConfig = config.clone();
+      subTestConfig.inst = item;
+      subTestConfig.schema = itemSchema;
+      subTestConfig.resolutionScope =
+        config.resolutionScope + '/items/' + index;
+      subTestConfig.instanceContext = config.instanceContext + '/' + index;
 
       errors = errors.concat(testRunner(subTestConfig));
     }
@@ -39,13 +38,12 @@ module.exports = function(config) {
              index < config.inst.length;
              ++index)
         {
-          subTestConfig = {
-            inst: config.inst[index],
-            schema: config.schema.additionalItems,
-            resolutionScope: config.resolutionScope + '/items/' + index,
-            instanceContext: config.instanceContext + '/' + index,
-            schemaRegistry: config.schemaRegistry
-          };
+          subTestConfig = config.clone();
+          subTestConfig.inst = config.inst[index];
+          subTestConfig.schema = config.schema.additionalItems;
+          subTestConfig.resolutionScope =
+            config.resolutionScope + '/items/' + index;
+          subTestConfig.instanceContext = config.instanceContext + '/' + index;
 
           errors = errors.concat(testRunner(subTestConfig));
         }
@@ -55,13 +53,11 @@ module.exports = function(config) {
   } else {
     // one schema for all items in the array
     for (index = 0; index < config.inst.length; ++index) {
-      subTestConfig = {
-        inst: config.inst[index],
-        schema: config.schema.items,
-        resolutionScope: config.resolutionScope + '/items',
-        instanceContext: config.instanceContext + '/' + index,
-        schemaRegistry: config.schemaRegistry
-      };
+      subTestConfig = config.clone();
+      subTestConfig.inst = config.inst[index];
+      subTestConfig.schema = config.schema.items;
+      subTestConfig.resolutionScope = config.resolutionScope + '/items';
+      subTestConfig.instanceContext = config.instanceContext + '/' + index;
 
       errors = errors.concat(testRunner(subTestConfig));
     }