z-schema 3.22.0 → 3.24.2

package/index.d.ts

@@ -0,0 +1,166 @@
+// Type definitions for z-schema v3.16.0
+// Project: https://github.com/zaggino/z-schema
+// Definitions by: pgonzal <https://github.com/pgonzal>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+declare namespace Validator {
+    export interface Options {
+        asyncTimeout?: number;
+        forceAdditional?: boolean;
+        assumeAdditional?: boolean;
+        forceItems?: boolean;
+        forceMinItems?: boolean;
+        forceMaxItems?: boolean;
+        forceMinLength?: boolean;
+        forceMaxLength?: boolean;
+        forceProperties?: boolean;
+        ignoreUnresolvableReferences?: boolean;
+        noExtraKeywords?: boolean;
+        noTypeless?: boolean;
+        noEmptyStrings?: boolean;
+        noEmptyArrays?: boolean;
+        strictUris?: boolean;
+        strictMode?: boolean;
+        reportPathAsArray?: boolean;
+        breakOnFirstError?: boolean;
+        pedanticCheck?: boolean;
+        ignoreUnknownFormats?: boolean;
+        customValidator?: (report: Report, schema: any, json: any) => void;
+    }
+
+    export interface SchemaError extends Error {
+        /**
+         * Implements the Error.name contract.  The value is always "z-schema validation error".
+         */
+        name: string;
+
+        /**
+         * An identifier indicating the type of error.
+         * Example: "JSON_OBJECT_VALIDATION_FAILED"
+         */
+        message: string;
+
+        /**
+         * Returns details for each error that occurred during validation.
+         * See Options.breakOnFirstError.
+         */
+        details: SchemaErrorDetail[];
+    }
+
+    export interface SchemaErrorDetail {
+        /**
+         * Example: "Expected type string but found type array"
+         */
+        message: string;
+        /**
+         * An error identifier that can be used to format a custom error message.
+         * Example: "INVALID_TYPE"
+         */
+        code: string;
+        /**
+         * Format parameters that can be used to format a custom error message.
+         * Example: ["string","array"]
+         */
+        params: Array<string>;
+        /**
+         * A JSON path indicating the location of the error.
+         * Example: "#/projects/1"
+         */
+        path: string;
+        /**
+         * The schema rule description, which is included for certain errors where
+         * this information is useful (e.g. to describe a constraint).
+         */
+        description: string;
+
+        /**
+         * Returns details for sub-schemas that failed to match.  For example, if the schema
+         * uses the "oneOf" constraint to accept several alternative possibilities, each
+         * alternative will have its own inner detail object explaining why it failed to match.
+         */
+        inner: SchemaErrorDetail[];
+    }
+
+    export const schemaSymbol: unique symbol
+
+    export const jsonSymbol: unique symbol
+}
+
+declare class Validator {
+    /**
+     * Register a custom format.
+     *
+     * @param name - name of the custom format
+     * @param validatorFunction - custom format validator function.
+     *   Returns `true` if `value` matches the custom format.
+     */
+    public static registerFormat(formatName: string, validatorFunction: (value: any) => boolean): void;
+
+    /**
+     * Unregister a format.
+     *
+     * @param name - name of the custom format
+     */
+    public static unregisterFormat(name: string): void;
+
+    /**
+     * Get the list of all registered formats.
+     *
+     * Both the names of the burned-in formats and the custom format names are
+     * returned by this function.
+     *
+     * @returns {string[]} the list of all registered format names.
+     */
+    public static getRegisteredFormats(): string[];
+
+    public static getDefaultOptions(): Validator.Options;
+
+    constructor(options: Validator.Options);
+
+    /**
+     * @param schema - JSON object representing schema
+     * @returns {boolean} true if schema is valid.
+     */
+    validateSchema(schema: any): boolean;
+
+    /**
+     * @param json - either a JSON string or a parsed JSON object
+     * @param schema - the JSON object representing the schema
+     * @returns true if json matches schema
+     */
+    validate(json: any, schema: any): boolean;
+
+    /**
+     * @param json - either a JSON string or a parsed JSON object
+     * @param schema - the JSON object representing the schema
+     */
+    validate(json: any, schema: any, callback: (err: any, valid: boolean) => void): void;
+
+    /**
+     * Returns an Error object for the most recent failed validation, or null if the validation was successful.
+     */
+    getLastError(): Validator.SchemaError;
+
+    /**
+     * Returns the error details for the most recent validation, or undefined if the validation was successful.
+     * This is the same list as the SchemaError.details property.
+     */
+    getLastErrors(): Validator.SchemaErrorDetail[];
+}
+
+/**
+ * Basic representation of the Report class -- just enough to support customValidator
+ */
+declare class Report {
+    /**
+     * @param errorCode - a string representing the code for the custom error, e.g. INVALID_VALUE_SET
+     * @param errorMessage - string with the message to be returned in the error
+     * @param params - an array of relevant params for the error, e.g. [fieldName, fieldValue]
+     * @param subReports - sub-schema involved in the error
+     * @param schemaDescription - description from the schema used in the validation
+     * Adds custom error to the errors array in the validation instance and sets valid to false if it is not already set as false
+     */
+    addCustomError: (errorCode: string, errorMessage: string, params: string[], subReports: string, schemaDescription: string) => void;
+}
+
+export = Validator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "z-schema",
-  "version": "3.22.0",
+  "version": "3.24.2",
   "description": "JSON schema validator",
   "homepage": "https://github.com/zaggino/z-schema",
   "authors": [
@@ -28,8 +28,10 @@
     "src",
     "dist",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "index.d.ts"
   ],
