Specifying Merge Versions

 Table of Contents

1. XML / JSON Requests

1.1. Concurrent

Concurrent Merge takes three or more versions, with one version treated as the "ancestor" or original to each of the other versions that are compared.

Each version needs a name, and an input. See I/O types for more information on sources of input.

As such, you can specify three or more versions, and the first in the set of versions will be treated as the ancestor. For example:

XML

Request
<ConcurrentMerge>
  <Versions>
    <Version type="file" name="anna">
      <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-anna.xml</Path>
    </Version>
    <Version type="file" name="ben">
      <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-ben.xml</Path>
    </Version>
    <Version type="file" name="chris">
      <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-chris.xml</Path>
    </Version>
  </Versions>
  ...
</ConcurrentMerge>

JSON

Request
{
  "Versions": [
    {
      "type": "file",
      "name": "anna",
      "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-anna.xml"
    },
    {
      "type": "file",
      "name": "ben",
      "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-ben.xml"
    },
    {
      "type": "file",
      "name": "chris",
      "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-chris.xml"
    }
  ],
  ...
}

1.2. Sequential

Like Concurrent Merge, Sequential Merge takes three or more versions, each with a name. These are then merged sequentially - in the order you specified, which needs to be the same as the order they were edited. The syntax for specifying versions in Sequential is the same as Concurrent:

XML

Request Excerpt
<SequentialMerge>
  <Versions>
    <Version type="file" name="anna">
      <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-anna.xml</Path>
    </Version>
    <Version type="file" name="ben">
      <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-ben.xml</Path>
    </Version>
    <Version type="file" name="chris">
      <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-chris.xml</Path>
    </Version>
  </Versions>
  ...
</SequentialMerge>

JSON

Request Excerpt
{
  "Versions": [
    {
      "type": "file",
      "name": "anna",
      "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/html-data/four-edits-anna.html"
    },
    {
      "type": "file",
      "name": "ben",
      "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/html-data/four-edits-ben.html"
    },
    {
      "type": "file",
      "name": "chris",
      "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/html-data/four-edits-chris.html"
    },
    {
      "type": "file",
      "name": "david",
      "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/html-data/four-edits-david.html"
    }
  ],
  ...
}

1.3. Three Way Merge

As the name suggests, there are only three versions in a Three Way Merge. We have simplified how to specify versions in Three Way Merge by explicitly naming the elements used:

XML

Request Excerpt
<ThreeWayMerge>
  <Ancestor type="file" name="anna">
    <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/html-data/four-edits-anna.html</Path>
  </Ancestor>
  <VersionOne type="file" name="ben">
    <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/html-data/four-edits-ben.html</Path>
  </VersionOne>
  <VersionTwo type="file" name="chris">
    <Path>/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/html-data/four-edits-chris.html</Path>
  </VersionTwo>
  ...
</ThreeWayMerge>


JSON

Request Excerpt
{
  "Ancestor": {
    "type": "file",
    "name": "anna",
    "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-anna.xml"
  },
  "VersionOne": {
    "type": "file",
    "name": "ben",
    "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-ben.xml"
  },
  "VersionTwo": {
    "type": "file",
    "name": "chris",
    "Path": "/usr/local/deltaxml/DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-chris.xml"
  },
  ...
}

2. multipart/form-data Requests

2.1. Concurrent and Sequential

When using Concurrent or Sequential Merge, the part name is used as the version identifier in the merge - i.e. enter any valid name NMTOKEN isn't a parameter otherwise used by XML Merge REST e.g. Async.

There is an additional parameter, VersionOrder, used with multipart/form-data to clarify the order of the versions - a comma separated list of the version names.

In Concurrent Merge the first item in this list will be assumed to be the ancestor.

...
Content-Disposition: form-data; name="base"
http://www.example.com/file1.xml
--boundary
Content-Disposition: form-data; name="anna"
http://www.example.com/file2.xml
--boundary
Content-Disposition: form-data; name="ben"
http://www.example.com/file3.xml
--boundary
Content-Disposition: form-data; name="VersionOrder"
base,anna,ben
--boundary
...

2.2. Three Way Merge

This is similar to an XML or JSON request - there are predefined part names for Ancestor, VersionOne, and VersionTwo. There are additional optional parameters corresponding to each input's version identifier e.g. AncestorName.

If names aren't specified then the values "Ancestor", "VersionOne" and "VersionTwo" will be used.

...
Content-Disposition: form-data; name="Ancestor"
http://www.example.com/file1.xml
--boundary
Content-Disposition: form-data; name="AncestorName"
base
--boundary
Content-Disposition: form-data; name="VersionOne"
http://www.example.com/file2.xml
--boundary
Content-Disposition: form-data; name="VersionOneName"
anna
--boundary
Content-Disposition: form-data; name="VersionTwo"
http://www.example.com/file3.xml
--boundary
Content-Disposition: form-data; name="VersionTwoName"
ben
--boundary
...
#content .code