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.
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.
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:
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
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:
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
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.