+  "types": "index.d.ts",
   "scripts": {
     "prepublish": "npm test && grunt",
     "test": "jasmine-node test/ && grunt lint"
@@ -58,6 +60,7 @@
     ]
   },
   "dependencies": {
+    "core-js": "^2.5.7",
     "lodash.get": "^4.0.0",
     "lodash.isequal": "^4.0.0",
     "validator": "^10.0.0"

package/src/JsonValidation.js

@@ -1,8 +1,8 @@
 "use strict";
 
-var FormatValidators  = require("./FormatValidators"),
-    Report            = require("./Report"),
-    Utils             = require("./Utils");
+var FormatValidators = require("./FormatValidators"),
+    Report           = require("./Report"),
+    Utils            = require("./Utils");
 
 var JsonValidators = {
     multipleOf: function (report, schema, json) {
@@ -11,7 +11,7 @@ var JsonValidators = {
             return;
         }
         if (Utils.whatIs(json / schema.multipleOf) !== "integer") {
-            report.addError("MULTIPLE_OF", [json, schema.multipleOf], null, schema.description);
+            report.addError("MULTIPLE_OF", [json, schema.multipleOf], null, schema);
         }
     },
     maximum: function (report, schema, json) {
@@ -21,11 +21,11 @@ var JsonValidators = {
         }
         if (schema.exclusiveMaximum !== true) {
             if (json > schema.maximum) {
-                report.addError("MAXIMUM", [json, schema.maximum], null, schema.description);
+                report.addError("MAXIMUM", [json, schema.maximum], null, schema);
             }
         } else {
             if (json >= schema.maximum) {
-                report.addError("MAXIMUM_EXCLUSIVE", [json, schema.maximum], null, schema.description);
+                report.addError("MAXIMUM_EXCLUSIVE", [json, schema.maximum], null, schema);
             }
         }
     },
@@ -39,11 +39,11 @@ var JsonValidators = {
         }
         if (schema.exclusiveMinimum !== true) {
             if (json < schema.minimum) {
-                report.addError("MINIMUM", [json, schema.minimum], null, schema.description);
+                report.addError("MINIMUM", [json, schema.minimum], null, schema);
             }
         } else {
             if (json <= schema.minimum) {
-                report.addError("MINIMUM_EXCLUSIVE", [json, schema.minimum], null, schema.description);
+                report.addError("MINIMUM_EXCLUSIVE", [json, schema.minimum], null, schema);
             }
         }
     },
@@ -56,7 +56,7 @@ var JsonValidators = {
             return;
         }
         if (Utils.ucs2decode(json).length > schema.maxLength) {
-            report.addError("MAX_LENGTH", [json.length, schema.maxLength], null, schema.description);
+            report.addError("MAX_LENGTH", [json.length, schema.maxLength], null, schema);
         }
     },
     minLength: function (report, schema, json) {
@@ -65,7 +65,7 @@ var JsonValidators = {
             return;
         }
         if (Utils.ucs2decode(json).length < schema.minLength) {
-            report.addError("MIN_LENGTH", [json.length, schema.minLength], null, schema.description);
+            report.addError("MIN_LENGTH", [json.length, schema.minLength], null, schema);
         }
     },
     pattern: function (report, schema, json) {
@@ -74,7 +74,7 @@ var JsonValidators = {
             return;
         }
         if (RegExp(schema.pattern).test(json) === false) {
-            report.addError("PATTERN", [schema.pattern, json], null, schema.description);
+            report.addError("PATTERN", [schema.pattern, json], null, schema);
         }
     },
     additionalItems: function (report, schema, json) {
@@ -86,7 +86,7 @@ var JsonValidators = {
         // the json is valid if its size is less than, or equal to, the size of "items".
         if (schema.additionalItems === false && Array.isArray(schema.items)) {
             if (json.length > schema.items.length) {
-                report.addError("ARRAY_ADDITIONAL_ITEMS", null, null, schema.description);
+                report.addError("ARRAY_ADDITIONAL_ITEMS", null, null, schema);
             }
         }
     },
@@ -99,7 +99,7 @@ var JsonValidators = {
             return;
         }
         if (json.length > schema.maxItems) {
-            report.addError("ARRAY_LENGTH_LONG", [json.length, schema.maxItems], null, schema.description);
+            report.addError("ARRAY_LENGTH_LONG", [json.length, schema.maxItems], null, schema);
         }
     },
     minItems: function (report, schema, json) {
@@ -108,7 +108,7 @@ var JsonValidators = {
             return;
         }
         if (json.length < schema.minItems) {
-            report.addError("ARRAY_LENGTH_SHORT", [json.length, schema.minItems], null, schema.description);
+            report.addError("ARRAY_LENGTH_SHORT", [json.length, schema.minItems], null, schema);
         }
     },
     uniqueItems: function (report, schema, json) {
@@ -119,7 +119,7 @@ var JsonValidators = {
         if (schema.uniqueItems === true) {
             var matches = [];
             if (Utils.isUniqueArray(json, matches) === false) {
-                report.addError("ARRAY_UNIQUE", matches, null, schema.description);
+                report.addError("ARRAY_UNIQUE", matches, null, schema);
             }
         }
     },
@@ -130,7 +130,7 @@ var JsonValidators = {
         }
         var keysCount = Object.keys(json).length;
         if (keysCount > schema.maxProperties) {
-            report.addError("OBJECT_PROPERTIES_MAXIMUM", [keysCount, schema.maxProperties], null, schema.description);
+            report.addError("OBJECT_PROPERTIES_MAXIMUM", [keysCount, schema.maxProperties], null, schema);
         }
     },
     minProperties: function (report, schema, json) {
@@ -140,7 +140,7 @@ var JsonValidators = {
         }
         var keysCount = Object.keys(json).length;
         if (keysCount < schema.minProperties) {
-            report.addError("OBJECT_PROPERTIES_MINIMUM", [keysCount, schema.minProperties], null, schema.description);
+            report.addError("OBJECT_PROPERTIES_MINIMUM", [keysCount, schema.minProperties], null, schema);
         }
     },
     required: function (report, schema, json) {
@@ -152,7 +152,7 @@ var JsonValidators = {
         while (idx--) {
             var requiredPropertyName = schema.required[idx];
             if (json[requiredPropertyName] === undefined) {
-                report.addError("OBJECT_MISSING_REQUIRED_PROPERTY", [requiredPropertyName], null, schema.description);
+                report.addError("OBJECT_MISSING_REQUIRED_PROPERTY", [requiredPropertyName], null, schema);
             }
         }
     },
@@ -208,7 +208,7 @@ var JsonValidators = {
                     }
                 }
                 if (s.length > 0) {
-                    report.addError("OBJECT_ADDITIONAL_PROPERTIES", [s], null, schema.description);
+                    report.addError("OBJECT_ADDITIONAL_PROPERTIES", [s], null, schema);
                 }
             }
         }
