Tiny Validator for JSON Schema v4

Common errors

• RangeError: Maximum call stack size exceeded

  cause Attempting to validate a JavaScript object with circular references without enabling recursive checking.
  fix Pass `true` as the third argument to the validation method: `tv4.validate(data, schema, true);` or `tv4.validateResult(data, schema, true);`.

• { valid: false, error: { ... }, missing: [] } where error seems incorrect or refers to a previous validation.

  cause Using `tv4.validate(data, schema)` in an environment where multiple validations might occur concurrently, leading to the global `tv4.error` property being overwritten.
  fix Switch to `tv4.validateResult(data, schema)` which returns a self-contained result object, preventing global state conflicts.

• Validation passes (returns `true`) but some schemas referenced by `$ref` are not actually validated.

  cause The referenced schemas were not added to `tv4` using `tv4.addSchema(url, schema)`, and the validation was synchronous. `tv4.missing` will indicate which schemas were not found.
  fix Ensure all referenced schemas are pre-loaded using `tv4.addSchema(url, schema)` before validation. Alternatively, if asynchronous fetching is set up, ensure it's properly configured and awaited.

• JSON data contains an extra field not defined in the schema, but validation still passes.

  cause By default, `tv4` ignores properties not explicitly defined in the schema.
  fix Set `tv4.banUnknownProperties = true;` globally or add `"additionalProperties": false` to your schema to disallow undeclared properties.

Warnings

• breaking tv4 is no longer actively maintained. Its last release was in 2015, and it strictly supports only JSON Schema Draft v4. It does not support newer drafts (like Draft 6, 7, 2019-09, or 2020-12), meaning schemas written for modern JSON Schema specifications will not validate correctly.
  Fix: For new projects or projects requiring modern JSON Schema features, consider using actively maintained alternatives like Ajv (Another JSON Schema Validator) which supports all current drafts and offers better performance and extensibility.
• gotcha The default `tv4.validate` method returns a boolean and stores the last validation error in `tv4.error` and missing schemas in `tv4.missing`. These are global properties, making `tv4.validate` unsafe for concurrent or multi-threaded environments, as validation results can be overwritten.
  Fix: Always use `tv4.validateResult(data, schema)` or `tv4.validateMultiple(data, schema)` for safer, self-contained result objects that include `valid`, `error` (or `errors`), and `missing` properties, ensuring thread-safety and consistent error reporting.
• gotcha By default, `tv4` stops validation on the first encountered error. This means `tv4.validate` and `tv4.validateResult` will only report one error at a time.
  Fix: To collect all validation errors, use `tv4.validateMultiple(data, schema)`. This method returns an object containing an `errors` array with all detected issues.
• gotcha Validation of cyclical JavaScript objects (objects that reference themselves, which are not valid JSON but can exist in JavaScript) can lead to 'too much recursion' errors or script hangs.
  Fix: When validating objects that might contain circular references, pass `true` as the third argument to any validation method (e.g., `tv4.validate(data, schema, true)`). This enables recursive checking, preventing infinite loops.
• gotcha By default, `tv4` ignores properties in your data that are not defined in the schema. This can lead to unexpected behavior if you intend for unknown properties to cause validation failure.
  Fix: To treat unknown properties as validation errors, set the `banUnknownProperties` flag to `true` on the `tv4` object (e.g., `tv4.banUnknownProperties = true;`). Alternatively, set `"additionalProperties": false` in your schema.
• gotcha Asynchronous validation, which allows `tv4` to fetch missing schemas dynamically, is not built-in and requires an external file (`tv4.async-jquery.js`) that currently has a dependency on jQuery.
  Fix: If asynchronous schema fetching is required, include `tv4.async-jquery.js`. For environments without jQuery, the README suggests the code is simple enough to adapt, but no official alternatives are provided. Consider pre-loading all schemas via `tv4.addSchema` if possible to avoid this dependency.

Install

• npm install tv4 npm
• yarn add tv4 yarn
• pnpm add tv4 pnpm

Imports

• tv4
  wrong:

  import tv4 from 'tv4';

  correct:

  const tv4 = require('tv4');

  tv4 is primarily a CommonJS module. While bundlers might process ESM imports, direct ESM import syntax without specific configuration or interop is not natively supported for older Node.js versions or direct browser use.
• validate
  wrong:

  import { validate } from 'tv4';
  const isValid = validate(data, schema);

  correct:

  const tv4 = require('tv4');
  const isValid = tv4.validate(data, schema);

  The core validation functions are properties of the default exported `tv4` object, not named exports. Access them via the `tv4` object.
• tv4.addSchema
  wrong:

  import { addSchema } from 'tv4';

  correct:

  const tv4 = require('tv4');
  tv4.addSchema(url, schema);

  Utility functions like `addSchema` are also methods of the global `tv4` object.

Quickstart

This quickstart demonstrates basic synchronous JSON Schema Draft v4 validation, including how to handle validation results and errors, disallow additional properties, and use the `validateResult` method for safer error handling in shared environments.

const tv4 = require('tv4');

// Define your data to be validated
const data = {
  name: 'John Doe',
  age: 30,
  email: 'john.doe@example.com',
  occupation: 'Software Engineer'
};

// Define your JSON Schema Draft v4
const schema = {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "age", "email"],
  "additionalProperties": false // Disallow unknown properties
};

// Perform validation
const result = tv4.validateResult(data, schema, true); // Use validateResult for structured output and checkRecursive

if (!result.valid) {
  console.error('Validation failed!');
  console.error('Error:', result.error);
  if (result.missing && result.missing.length > 0) {
    console.warn('Missing schemas:', result.missing);
  }
} else {
  console.log('Validation successful!');
}

// Example with an invalid data
const invalidData = { name: 'Jane Doe', age: 'twenty', email: 'invalid-email' };
const invalidResult = tv4.validateResult(invalidData, schema);
if (!invalidResult.valid) {
  console.error('\nValidation failed for invalid data:');
  console.error('Error:', invalidResult.error);
}