JSON Compare Features

1. Word By Word

For Compare and Two-Way Merge operations there is an option to control the granularity the operation is performed at. This parameter by default is set to false - i.e. searches for full string equality. When set to true, it allows a more granular word level comparison.

It is similar to the Word By Word feature in our existing Compare products.

Input AInput B
This is a good example of Word by Word comparison.This is great example of Word by Word comparison.

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

dx_deltaJSON_delta (with Word by Word = 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 = true)
{
  "dx_delta_string": [
    "This is a ",
    {
      "dx_delta": {
        "A": "good",
        "B": "great"
      }
    },
    " example of Word by Word processing."
  ]
}

2. Array Alignment

This parameter (by default "Type with Value Priority" ) gives you control over how items in arrays are matched for comparison.

Array items can be aligned currently in three ways:

  • Type with Value Priority - Alignment will be by equality first (same type and value), then by type but items of different type will not align
  • Position Priority - Alignment will be by item position in the array
  • Orderless - Alignment will be by exact equality for items. I.e., two arrays containing the same items but in a different order will match with no changes.

Let's look at an example comparing the following arrays:

Input AInput B
[ 116, 943, 234, 38793 ][ 200, "ABC", "DEF", 234, 38793 ]

Array Alignment by Type with Value Priority would result in the following comparisons and delta representation

A     [ 116, 943,                234, 38793 ]
         |                        |     |
B     [ 200,      "ABC", "DEF",  234, 38793 ]
Delta
[
  {
    "dx_delta": {
      "A": 116,
      "B": 200
    }
  },
  {
    "dx_delta": {
      "A": 943
    }
  },
  {
    "dx_delta": {
      "B": "ABC"
    }
  },
  {
    "dx_delta": {
      "B": "DEF"
    }
  },
  234,
  38793
]

Array Alignment by Position would result in the following comparisons and delta representation

A     [ 116,  943,   234, 38793          ]
         |     |      |     |
B     [ 200, "ABC", "DEF", 234,    38793 ]
Delta
[
  {
    "dx_delta": {
      "A": 116,
      "B": 200
    }
  },
  {
    "dx_delta": {
      "A": 943,
      "B": "ABC"
    }
  },
  {
    "dx_delta": {
      "A": 234,
      "B": "DEF"
    }
  },
  {
    "dx_delta": {
      "A": 38793,
      "B": 234
    }
  },
  {
    "dx_delta": {
      "B": 38793
    }
  }
]

In this example, Array Alignment by Orderless would result in a "changes only" delta indicating zero change.

Input AInput B
["ABC", "DEF", 234, 200, 38793][200, "ABC", "DEF", 234, 38793]

Delta
{
 "dx_deltaJSON": {
  ...
  "dx_deltaJSON_metadata": {
   ...

   "parameters": {
    ...
    "arrayalignment": "ORDERLESS",
    "output": "CHANGES_ONLY"
   }
  },
  "dx_deltaJSON_delta": []
 }
}

3. Number Precision

Numbers are normalized prior to comparison so that different lexical forms of the same logical number will not be reported as a difference, for example the following pairs of numbers will be considered similar:

  • 1 and 1.00
  • 1.00 and 1.000
  • 100 and 1e2

4. Boolean

In JSON true and false are separate values, but most developers consider them in the same way booleans are treated in other languages. As such, we match true against false:

Input AInput B
truefalse

dx_deltaJSON_delta
{
  "dx_delta": {
    "A": true,
    "B": false
  }
}

5. Character Escape Codes

The standard escape codes supported in JSON are supported:

  • Quote Mark: \"
  • Reverse Solidus: \\
  • Solidus: \/
  • Backspace: \b
  • Form Feed: \f
  • New Line: \n
  • Carriage Return: \r
  • Tab: \t

6. Unicode Characters

In some cases unicode character sequences in the JSON inputs are not lexically retained in the delta output but are converted into equivalent characters, for example:

Input AInput B
"Here are some apostrophes ( ' and ' and \u0027 )""Here are some apostrophes ( ' and ' and \u0027 )"

dx_deltaJSON_delta
"Here are some apostrophes ( ' and ' and ' )"

7. Input Format

There are three ways to input data to the API:

  1. Raw JSON specified in Multi-Part Form Data
  2. URIs to JSON data specified in Multi-Part Form Data
  3. URIs to JSON data specified within a JSON object

8. Output Format

Output can be specified in JSON (default) or XML format. The XML format is the JSON result converted to XML using XSLT 3.0's json-to-xml() function.

9. Ignore Changes

Values can be ignored (they will be deleted) by passing a JSON object to the parameter dx_config with a value containing an array of configuration instructions. Currently the only instruction supported is the ignorechanges instruction. You specify keys of values to ignore. For ease of use with the command line clients, we have provided a parameter to input this as a file. Simply store your dx_config instructions in a JSON file, and they can be easily re-used with different calls. An example of the format is below:

Input AInput B
{
 "created":"2017-01-31T16:55:25.700Z",
 "description": "This is an example of dx_config"
}
{
 "created":"2016-05-12T13:15:23.700Z",
 "description": "This is an example of ignorechanges"
}

dx_config
{
 "dx_config": [
  {
   "ignorechanges": "delete",
   "key": "created"
  }
 ]
}

The value of "created" has changed but is not present in the output:
dx_deltaJSON_delta
{
 "description": {
  "dx_delta": {
   "A": "This is an example of dx_config",
   "B": "This is an example of ignorechanges"
  }
 }
}