Two Way Merge Guide

Two-way merge is effectively a resolved comparison, where changes have been resolved to a specified version. The merge priority can be set to 'b' and the default is 'a'.

For request details see Two Way Merge Request

The following shows the results of merging two files with all the default priorities, (mergePriority = a, wordByWord=true and arrayAlignment= typeWithValuePriority)

Input A

JSON

{
  "a": "your data",
  "b": "bbc 1",
  "name": "John Joe Smith",
  "age": 21,
  "owner": true
}

Input B

JSON

{
  "a": "my data",
  "b": "bbc 2",
  "name": "Mr John Smith",
  "age": 22,
  "pet": "dog"
}

Result

JSON

{
    "a": "your data",
    "b": "bbc 1",
    "name": "Mr John Joe Smith",
    "age": 21,
    "pet": "dog",
    "owner": true
}

As you can see, because merge priority is given to 'a', the values in Input A override those in 'b'. Any new values in 'b', such as the pet dog, will appear in the result. The order of objects may vary. When wordByWord is true this allows John Joe Smith to match Mr John Smith and this string is merged into Mr John Joe Smith.

The word by word parameter operates in the same way as for compare, see Word by Word.

Similarly for array alignment which has full details on this page: Array Alignment. If an array contains sentences then the setting for wordByWord may affect whether those sentences will match other similar sentences. See the examples below.

Array Alignment Settings

orderless

You need to be careful when using the orderless setting in conjunction with wordByWord. This is because wordByWord splits up a string into word, space and punctuation parts. The heuristic algorithm sees each of these parts as independent. It will attempt to match strings based on what parts that these strings have in common. Each string will be matched against all the strings in the array from the other input. This is useful when attempting to match a JSON array of natural language phrases. For example:

a

JSON

{
  "a": "my data",
  "hobbies": [
    "reading",
    "playing guitar badly",
    "cinema"
  ]
}

b

JSON

{  
  "a": "your data",
  "hobbies": [
    "badminton",
    "guitar",
    "reading",
    "bird-watching"
  ]
}

When wordByWord is true then 'playing guitar badly' matches 'guitar' and only appears once:

Result with word-by-word set to true

JSON

{
    "a": "my data",
    "hobbies": [
        "reading",
        "playing guitar badly",
        "cinema",
        "badminton",
        "bird-watching"
    ]
}

When it is false then both appear:

Result with word-by-word set to false

JSON

{
    "a": "my data",
    "hobbies": [
        "reading",
        "playing guitar badly",
        "cinema",
        "badminton",
        "guitar",
        "bird-watching"
    ]
}

However it may give unexpected results when applied to identifiers; "A/B" will match with "C/B" and "A/D" for example because wordByWord will split them into letters and the '/' character.

a

JSON

{
    "a": "my data",
    "identifiers": [
        "X/Y",
        "A/B",
        "P/Q"
    ]
}

b

JSON

{
  "a": "your data",
  "identifiers": [
    "X/Y",
    "C/B",
    "P/Z"
  ]
}

Result with wordByWord set to true

JSON

{
    "a": "my data",
    "identifiers": [
        "X/Y",
        "A/B",
        "P/Q"
    ]
}

In this case, when wordByWord is false then all five identifiers appear in the result ("X/Y", "A/B", "P/Q", "C/B", "P/Z")

We recommend to only switch on wordByWord if your data consists of reasonably-sized natural language strings, particularly when arrayAlignment is orderless.

positionPriority

With this setting, array alignment is simply by position in the array.

JSON

{
    "a": "my data",
    "hobbies": [
        "reading",
        "playing guitar badly",
        "cinema",
        "bird-watching"
    ]
}

typeWithValuePriority

Note that the position is still important.

JSON

{
    "a": "my data",
    "hobbies": [
        "badminton",
        "guitar",
        "reading",
        "playing guitar badly",
        "cinema",
        "bird-watching"
    ]
}