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-DocBook-Compare-11_0_0/resources/inputA.xml</path>
  </inputA>
  <inputB type="file">
    <path>/usr/local/deltaxml/DeltaXML-DocBook-Compare-11_0_0/resources/inputB.xml</path>
  </inputB>
  <configuration type="file">
    <path>/usr/local/deltaxml/DeltaXML-DocBook-Compare-11_0_0/resources/config.xml</path>
  </configuration>
</comparison>
Request (JSON)
JSON
{
  "inputA": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DocBook-Compare-11_0_0/resources/inputA.xml"
  },
  "inputB": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DocBook-Compare-11_0_0/resources/inputB.xml"
  },
  "configuration": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DocBook-Compare-11_0_0/resources/config.xml"
  }
}

The response below indicates the comparison result, in this case a DocBook file describing the changes between the inputs specified in the request.

Response
XML
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://missing.deltaxml.com/non-existent.dtd">
<article>
  <title>Article Title</title>
  <sect1>
    <title>
      <phrase revisionflag="deleted">Section1</phrase>
      <phrase revisionflag="added">Section2</phrase> Title
    </title>
    <para>This file points to a non-existent dtd in its DOCTYPE. This forces it to use the catalog and therefore check that it works</para>
  </sect1>
</article>

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/docbook-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.xml"
Content-Size: 98344
Content-Type: application/xml

... XML  ...
--boundary-id
Content-Disposition: file; filename="file2.xml"
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.