{"id":12205,"library":"tv4","title":"Tiny Validator for JSON Schema v4","description":"tv4 is an abandoned JavaScript library designed for validating data against JSON Schema Draft v4 exclusively. Its latest release, version 1.3.0, was published in August 2015, with no subsequent updates or active maintenance. The library differentiates itself by offering synchronous, single-error validation by default, with optional methods for collecting multiple errors (`validateMultiple`) or a structured result object (`validateResult`) to better support multi-threaded environments where global state (`tv4.error`, `tv4.missing`) is problematic. It also supports `$ref` for referencing external schemas and has an optional mechanism for handling cyclical JavaScript objects. Due to its strict adherence to Draft v4 and lack of updates, it does not support newer JSON Schema drafts (like Draft 6, 7, 2019-09, or 2020-12) and is not recommended for new projects requiring modern schema features or active support.","status":"abandoned","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/geraintluff/tv4","tags":["javascript","json-schema","schema","validator","tv4"],"install":[{"cmd":"npm install tv4","lang":"bash","label":"npm"},{"cmd":"yarn add tv4","lang":"bash","label":"yarn"},{"cmd":"pnpm add tv4","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import tv4 from 'tv4';","symbol":"tv4","correct":"const tv4 = require('tv4');"},{"note":"The core validation functions are properties of the default exported `tv4` object, not named exports. Access them via the `tv4` object.","wrong":"import { validate } from 'tv4';\nconst isValid = validate(data, schema);","symbol":"validate","correct":"const tv4 = require('tv4');\nconst isValid = tv4.validate(data, schema);"},{"note":"Utility functions like `addSchema` are also methods of the global `tv4` object.","wrong":"import { addSchema } from 'tv4';","symbol":"tv4.addSchema","correct":"const tv4 = require('tv4');\ntv4.addSchema(url, schema);"}],"quickstart":{"code":"const tv4 = require('tv4');\n\n// Define your data to be validated\nconst data = {\n  name: 'John Doe',\n  age: 30,\n  email: 'john.doe@example.com',\n  occupation: 'Software Engineer'\n};\n\n// Define your JSON Schema Draft v4\nconst schema = {\n  \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\", \"minLength\": 1 },\n    \"age\": { \"type\": \"integer\", \"minimum\": 0 },\n    \"email\": { \"type\": \"string\", \"format\": \"email\" }\n  },\n  \"required\": [\"name\", \"age\", \"email\"],\n  \"additionalProperties\": false // Disallow unknown properties\n};\n\n// Perform validation\nconst result = tv4.validateResult(data, schema, true); // Use validateResult for structured output and checkRecursive\n\nif (!result.valid) {\n  console.error('Validation failed!');\n  console.error('Error:', result.error);\n  if (result.missing && result.missing.length > 0) {\n    console.warn('Missing schemas:', result.missing);\n  }\n} else {\n  console.log('Validation successful!');\n}\n\n// Example with an invalid data\nconst invalidData = { name: 'Jane Doe', age: 'twenty', email: 'invalid-email' };\nconst invalidResult = tv4.validateResult(invalidData, schema);\nif (!invalidResult.valid) {\n  console.error('\\nValidation failed for invalid data:');\n  console.error('Error:', invalidResult.error);\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To collect all validation errors, use `tv4.validateMultiple(data, schema)`. This method returns an object containing an `errors` array with all detected issues.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Pass `true` as the third argument to the validation method: `tv4.validate(data, schema, true);` or `tv4.validateResult(data, schema, true);`.","cause":"Attempting to validate a JavaScript object with circular references without enabling recursive checking.","error":"RangeError: Maximum call stack size exceeded"},{"fix":"Switch to `tv4.validateResult(data, schema)` which returns a self-contained result object, preventing global state conflicts.","cause":"Using `tv4.validate(data, schema)` in an environment where multiple validations might occur concurrently, leading to the global `tv4.error` property being overwritten.","error":"{ valid: false, error: { ... }, missing: [] } where error seems incorrect or refers to a previous validation."},{"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.","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.","error":"Validation passes (returns `true`) but some schemas referenced by `$ref` are not actually validated."},{"fix":"Set `tv4.banUnknownProperties = true;` globally or add `\"additionalProperties\": false` to your schema to disallow undeclared properties.","cause":"By default, `tv4` ignores properties not explicitly defined in the schema.","error":"JSON data contains an extra field not defined in the schema, but validation still passes."}],"ecosystem":"npm"}