Registry / devops / json-schema-diff-validator

json-schema-diff-validator

library0.4.2jsnpmunverified

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.

devops

npm install json-schema-diff-validator

package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-DIFF-V

json-schema-diff-validator

devopsjavascriptv0.4.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

validateSchemaFiles

✓ import { validateSchemaFiles } from 'json-schema-diff-validator'

✗ const validateSchemaFiles = require('json-schema-diff-validator').validateSchemaFiles

Package ships CommonJS, but ESM imports may work with bundlers. TypeScript types are included.

validateSchemaCompatibility

✓ import { validateSchemaCompatibility } from 'json-schema-diff-validator'

Named export for comparing JSON objects.

default import

✓ import jsonSchemaDiffValidator from 'json-schema-diff-validator'

✗ const jsonSchemaDiffValidator = require('json-schema-diff-validator')

Default import is an object with methods validateSchemaFiles and validateSchemaCompatibility. Works in TypeScript as well.

Shows how to use validateSchemaFiles and validateSchemaCompatibility for file and object validation, including error handling.

import { validateSchemaFiles, validateSchemaCompatibility } from 'json-schema-diff-validator'; // Using CLI (globally installed): // json-schema-diff-validator old.json new.json // Validate files: try { validateSchemaFiles('old_schema.json', 'new_schema.json'); console.log('No breaking changes'); } catch (error) { console.error(error.message); } // Validate JSON objects: const oldSchema = { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }; const newSchema = { type: 'object', properties: { name: { type: 'string' } } }; // removed required try { validateSchemaCompatibility(oldSchema, newSchema); console.log('Compatible'); } catch (error) { console.error(error.message); }

Debug

Known issues

gotchaThe package only detects breaking changes based on removed, replaced, and new required nodes. Changes like relaxing constraints (e.g., removing 'required') are NOT flagged.

fix

Use additional schema validation tools to check for other backward-compatibility rules.

affects: >=0.0.0

gotchaCLI returns exit code 0 for compatible, but throws an exception for breaking changes. This may break scripts expecting non-zero exit code.

fix

Wrap CLI in try/catch in shell scripts; use the library programmatically to handle errors gracefully.

affects: >=0.0.0

gotchaOptions like allowNewOneOf, allowNewEnumValues, and allowReorder are only available via the programmatic API, not via CLI flags.

fix

Use the package as a library to pass options object.

affects: >=0.0.0

deprecatedThe npm description suggests a non-existent function 'difftool.validateSchemaCompatibility' is misspelled (validateSchemaCompatibility vs validateSchemaCompatibility).

fix

Use the correctly named exports: validateSchemaFiles, validateSchemaCompatibility.

affects: >=0.1.0

Errors

Common errors & fixes

Error: The schema is not backward compatible. Difference include breaking change = [{"op":"remove","path":"/properties/name"}]

One schema has a property removed compared to the other.

fix

Ensure both schemas have the same properties; if removal is intentional, note it as breaking.

TypeError: validateSchemaFiles is not a function

Incorrect import: using default import but calling as named import, or using CommonJS incorrectly.

fix

Use correct import: import { validateSchemaFiles } from 'json-schema-diff-validator' or const { validateSchemaFiles } = require('json-schema-diff-validator').

Error: Cannot find module 'json-schema-diff-validator'

Package not installed or not in node_modules.

fix

Run npm install json-schema-diff-validator

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

packagejson-schema-diff-validator ↗

homepagehttps://bitbucket.org/atlassian/json-schema-diff-validator#readme ↗