@@ -236,7 +236,7 @@ var JsonValidators = {
                     while (idx2--) {
                         var requiredPropertyName = dependencyDefinition[idx2];
                         if (json[requiredPropertyName] === undefined) {
-                            report.addError("OBJECT_DEPENDENCY_KEY", [requiredPropertyName, dependencyName], null, schema.description);
+                            report.addError("OBJECT_DEPENDENCY_KEY", [requiredPropertyName, dependencyName], null, schema);
                         }
                     }
                 }
@@ -259,7 +259,7 @@ var JsonValidators = {
 
         if (match === false) {
             var error = caseInsensitiveMatch && this.options.enumCaseInsensitiveComparison ? "ENUM_CASE_MISMATCH" : "ENUM_MISMATCH";
-            report.addError(error, [json], null, schema.description);
+            report.addError(error, [json], null, schema);
         }
     },
     type: function (report, schema, json) {
@@ -267,11 +267,11 @@ var JsonValidators = {
         var jsonType = Utils.whatIs(json);
         if (typeof schema.type === "string") {
             if (jsonType !== schema.type && (jsonType !== "integer" || schema.type !== "number")) {
-                report.addError("INVALID_TYPE", [schema.type, jsonType], null, schema.description);
+                report.addError("INVALID_TYPE", [schema.type, jsonType], null, schema);
             }
         } else {
             if (schema.type.indexOf(jsonType) === -1 && (jsonType !== "integer" || schema.type.indexOf("number") === -1)) {
-                report.addError("INVALID_TYPE", [schema.type, jsonType], null, schema.description);
+                report.addError("INVALID_TYPE", [schema.type, jsonType], null, schema);
             }
         }
     },
@@ -298,7 +298,7 @@ var JsonValidators = {
         }
 
         if (passed === false) {
-            report.addError("ANY_OF_MISSING", undefined, subReports, schema.description);
+            report.addError("ANY_OF_MISSING", undefined, subReports, schema);
         }
     },
     oneOf: function (report, schema, json) {
@@ -316,16 +316,16 @@ var JsonValidators = {
         }
 
         if (passes === 0) {
-            report.addError("ONE_OF_MISSING", undefined, subReports, schema.description);
+            report.addError("ONE_OF_MISSING", undefined, subReports, schema);
         } else if (passes > 1) {
-            report.addError("ONE_OF_MULTIPLE", null, null, schema.description);
+            report.addError("ONE_OF_MULTIPLE", null, null, schema);
         }
     },
     not: function (report, schema, json) {
         // http://json-schema.org/latest/json-schema-validation.html#rfc.section.5.5.6.2
         var subReport = new Report(report);
         if (exports.validate.call(this, subReport, schema.not, json) === true) {
-            report.addError("NOT_PASSED", null, null, schema.description);
+            report.addError("NOT_PASSED", null, null, schema);
         }
     },
     definitions: function () { /*report, schema, json*/
@@ -340,17 +340,17 @@ var JsonValidators = {
                 // async
                 report.addAsyncTask(formatValidatorFn, [json], function (result) {
                     if (result !== true) {
-                        report.addError("INVALID_FORMAT", [schema.format, json], null, schema.description);
+                        report.addError("INVALID_FORMAT", [schema.format, json], null, schema);
                     }
                 });
             } else {
                 // sync
                 if (formatValidatorFn.call(this, json) !== true) {
-                    report.addError("INVALID_FORMAT", [schema.format, json], null, schema.description);
+                    report.addError("INVALID_FORMAT", [schema.format, json], null, schema);
                 }
             }
         } else if (this.options.ignoreUnknownFormats !== true) {
-            report.addError("UNKNOWN_FORMAT", [schema.format], null, schema.description);
+            report.addError("UNKNOWN_FORMAT", [schema.format], null, schema);
         }
     }
 };
