Skip to main content
Skip table of contents

Specifying Comparisons

To invoke a comparison you POST parameters to the specified DITA Compare pipeline, in either JSON or XML form.

Comparison Example

Here is a simple synchronous example (asynchronous comparison is detailed in more detail on this page):

Request (XML)
XML
<comparison>
  <inputA type="file">
    <path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputA.dita</path>
  </inputA>
  <inputB type="file">
    <path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputB.dita</path>
  </inputB>
  <configuration type="file">
    <path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/config.xml</path>
  </configuration>
</comparison>
Request (JSON)
JSON
{
  "inputA": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputA.dita"
  },
  "inputB": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputB.dita"
  },
  "configuration": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/config.xml"
  }
}

The response below indicates the comparison result, in this case an DITA topic describing the changes between the inputs specified in the request.

Response
XML
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/topic.dtd">
<topic id="topic-1">
  <title>DeltaXML DITA Compare - taking control of document changes </title>
  <body>
    <p status="unchanged">This sample document shows some of the benefits of DeltaXML DITA
        Compare, which shows revisions in all your DITA documents. DeltaXML DITA Compare takes
        the pain out of tracking and documenting changes in all DITA documents.</p>
    <p status="unchanged">You can simply execute DeltaXML DITA Compare and provide it with two
        versions of, say, a DITA topic and it will generate a new topic file which shows all the
        changes. Added, deleted and changed text will be highlighted. This simple example shows
        how this works.</p>
    <p>This document represents Version <ph status="deleted" rev="deltaxml-delete">1</ph><ph
            status="new" rev="deltaxml-add">2</ph>. You will see that when 'Version 1' is
        changed to 'Version 2', the change is shown.</p>
  </body>
</topic>

Comparison Model

When specifying a comparison, these are the various available objects:

Object

Description

inputA

(required)

Input A to the comparison.

See this page for the various I/O types available. 

inputB

(required)

Input B to the comparison.

See this page for the various I/O types available. 

configuration

Configuration to the comparison

See this page for the various I/O types available.

catalog

File path or HTTP URI pointing to catalog file(s).

See this page for the various I/O types available.

async

output

Specification of where the comparison result will be written.

See this page for the various I/O types available. 

callback

URL that will be polled after the comparison is complete.

See Callbacks in Async for more information.

Form Input

In addition to requests in structured XML or JSON format, multipart/form-data can also be used.

For example:

Request
CODE
POST /api/dita-compare/v1/compare/topic
Content-Type: multipart/form-data; boundary=boundary-id
Content-Length: number_of_bytes_in_entire_request_body

--boundary-id
Content-Disposition: file; filename="file1.dita"
Content-Size: 98344
Content-Type: application/xml

... XML  ...
--boundary-id
Content-Disposition: file; filename="file2.dita"
Content-Size: 92224
Content-Type: application/xml

... XML  ...
--boundary-id
Content-Disposition: file; filename="configuration.xml"
Content-Size: 32224
Content-Type: application/xml

... XML  ...
--boundary-id

Content-Disposition: form-data; name="async"
true
--boundary-id

The following table describes the parts that can make up the form-data:

Parameter

Description and example usage

inputA (required)

Input A

Can be specified in either a file path, a HTTP URI, or raw XML

inputB (required)

Input B

Can be specified in either a file path, a HTTP URI, or raw XML

configuration

Configuration file

Can be specified in either a file path, a HTTP URI, or raw XML

catalog

File path or HTTP URI pointing to catalog file(s).

async

Whether async comparison is used.

Default value if not specified: false

output

An optional file path to write the output to when using async.

E.g. "/Users/exampleUser/Documents/test.xml"

callback

Callback URL called after comparison is complete.

Note : only used with asynchronous comparisons. See this page.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.