User Guide

Introduction

This User Guide outlines the DeltaJSON product, with links to more detailed documentation.  It describes what DeltaJSON is, what it can be used for and how DeltaJSON operations are invoked. 

The DeltaJSON Product

At the core of DeltaJSON is a JSON comparator that can, by understanding the semantics of JSON structures, provide more optimal comparison results than a line-by-line comparison.  DeltaJSON uses the JSON comparator to provide a number of operations that are used to identify and manage differences between two or more JSON input files. DeltaJSON operations are invoked via a REST API.

A Cross-Platform REST Service

DeltaJSON is a cross-platform Java product that runs as an HTTP REST service. All DeltaJSON operations are invoked using REST API calls, allowing integration with a wide range of other languages and systems. There are two distinct modes of HTTP REST operation:

• Synchronous - The HTTP response is the result of the REST request

• Asynchronous - The HTTP response is a 'job number'. The job number is then used in further REST requests until the job is complete.

DeltaJSON Operations

The DeltaJSON comparison-based operations are outlined in the list below:

• Comparison will compare two input files and produce a result file which may be a full delta or just the changes. See Compare Guide.

• Two-way merge produces a merged JSON file from two JSON inputs by resolving the changes with respect to a specific version. See the Two Way Merge guide.

• Patch generates a JSON Patch result in RFC6902 JSON Patch format. See Patch Guide.

• Three-way concurrent merge represents the conflicts or resolves all the changes in two input JSON files derived from an ancestor file independently. See Three Way Merge guide.

• Graft takes the result of a comparison between two files as a delta and applies the changes to a third related file to update it in a similar way. See Graft Guide.

Features

Additional settings in DeltaJSON operations provide control on specific features that DeltaJSON exploits. These features control how parts of JSON inputs are compared and processed.

The DeltaJSON features are listed below, these include links to sections that provide more detail

• Array Alignment - control how array items are matched by the JSON comparator

• Ignore Changes - ignore differences for specific key-values in a JSON object

• Word by Word - control whether differences between string values are shown at the word-level instead of for the whole string

• Output Formats - control the format of the result

Comparison Result Details

In the comparison result, there is different lexical treatment for specific JSON types, these differences are detailed in the sections linked below:

• Boolean Comparisons

• Character Escape Codes

• Number Precision

• Unicode Characters

Using DeltaJSON

Starting up the REST Server

First ensure that you have a license installed and have Java 8 up to Java 13. Versions later than 13 are not currently officially supported.

The DeltaJSON REST Server must be started before operations can be invoked.

Invoking DeltaJSON operations with the sample REST Clients

To assist with evaluation and one-off operations, a number of REST Clients for different languages/platforms are available

A Postman Collection is also available: Testing Using Postman This provides a set of REST request configurations for invoking DeltaJSON operations using the Postman API Client.

Processing/Rendering DeltaJSON Results

The output from a DeltaJSON operation is a JSON or XML format that includes information on unresolved differences. The output formats available depend on the type of DeltaJSON operation you are performing. The primary output format is the DeltaJSON Delta Format.

Sample solutions for processing the DeltaJSON Delta Format are available:

• DeltaJSON_TypeScript_API - a TypeScript based sample demonstrating interacting with and displaying DeltaJSON results

How to Use DeltaJSON REST Service

There are various way of running the DeltaJSON. They are listed bellow:

• Using REST Service

• Command Line Interface

Free Usage Tier

The free usage tier allows evaluation and experimentation prior to large scale deployments using future paid tiers or on-premise deployments. It also allow small-scale production use, but without any service level agreements or other guarantees of service availability or provision. For more information see: Free Usage Tier

Experimentation using the Web Client

A web client is available that allows developers to explore the capabilities of our change representation or 'delta format' for JSON. It allow developers to paste or drag-and-drop small JSON examples (see: Free Usage Tier) and see various linked representations of those inputs and the comparison results so that where changes are reported in the delta the corresponding locations of the data in the inputs are also highlighted.

We recommend using this web client in conjunction with our format documentation when exploring and experimenting with our change representations.

There is also documentation for this client.

Experimentation using Postman

We have provided a Postman Collection that allows easy experimentation of REST requests and responses with simple example data. It has been documented here.

Licensing and legal notices

The DeltaXML software is licensed under the terms described in the file Licence.html. The software also includes components developed by others, the redistribution and copyright terms, including necessary notices are described in legal-notices.html

Support

Please raise issues related to our sample clients and applications on their respective Bitbucket issue trackers. For issues relating to the service itself and questions about the change representation and its application we have a dedicated support channels.