@@ -367,7 +367,7 @@ var recurseArray = function (report, schema, json) {
     if (Array.isArray(schema.items)) {
 
         while (idx--) {
-            // equal to doesnt make sense here
+            // equal to doesn't make sense here
             if (idx < schema.items.length) {
                 report.path.push(idx.toString());
                 exports.validate.call(this, report, schema.items[idx], json[idx]);
@@ -455,6 +455,14 @@ var recurseObject = function (report, schema, json) {
     }
 };
 
+exports.JsonValidators = JsonValidators;
+
+/**
+ *
+ * @param {Report} report
+ * @param {*} schema
+ * @param {*} json
+ */
 exports.validate = function (report, schema, json) {
 
     report.commonErrorMessage = "JSON_OBJECT_VALIDATION_FAILED";
@@ -462,7 +470,7 @@ exports.validate = function (report, schema, json) {
     // check if schema is an object
     var to = Utils.whatIs(schema);
     if (to !== "object") {
-        report.addError("SCHEMA_NOT_AN_OBJECT", [to], null, schema.description);
+        report.addError("SCHEMA_NOT_AN_OBJECT", [to], null, schema);
         return false;
     }
 
@@ -485,7 +493,7 @@ exports.validate = function (report, schema, json) {
         var maxRefs = 99;
         while (schema.$ref && maxRefs > 0) {
             if (!schema.__$refResolved) {
-                report.addError("REF_UNRESOLVED", [schema.$ref], null, schema.description);
+                report.addError("REF_UNRESOLVED", [schema.$ref], null, schema);
                 break;
             } else if (schema.__$refResolved === schema) {
                 break;

package/src/Report.js

@@ -4,6 +4,12 @@ var get    = require("lodash.get");
 var Errors = require("./Errors");
 var Utils  = require("./Utils");
 
+/**
+ * @class
+ *
+ * @param {Report|object} parentOrOptions
+ * @param {object} [reportOptions]
+ */
 function Report(parentOrOptions, reportOptions) {
     this.parentReport = parentOrOptions instanceof Report ?
                             parentOrOptions :
@@ -16,10 +22,20 @@ function Report(parentOrOptions, reportOptions) {
     this.reportOptions = reportOptions || {};
 
     this.errors = [];
+    /**
+     * @type {string[]}
+     */
     this.path = [];
     this.asyncTasks = [];
+
+    this.rootSchema = undefined;
+    this.commonErrorMessage = undefined;
+    this.json = undefined;
 }
 
+/**
+ * @returns {boolean}
+ */
 Report.prototype.isValid = function () {
     if (this.asyncTasks.length > 0) {
         throw new Error("Async tasks pending, can't answer isValid");
@@ -27,10 +43,23 @@ Report.prototype.isValid = function () {
     return this.errors.length === 0;
 };
 
+/**
+ *
+ * @param {*} fn
+ * @param {*} args
+ * @param {*} asyncTaskResultProcessFn
+ */
 Report.prototype.addAsyncTask = function (fn, args, asyncTaskResultProcessFn) {
     this.asyncTasks.push([fn, args, asyncTaskResultProcessFn]);
 };
 
+/**
+ *
+ * @param {*} timeout
+ * @param {function(*, *)} callback
+ *
+ * @returns {void}
+ */
 Report.prototype.processAsyncTasks = function (timeout, callback) {
 
     var validationTimeout = timeout || 2000,
@@ -42,7 +71,7 @@ Report.prototype.processAsyncTasks = function (timeout, callback) {
     function finish() {
         process.nextTick(function () {
             var valid = self.errors.length === 0,
-                err   = valid ? undefined : self.errors;
+                err = valid ? undefined : self.errors;
             callback(err, valid);
         });
     }
@@ -78,7 +107,16 @@ Report.prototype.processAsyncTasks = function (timeout, callback) {
 
 };
 
+/**
+ *
+ * @param {*} returnPathAsString
+ *
+ * @return {string[]|string}
+ */
 Report.prototype.getPath = function (returnPathAsString) {
+    /**
+     * @type {string[]|string}
+     */
     var path = [];
     if (this.parentReport) {
         path = path.concat(this.parentReport.path);
@@ -123,6 +161,13 @@ Report.prototype.getSchemaId = function () {
     return this.rootSchema.id;
 };
 
+/**
+ *
+ * @param {*} errorCode
+ * @param {*} params
+ *
+ * @return {boolean}
+ */
 Report.prototype.hasError = function (errorCode, params) {
     var idx = this.errors.length;
     while (idx--) {
@@ -145,13 +190,43 @@ Report.prototype.hasError = function (errorCode, params) {
     return false;
 };
 
-Report.prototype.addError = function (errorCode, params, subReports, schemaDescription) {
+/**
+ *
+ * @param {*} errorCode
+ * @param {*} params
+ * @param {Report[]|Report} [subReports]
+ * @param {*} [schema]
+ *
+ * @return {void}
+ */
+Report.prototype.addError = function (errorCode, params, subReports, schema) {
     if (!errorCode) { throw new Error("No errorCode passed into addError()"); }
 
-    this.addCustomError(errorCode, Errors[errorCode], params, subReports, schemaDescription);
+    this.addCustomError(errorCode, Errors[errorCode], params, subReports, schema);
+};
+
+Report.prototype.getJson = function () {
+    var self = this;
+    while (self.json === undefined) {
+        self = self.parentReport;
+        if (self === undefined) {
+            return undefined;
+        }
+    }
+    return self.json;
 };
 
-Report.prototype.addCustomError = function (errorCode, errorMessage, params, subReports, schemaDescription) {
+/**
+ *
+ * @param {*} errorCode
+ * @param {*} errorMessage
+ * @param {*[]} params
+ * @param {Report[]|Report} subReports
+ * @param {*} schema
+ *
+ * @returns {void}
+ */
+Report.prototype.addCustomError = function (errorCode, errorMessage, params, subReports, schema) {
     if (this.errors.length >= this.reportOptions.maxErrors) {
         return;
     }
@@ -175,8 +250,18 @@ Report.prototype.addCustomError = function (errorCode, errorMessage, params, sub
         schemaId: this.getSchemaId()
     };
 
-    if (schemaDescription) {
-        err.description = schemaDescription;
+    err[Utils.schemaSymbol] = schema;
+    err[Utils.jsonSymbol] = this.getJson();
+
+    if (schema && typeof schema === "string") {
+        err.description = schema;
+    } else if (schema && typeof schema === "object") {
+        if (schema.title) {
+            err.title = schema.title;
+        }
+        if (schema.description) {
+            err.description = schema.description;
+        }
     }
 
     if (subReports != null) {

package/src/SchemaCache.js

@@ -64,6 +64,13 @@ function findId(schema, id) {
     }
 }
 
+/**
+ *
+ * @param {*} uri
+ * @param {*} schema
+ *
+ * @returns {void}
+ */
 exports.cacheSchemaByUri = function (uri, schema) {
     var remotePath = getRemotePath(uri);
     if (remotePath) {
@@ -71,6 +78,12 @@ exports.cacheSchemaByUri = function (uri, schema) {
     }
 };
 
+/**
+ *
+ * @param {*} uri
+ *
+ * @returns {void}
+ */
 exports.removeFromCacheByUri = function (uri) {
     var remotePath = getRemotePath(uri);
     if (remotePath) {
@@ -78,6 +91,12 @@ exports.removeFromCacheByUri = function (uri) {
     }
 };
 
+/**
+ *
+ * @param {*} uri
+ *
+ * @returns {boolean}
+ */
 exports.checkCacheForUri = function (uri) {
     var remotePath = getRemotePath(uri);
     return remotePath ? this.cache[remotePath] != null : false;

package/src/SchemaValidation.js

@@ -501,6 +501,13 @@ var SchemaValidators = {
     }
 };
 
+/**
+ *
+ * @param {Report} report
+ * @param {*[]} arr
+ *
+ * @returns {boolean}
+ */
 var validateArrayOfSchemas = function (report, arr) {
     var idx = arr.length;
     while (idx--) {
@@ -509,6 +516,11 @@ var validateArrayOfSchemas = function (report, arr) {
     return report.isValid();
 };
 
+/**
+ *
+ * @param {Report} report
+ * @param {*} schema
+ */
 exports.validateSchema = function (report, schema) {
 
     report.commonErrorMessage = "SCHEMA_VALIDATION_FAILED";