json-schema-diff

What is json-schema-diff?

The json-schema-diff npm package is a tool for comparing JSON schemas. It helps identify differences between two JSON schemas, which can be useful for versioning, migration, and ensuring compatibility between different versions of APIs or data structures.

What are json-schema-diff's main functionalities?

Compare JSON Schemas

This feature allows you to compare two JSON schemas and identify the differences between them. The code sample demonstrates how to use the json-schema-diff package to compare two schemas and print the differences.

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

const schema1 = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  },
  required: ['name']
};

const schema2 = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' },
    email: { type: 'string' }
  },
  required: ['name', 'email']
};

jsonSchemaDiff.diffSchemas({
  sourceSchema: schema1,
  destinationSchema: schema2
}).then((diff) => {
  console.log(JSON.stringify(diff, null, 2));
}).catch((error) => {
  console.error(error);
});

Other packages similar to json-schema-diff

json-diff

The json-diff package provides a way to compare two JSON objects and highlight the differences. While it is not specifically designed for JSON schemas, it can be used to compare any JSON data structures. It is more general-purpose compared to json-schema-diff, which is specialized for JSON schema comparison.

deep-diff

The deep-diff package allows for deep comparison of JavaScript objects, including JSON objects. It can be used to find differences between two objects at any depth. Similar to json-diff, it is not specialized for JSON schemas but can be used for a wide range of JSON data comparisons.

diff

The diff package is a general-purpose text comparison tool that can be used to compare JSON strings. It provides a variety of diff algorithms and output formats. While it is not specifically designed for JSON schemas, it can be used to compare JSON data by converting it to strings.

README

Json Schema Diff

A language agnostic CLI tool and nodejs api to identify differences between two json schema files.

Requirements

• nodejs 6.x or higher (tested using 6.x, 8.x and 9.x)
• npm 2.x or higher (tested using 2.x, 3.x and 5x)

Installation

Install the tool using npm and add it to the package.json

npm install json-schema-diff --save-dev

Usage

This tool identifies differences between two json schema files. KEYWORDS.md contains the details of what json schema keywords are supported. Differences are classified into two broad groups, added and removed.

Added differences are areas where the destination schema has become more permissive relative to the source schema. For example {"type": "string"} -> {"type": ["string", "number"]}.

Removed differences are areas where the destination schema has become more restrictive relative to the source schema. For example {"type": ["string", "number"]} -> {"type": "string"}.

Usage as a cli tool

Invoke the tool with a file path to the source schema file and the destination schema file. These files should be in JSON format and be valid according to the json schema draft-07 specification.

The tool will return two json schemas as output, one representing the values that were added by the destination schema and the other representing the values that were removed by the destination schema.

The tool will fail if any removed differences are detected.

Example

/path/to/source-schema.json

{
  "type": "string"
}

/path/to/destination-schema.json

{
  "type": ["string", "number"]
}

Invoking the tool

json-schema-diff /path/to/source-schema.json /path/to/destination-schema.json

Output

Non-breaking changes found between the two schemas.

Values described by the following schema were added:
{
    "type": [
        "number"
    ]
}

Values described by the following schema were removed:
false

Usage as a nodejs api

Invoke the library with the source schema and the destination schema. These objects should be simple javascript objects and be valid according to the json schema draft-07 specification.

For full details of the nodejs api please refer to api-types.d.ts

Example

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

const source = {type: 'string'};
const destination = {type: ['string', 'number']};

const result = await jsonSchemaDiff.diffSchemas({
    sourceSchema: source, 
    destinationSchema: destination
});

if (result.removalsFound) {
    console.log('Something was removed!');
}

if (result.additionsFound) {
    console.log('Something was added!');
}

Changelog

See CHANGELOG.md

Contributing

See CONTRIBUTING.md

License

See LICENSE.txt

Changelog

0.9.0 (2019-02-07)

Features

• add support for required keyword (2290b74)

BREAKING CHANGES

• Prior to this change the nodejs api returned added and removed differences detected as as an array of DiffResultDifference objects. Now the added and removed differences are returned as two seperate JsonSchema objects. In addition all the property names of the DiffResult object have been renamed. To migrate, update code that consumes the DiffResult object returned by the API to the new property names and types.

<a name="0.8.3"></a>