{"id":48268,"library":"json-schema-diff-validator","title":"json-schema-diff-validator","description":"A CLI and library for detecting breaking changes between two versions of a JSON Schema. v0.4.2 (latest), released occasionally. It checks schema files or objects for removed nodes, replaced nodes, and new required nodes. Offers options to allow new oneOf/anyOf items, new enum values, and reordering as backward-compatible. Ships TypeScript types. Differentiates by focusing on schema backward compatibility specifically, with a simple CLI interface.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install json-schema-diff-validator","lang":"bash","label":"npm"},{"cmd":"yarn add json-schema-diff-validator","lang":"bash","label":"yarn"},{"cmd":"pnpm add json-schema-diff-validator","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package ships CommonJS, but ESM imports may work with bundlers. TypeScript types are included.","wrong":"const validateSchemaFiles = require('json-schema-diff-validator').validateSchemaFiles","symbol":"validateSchemaFiles","correct":"import { validateSchemaFiles } from 'json-schema-diff-validator'"},{"note":"Named export for comparing JSON objects.","symbol":"validateSchemaCompatibility","correct":"import { validateSchemaCompatibility } from 'json-schema-diff-validator'"},{"note":"Default import is an object with methods validateSchemaFiles and validateSchemaCompatibility. Works in TypeScript as well.","wrong":"const jsonSchemaDiffValidator = require('json-schema-diff-validator')","symbol":"default import","correct":"import jsonSchemaDiffValidator from 'json-schema-diff-validator'"}],"quickstart":{"code":"import { validateSchemaFiles, validateSchemaCompatibility } from 'json-schema-diff-validator';\n\n// Using CLI (globally installed):\n// json-schema-diff-validator old.json new.json\n\n// Validate files:\ntry {\n  validateSchemaFiles('old_schema.json', 'new_schema.json');\n  console.log('No breaking changes');\n} catch (error) {\n  console.error(error.message);\n}\n\n// Validate JSON objects:\nconst oldSchema = { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] };\nconst newSchema = { type: 'object', properties: { name: { type: 'string' } } }; // removed required\n\ntry {\n  validateSchemaCompatibility(oldSchema, newSchema);\n  console.log('Compatible');\n} catch (error) {\n  console.error(error.message);\n}","lang":"typescript","description":"Shows how to use validateSchemaFiles and validateSchemaCompatibility for file and object validation, including error handling."},"warnings":[{"fix":"Use additional schema validation tools to check for other backward-compatibility rules.","message":"The package only detects breaking changes based on removed, replaced, and new required nodes. Changes like relaxing constraints (e.g., removing 'required') are NOT flagged.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Wrap CLI in try/catch in shell scripts; use the library programmatically to handle errors gracefully.","message":"CLI returns exit code 0 for compatible, but throws an exception for breaking changes. This may break scripts expecting non-zero exit code.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use the package as a library to pass options object.","message":"Options like allowNewOneOf, allowNewEnumValues, and allowReorder are only available via the programmatic API, not via CLI flags.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use the correctly named exports: validateSchemaFiles, validateSchemaCompatibility.","message":"The npm description suggests a non-existent function 'difftool.validateSchemaCompatibility' is misspelled (validateSchemaCompatibility vs validateSchemaCompatibility).","severity":"deprecated","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'allow':43 'backward':54,64 'backward-compat':53 'break':12 'chang':13 'check':26 'cli':7,70 'compat':55,65 'detect':11 'diff':4 'differenti':59 'enum':48 'file':28 'focus':61 'interfac':71 'item':46 'javascript':72 'json':2,19 'json-schema-diff-valid':1 'latest':22 'librari':9 'new':37,44,47 'node':33,35,39 'object':30 'occasion':24 'offer':40 'oneof/anyof':45 'option':41 'releas':23 'remov':32 'reorder':51 'replac':34 'requir':38 'schema':3,20,27,63 'ship':56 'simpl':69 'specif':66 'two':15 'type':58 'typescript':57,73 'v0.4.2':21 'valid':5 'valu':49 'version':16","created_at":"2026-06-07T16:55:45.209263+00:00","updated_at":"2026-06-07T16:55:45.209263+00:00","problems":[{"fix":"Ensure both schemas have the same properties; if removal is intentional, note it as breaking.","cause":"One schema has a property removed compared to the other.","error":"Error: The schema is not backward compatible. Difference include breaking change = [{\"op\":\"remove\",\"path\":\"/properties/name\"}]"},{"fix":"Use correct import: import { validateSchemaFiles } from 'json-schema-diff-validator' or const { validateSchemaFiles } = require('json-schema-diff-validator').","cause":"Incorrect import: using default import but calling as named import, or using CommonJS incorrectly.","error":"TypeError: validateSchemaFiles is not a function"},{"fix":"Run npm install json-schema-diff-validator","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'json-schema-diff-validator'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://bitbucket.org/atlassian/json-schema-diff-validator#readme","github":null,"docs":null,"changelog":null,"pypi":null,"npm":"json-schema-diff-validator","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}