json-schema-diff

library1.0.0jsnpmunverified

A CLI tool and Node.js API for computing the difference between two JSON Schema files (draft-07). Version 1.0.0 supports Node.js >=18.18.0 and ships TypeScript definitions. Unlike generic JSON diff tools, this library performs a semantic diff based on set theory, classifying changes as additions (more permissive) or removals (more restrictive), outputting JSON Schema representations of the added/removed value sets. It is designed for schema migration validation and CI workflows where breaking changes must be flagged.

testing devops

npm install json-schema-diff

package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-DIFF

json-schema-diff

testingjavascriptv1.0.0

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.

diffSchemas

✓ import { diffSchemas } from 'json-schema-diff'

✗ const jsonSchemaDiff = require('json-schema-diff'); jsonSchemaDiff.diffSchemas(...);

ESM-only starting v1.0.0 (package type: module). The CommonJS require pattern works via default export but named exports like diffSchemas require named import.

DiffResult

✓ import type { DiffResult } from 'json-schema-diff'

TypeScript users should import the type for the result object. Available since v1.0.0.

default (namespace)

✓ import jsonSchemaDiff from 'json-schema-diff'

✗ const jsonSchemaDiff = require('json-schema-diff')

CJS require works on the default export, but named exports like diffSchemas are preferred. Use import * as jsonSchemaDiff from 'json-schema-diff' for namespace.

Compares two JSON Schema objects using async diffSchemas, logs removal (breaking) and addition (non-breaking) diff schemas.

import { diffSchemas } from 'json-schema-diff'; import { readFileSync } from 'fs'; async function main() { const source = JSON.parse(readFileSync('source.json', 'utf8')); const destination = JSON.parse(readFileSync('destination.json', 'utf8')); const result = await diffSchemas({ sourceSchema: source, destinationSchema: destination }); if (result.removalsFound) { console.log('Breaking changes detected (removals):', JSON.stringify(result.removed, null, 2)); } if (result.additionsFound) { console.log('Non-breaking changes (additions):', JSON.stringify(result.added, null, 2)); } } main().catch(console.error);

Debug

Known issues

breakingNode.js engine requirement: >=v18.18.0. Older Node versions will crash with syntax errors or module resolution failures.

fix

Upgrade Node.js to v18.18.0 or later, or use nvm to switch versions.

affects: <18.18.0

gotchaThe CLI exits with non-zero code if any removals (breaking changes) are detected. This may break CI pipelines unintentionally if the destination schema is meant to have removals.

fix

In CI, either ensure no removals are introduced, or capture exit code and handle intentionally (e.g., by allowing exit code 1 in script).

affects: >=1.0.0

deprecatedThe README mentions Node.js >=10 support and CommonJS require, but v1.0.0 is ESM-only with Node >=18.18.0. The documentation is outdated.

fix

Use ESM imports and Node >=18.18.0. Refer to the actual package.json or source for correct requirements.

affects: >=1.0.0

gotchaOnly supports JSON Schema draft-07. Schemas using draft-04, draft-06, or 2020-12 may produce incorrect diffs or throw errors.

fix

Convert schemas to draft-07 before diffing, or use a library that supports multiple drafts.

affects: >=1.0.0

gotchaThe diff algorithm may have edge cases with recursive schemas or unknown keywords. Not all JSON Schema keywords are supported; see KEYWORDS.md.

fix

Validate that both schemas use only supported keywords. Test thoroughly with your schema patterns.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/path/to/json-schema-diff' imported from ...

ESM resolution fails when using require() or incorrect import path.

fix

Use ESM import: import { diffSchemas } from 'json-schema-diff'; Ensure package.json has 'type': 'module' or use .mjs extension.

TypeError: jsonSchemaDiff.diffSchemas is not a function

CommonJS require returns the default export, not a named export object.

fix

Use import jsonSchemaDiff from 'json-schema-diff'; then jsonSchemaDiff.diffSchemas(...) OR use named import: import { diffSchemas } from 'json-schema-diff';

Error: The source/destination schema must be a valid JSON Schema object.

Input is not a plain object or is null/undefined.

fix

Ensure inputs are parsed JavaScript objects (e.g., JSON.parse() result) and not strings or arrays.

Error: Unsupported schema keyword: $ref

The library does not handle $ref by default; it treats it as unknown.

fix

Resolve $ref externally before diffing, or use a different library that supports references.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

packagejson-schema-diff ↗

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