z-schema 6.0.2 → 7.0.0-beta.2

package/src/ZSchema.ts

@@ -0,0 +1,467 @@
+import get from 'lodash.get';
+import { Report, SchemaError, SchemaErrorDetail } from './Report.js';
+import { FormatValidators } from './FormatValidators.js';
+import * as JsonValidation from './JsonValidation.js';
+import * as SchemaCache from './SchemaCache.js';
+import * as SchemaCompilation from './SchemaCompilation.js';
+import * as SchemaValidation from './SchemaValidation.js';
+import * as Utils from './Utils.js';
+import Draft4Schema from './schemas/schema.json' with { type: 'json' };
+import Draft4HyperSchema from './schemas/hyper-schema.json' with { type: 'json' };
+import type { Errors } from './Errors.js';
+
+/**
+ * default options
+ */
+const defaultOptions = {
+  // default timeout for all async tasks
+  asyncTimeout: 2000,
+  // force additionalProperties and additionalItems to be defined on "object" and "array" types
+  forceAdditional: false,
+  // assume additionalProperties and additionalItems are defined as "false" where appropriate
+  assumeAdditional: false,
+  // do case insensitive comparison for enums
+  enumCaseInsensitiveComparison: false,
+  // force items to be defined on "array" types
+  forceItems: false,
+  // force minItems to be defined on "array" types
+  forceMinItems: false,
+  // force maxItems to be defined on "array" types
+  forceMaxItems: false,
+  // force minLength to be defined on "string" types
+  forceMinLength: false,
+  // force maxLength to be defined on "string" types
+  forceMaxLength: false,
+  // force properties or patternProperties to be defined on "object" types
+  forceProperties: false,
+  // ignore references that cannot be resolved (remote schemas) // TODO: make sure this is only for remote schemas, not local ones
+  ignoreUnresolvableReferences: false,
+  // disallow usage of keywords that this validator can't handle
+  noExtraKeywords: false,
+  // disallow usage of schema's without "type" defined
+  noTypeless: false,
+  // disallow zero length strings in validated objects
+  noEmptyStrings: false,
+  // disallow zero length arrays in validated objects
+  noEmptyArrays: false,
+  // forces "uri" format to be in fully rfc3986 compliant
+  strictUris: false,
+  // turn on some of the above
+  strictMode: false,
+  // report error paths as an array of path segments to get to the offending node
+  reportPathAsArray: false,
+  // stop validation as soon as an error is found
+  breakOnFirstError: false,
+  // check if schema follows best practices and common sense
+  pedanticCheck: false,
+  // ignore unknown formats (do not report them as an error)
+  ignoreUnknownFormats: false,
+  // function to be called on every schema
+  customValidator: null,
+};
+
+function normalizeOptions(options) {
+  let normalized;
+
+  // options
+  if (typeof options === 'object') {
+    let keys = Object.keys(options),
+      idx = keys.length,
+      key;
+
+    // check that the options are correctly configured
+    while (idx--) {
+      key = keys[idx];
+      if (defaultOptions[key] === undefined) {
+        throw new Error('Unexpected option passed to constructor: ' + key);
+      }
+    }
+
+    // copy the default options into passed options
+    keys = Object.keys(defaultOptions);
+    idx = keys.length;
+    while (idx--) {
+      key = keys[idx];
+      if (options[key] === undefined) {
+        options[key] = Utils.clone(defaultOptions[key]);
+      }
+    }
+
+    normalized = options;
+  } else {
+    normalized = Utils.clone(defaultOptions);
+  }
+
+  if (normalized.strictMode === true) {
+    normalized.forceAdditional = true;
+    normalized.forceItems = true;
+    normalized.forceMaxLength = true;
+    normalized.forceProperties = true;
+    normalized.noExtraKeywords = true;
+    normalized.noTypeless = true;
+    normalized.noEmptyStrings = true;
+    normalized.noEmptyArrays = true;
+  }
+
+  return normalized;
+}
+
+export interface ZSchemaOptions {
+  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: unknown, json: unknown) => void;
+}
+
+export interface ValidateOptions {
+  schemaPath?: string;
+  includeErrors?: Array<keyof typeof Errors>;
+}
+
+type ValidateCallback = (e: Error, valid: boolean) => void;
+
+// a sync function that loads schemas for future use, for example from schemas directory, during server startup
+type SchemaReader = (uri: string) => unknown;
+
+export class ZSchema {
+  public lastReport: Report | undefined;
+
+  /**
+   * 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: unknown) => boolean): void {
+    FormatValidators[formatName] = validatorFunction;
+  }
+
+  /**
+   * Unregister a format.
+   *
+   * @param name - name of the custom format
+   */
+  public static unregisterFormat(name: string): void {
+    delete FormatValidators[name];
+  }
+
+  /**
+   * 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[] {
+    return Object.keys(FormatValidators);
+  }
+
+  public static getDefaultOptions(): ZSchemaOptions {
+    return Utils.cloneDeep(defaultOptions);
+  }
+
+  private cache: Record<string, string>;
+  private referenceCache: Array<string>;
+  private validateOptions: ValidateOptions;
+  options: ZSchemaOptions;
+
+  constructor(options?: ZSchemaOptions) {
+    this.cache = {};
+    this.referenceCache = [];
+    this.validateOptions = {};
+
+    this.options = normalizeOptions(options);
+
+    // Disable strict validation for the built-in schemas
+    const metaschemaOptions = normalizeOptions({});
+
+    this.setRemoteReference('http://json-schema.org/draft-04/schema', Draft4Schema, metaschemaOptions);
+    this.setRemoteReference('http://json-schema.org/draft-04/hyper-schema', Draft4HyperSchema, metaschemaOptions);
+  }
+
+  /**
+   * @param schema - JSON object representing schema
+   * @returns {boolean} true if schema is valid.
+   */
+  validateSchema(schema: unknown): boolean {
+    if (Array.isArray(schema) && schema.length === 0) {
+      throw new Error('.validateSchema was called with an empty array');
+    }
+
+    const report = new Report(this.options);
+
+    schema = SchemaCache.getSchema.call(this, report, schema);
+
+    const compiled = SchemaCompilation.compileSchema.call(this, report, schema);
+    if (compiled) {
+      SchemaValidation.validateSchema.call(this, report, schema);
+    }
+
+    this.lastReport = report;
+    return report.isValid();
+  }
+
+  /**
+   * @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, schema, options?: ValidateOptions, callback?: ValidateCallback): boolean;
+  validate(json, schema, callback?): boolean;
+  validate(json, schema): boolean;
+  validate(json, schema, options?: ValidateOptions | ValidateCallback, callback?: ValidateCallback): boolean {
+    if (typeof options === 'function') {
+      callback = options;
+      options = {};
+    }
+    if (!options) {
+      options = {};
+    }
+
+    this.validateOptions = options;
+
+    const whatIs = Utils.whatIs(schema);
+    if (whatIs !== 'string' && whatIs !== 'object') {
+      const e = new Error('Invalid .validate call - schema must be a string or object but ' + whatIs + ' was passed!');
+      if (callback) {
+        setTimeout(function () {
+          callback(e, false);
+        }, 0);
+        return;
+      }
+      throw e;
+    }
+
+    let foundError = false;
+    const report = new Report(this.options);
+    report.json = json;
+
+    if (typeof schema === 'string') {
+      const schemaName = schema;
+      schema = SchemaCache.getSchema.call(this, report, schemaName);
+      if (!schema) {
+        throw new Error("Schema with id '" + schemaName + "' wasn't found in the validator cache!");
+      }
+    } else {
+      schema = SchemaCache.getSchema.call(this, report, schema);
+    }
+
+    let compiled = false;
+    if (!foundError) {
+      compiled = SchemaCompilation.compileSchema.call(this, report, schema);
+    }
+    if (!compiled) {
+      this.lastReport = report;
+      foundError = true;
+    }
+
+    let validated = false;
+    if (!foundError) {
+      validated = SchemaValidation.validateSchema.call(this, report, schema);
+    }
+    if (!validated) {
+      this.lastReport = report;
+      foundError = true;
+    }
+
+    if (options.schemaPath) {
+      report.rootSchema = schema;
+      schema = get(schema, options.schemaPath);
+      if (!schema) {
+        throw new Error("Schema path '" + options.schemaPath + "' wasn't found in the schema!");
+      }
+    }
+
+    if (!foundError) {
+      JsonValidation.validate.call(this, report, schema, json);
+    }
+
+    if (callback) {
+      report.processAsyncTasks(this.options.asyncTimeout, callback);
+      return;
+    } else if (report.asyncTasks.length > 0) {
+      throw new Error(
+        'This validation has async tasks and cannot be done in sync mode, please provide callback argument.'
+      );
+    }
+
+    // assign lastReport so errors are retrievable in sync mode
+    this.lastReport = report;
+    return report.isValid();
+  }
+
+  /**
+   * Returns an Error object for the most recent failed validation, or null if the validation was successful.
+   */
+  getLastError(): SchemaError {
+    if (this.lastReport.errors.length === 0) {
+      return null;
+    }
+    const e: SchemaError = new Error();
+    e.name = 'z-schema validation error';
+    e.message = this.lastReport.commonErrorMessage;
+    e.details = this.lastReport.errors;
+    return e;
+  }
+
+  /**
+   * 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(): SchemaErrorDetail[] {
+    return this.lastReport && this.lastReport.errors.length > 0 ? this.lastReport.errors : null;
+  }
+
+  setRemoteReference(uri, schema, validationOptions) {
+    if (typeof schema === 'string') {
+      schema = JSON.parse(schema);
+    } else {
+      schema = Utils.cloneDeep(schema);
+    }
+
+    if (validationOptions) {
+      schema.__$validationOptions = normalizeOptions(validationOptions);
+    }
+
+    SchemaCache.cacheSchemaByUri.call(this, uri, schema);
+  }
+
+  compileSchema(schema) {
+    const report = new Report(this.options);
+
+    schema = SchemaCache.getSchema.call(this, report, schema);
+
+    SchemaCompilation.compileSchema.call(this, report, schema);
+
+    this.lastReport = report;
+    return report.isValid();
+  }
+
+  getMissingReferences(arr?) {
+    arr = arr || this.lastReport.errors;
+    let res = [],
+      idx = arr.length;
+    while (idx--) {
+      const error = arr[idx];
+      if (error.code === 'UNRESOLVABLE_REFERENCE') {
+        const reference = error.params[0];
+        if (res.indexOf(reference) === -1) {
+          res.push(reference);
+        }
+      }
+      if (error.inner) {
+        res = res.concat(this.getMissingReferences(error.inner));
+      }
+    }
+    return res;
+  }
+
+  getMissingRemoteReferences() {
+    const missingReferences = this.getMissingReferences();
+    const missingRemoteReferences = [];
+    let idx = missingReferences.length;
+    while (idx--) {
+      const remoteReference = SchemaCache.getRemotePath(missingReferences[idx]);
+      if (remoteReference && missingRemoteReferences.indexOf(remoteReference) === -1) {
+        missingRemoteReferences.push(remoteReference);
+      }
+    }
+    return missingRemoteReferences;
+  }
+
+  getResolvedSchema(schema) {
+    const report = new Report(this.options);
+    schema = SchemaCache.getSchema.call(this, report, schema);
+
+    // clone before making any modifications
+    schema = Utils.cloneDeep(schema);
+
+    const visited = [];
+
+    // clean-up the schema and resolve references
+    const cleanup = function (schema) {
+      let key;
+      const typeOf = Utils.whatIs(schema);
+      if (typeOf !== 'object' && typeOf !== 'array') {
+        return;
+      }
+
+      if (schema.___$visited) {
+        return;
+      }
+
+      schema.___$visited = true;
+      visited.push(schema);
+
+      if (schema.$ref && schema.__$refResolved) {
+        const from = schema.__$refResolved;
+        const to = schema;
+        delete schema.$ref;
+        delete schema.__$refResolved;
+        for (key in from) {
+          if (Object.prototype.hasOwnProperty.call(from, key)) {
+            to[key] = from[key];
+          }
+        }
+      }
+      for (key in schema) {
+        if (Object.prototype.hasOwnProperty.call(schema, key)) {
+          if (key.indexOf('__$') === 0) {
+            delete schema[key];
+          } else {
+            cleanup(schema[key]);
+          }
+        }
+      }
+    };
+
+    cleanup(schema);
+    visited.forEach(function (s) {
+      delete s.___$visited;
+    });
+
+    this.lastReport = report;
+    if (report.isValid()) {
+      return schema;
+    } else {
+      throw this.getLastError();
+    }
+  }
+
+  static schemaReader: SchemaReader;
+
+  setSchemaReader(schemaReader) {
+    return ZSchema.setSchemaReader(schemaReader);
+  }
+
+  getSchemaReader() {
+    return ZSchema.schemaReader;
+  }
+
+  static setSchemaReader(schemaReader) {
+    ZSchema.schemaReader = schemaReader;
+  }
+
+  static schemaSymbol = Utils.schemaSymbol;
+
+  static jsonSymbol = Utils.jsonSymbol;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import { ZSchema } from './ZSchema.js';
+
+export default ZSchema;