The DeltaJSON Delta Format

Introduction

A JSON Delta is a JSON file which describes the differences between two JSON files. The structure of the delta is similar to that of the inputs, but additional objects are introduced to describe changes.

A delta is also used as the changeset input to the graft operation and conformance to the format described here is required for successful graft operations.

Format

The delta itself is an object which contains one child member with key: dx_deltaJSON.

The value of this member is an object itself containing four objects:

• Key: dx_data_sets – the equality of the overall inputs, can have the value A=B indicating both documents are equal, or A!=B indicating there is at least one change between inputs.

• Key: dx_deltaJSON_delta - stores the main heart of the delta, the data itself.

• Key: dx_deltaJSON_type - stores the type of delta. Can have the value diff for a comparison, or graft when using Three-Way Merge with showConflicts output.

• Key: dx_deltaJSON_metadata - stores metadata of the operation performed.

Metadata

The dx_deltaJSON_metadata object itself contains two child members, with keys operation and parameters.

The value of operation is an object whose child members have keys type, input-format and output-format. These child members store the type of comparison (e.g. merge), format the data was transmitted (e.g. multi_part_uris for JSON transmitted via multi-part form data containing URIs to JSON files), and output format (can be either JSON or XML depending on format requested).

The value of parameters is an object whose child members store the parameters used for the operation. E.g., if the Word by Word parameter was set to true, it will contain a member with key wordbyword and value true.

Delta Objects

The primary object used to describe changes has a key of dx_delta.

This contains a child object with one or two members with keys "A" and/or "B" which refer to the two inputs of the comparison. The "A" and "B" values then contain the content which is unique to the corresponding input.

The dx_delta object is used at the point in the structure at which the difference is detected. In trivially simple cases this could be the root node of the JSON structure, otherwise it will typically be found inside an array or object.

There is also an object with key dx_delta_string used when Word by Word comparison is set to true. The dx_delta_string object contains an array of items comprising strings and dx_delta objects.

Delta Types

There are currently two types of delta – full context, and three-way merge conflicts.

Full Context

Contains all the data from both inputs. The original inputs can be extracted from this file.

Three-Way Merge Conflicts

When using Three-Way Merge with threeWayMergeMode set to showConflicts, the result is returned in delta format with conflicts annotated in suitable delta elements.

Examples

dx_delta

Given the following inputs

The change is represented by the following structure:

dx_deltaJSON_delta

{
  "dx_delta": {
    "A": 1,
    "B": 2
  }
}

dx_delta_string

Given the following inputs

The outputs using different settings of the Word By Word parameter are as follows:

dx_deltaJSON_delta (with Word by Word set to false)

{
  "dx_delta": {
    "A": "This is a good example of Word by Word processing.",
    "B": "This is a great example of Word by Word processing."
  }
}

dx_deltaJSON_delta (with Word by Word set to true)

{
  "dx_delta_string": [
    "This is a ",
    {
      "dx_delta": {
        "A": "good",
        "B": "great"
      }
    },
    " example of Word by Word processing."
  ]
}

Full Delta

Using the inputs from the previous example a full delta file including meta data would be as follows:

Full Delta for the previous example (with Word by Word set to false)

{
  "dx_deltaJSON": {
    "dx_data_sets": "A!=B",
    "dx_deltaJSON_type": "diff",
    "dx_deltaJSON_metadata": {
      "operation": {
        "type": "compare",
        "input-format": "multi_part_strings",
        "output-format": "JSON"
      },
      "parameters": {
        "wordByWord": false,
        "arrayAlignment": "typeWithValuePriority"
      }
    },
    "dx_deltaJSON_delta": {
      "dx_delta": {
        "A": "This is a good example of Word by Word processing.",
        "B": "This is a great example of Word by Word processing."
      }
    }
  }
}