Skip to main content
Skip table of contents

Topic Comparison Configuration File Schema Guide

This guide provides a short description of each element and attribute defined in the XML schema for the DITA Compare REST topic configuration file. A fuller description of the configuration file, along with the examples and an explanation of the main concepts can be found in the User Guide and associated documentation.

 


An occurrence indicator is used here for cases other than where a child element may occur once and only once. The occurrent indicators are descibed below:

  • [*] - Zero or more
  • [?] - Zero or once
  • [+] - One or more

Element Index

 

Element Detail

Elements are listed in document-tree order, top-level elements first, then alphabetically:

Element: configuration 1

The root element for defining the configuration for DITA Compare REST.

Contained by

/

Contains
ElementDescription
parameters The root element for defining the configuration parameters for the comparison

Element: parameters 2

The root element for defining the configuration parameters for the comparison.

Contained by
Contains
ElementDescription
advancedParameters The advanced settings parameters provide a finer level of control over the comparison, the output, and error reporting
comparisonParameters These parameters control how the comparison is performed
outputParameters These parameters enable the form of the output to be configured

Element: advancedParameters 3

The advanced settings parameters provide a finer level of control over the comparison, the output, and error reporting.

Contained by
Contains
ElementDescription
advancedBehaviour Parameters used to override or force specific behaviours
selectingUnrepresentableChange These parameters are used to specify how unrepresentable change can be handled
validation Input validation and reporting

Element: comparisonParameters 4

These parameters control how the comparison is performed.

Contained by
Contains
ElementDescription
ditaConfiguration The DITA configuration parameters apply to all output formats
elementMoves These parameters control element moves handling and defines the values for revision attribute
formattingElements These parameters control which DITA elements are marked as inline structural changes
imageComparison Parameters managing image comparison
mathml Parameters managing MathML
tableComparison These parameters control how tables are compared
textComparison These parameters control how text is compared and whitespace handled

Element: outputParameters 5

These parameters enable the form of the output to be configured.

Contained by
Contains
ElementDescription
common The output parameters that are either used to specify a specific output type or apply to all output types
ditaMarkup The DITA markup output format specific parameters provide control over how the 'rev' and 'status' attributes are used to represent change
trackedChanges The tracked changes output format specific parameters provide a way of configuring tracked change output and editor/format specific output

Element: advancedBehaviour 6

Parameters used to override or force specific behaviours.

Contained by
Contains
ElementDescription
forceSpecialization Specifies whether or not to force result specialization when the input types are different
outputEncodingDeclaration Sets the character encoding output to use in the XML declaration
topicPublicId Specifies the publicId to use for a Topic doctype
topicSystemId Specifies the systemId to use for a Topic doctype
xmlVersionDeclaration Sets the version to use in the XML declaration

Element: selectingUnrepresentableChange 7

These parameters are used to specify how unrepresentable change can be handled.

Contained by
Contains
ElementDescription
modifiedAttributeMode Specifies how modified attributes should be included in the output
unmarkedChangeMode Specifies how to handle data that cannot contain difference markup

Element: validation 8

Input validation and reporting.

Contained by
Contains
ElementDescription
validateInputs Specifies whether to validate input documents
warningReportMode Sets the mode to use for reporting recoverable errors and warnings

Element: ditaConfiguration 9

The DITA configuration parameters apply to all output formats.

They are used to control both conflict resolution and which topics are considered to be part of the document.

Contained by
Contains
ElementDescription
removeRevAttributeRegex This parameter specifies the regular expression that matches 'rev' attributes to be stripped
stepsConflictResolution Specifies how to resolve conflicts between a task body's mutually exclusive steps and steps-unordered elements
strictTaskModel Specifies whether inputs are using the “strict task model” added in DITA 1
useIdsAsKeys Specifies whether to use id attribute value as keys in order to provide identity during comparison

Element: elementMoves 10

These parameters control element moves handling and defines the values for revision attribute.

Contained by
Contains
ElementDescription
detectMoves If set to true, then elements moves are handled - if the elements have ids on them
moveSourceRevision Specifies the string value to use for the rev attribute for source of moved content
moveTargetRevision Specifies the string value to use for the rev attribute for target of moved content

Element: formattingElements 11

These parameters control which DITA elements are marked as inline structural changes.

Contained by
Contains
ElementDescription
addInlineFormattingElements A comma and/or space separated list of inline formatting elements, which will be added to the value of the inline-formatting-elements parameter
ignoreInlineFormatting If set to true, any changes that consist only of the addition, deletion or modification of DITA inline markup elements are not noted as changes
inlineFormattingElements Sets the comma and/or space separated list of inline formatting elements
removeInlineFormattingElements A comma and/or space separated list of inline formatting elements, which will be removed from the value of the inline-formatting-elements parameter

Element: imageComparison 12

Parameters managing image comparison.

Contained by
Contains
ElementDescription
imageCompare Specifies whether to compare images
outputImageRefForm Specifies output image ref form after image comparison

Element: mathml 13

Parameters managing MathML

Contained by
Contains
ElementDescription
mathmlGranularity Specifies the granularity at which the differences between the two MathML expressions will be represented
mathmlProcessing Specifies whether to apply MathML processing

Element: tableComparison 14

These parameters control how tables are compared.

Contained by
Contains
ElementDescription
calsTableProcessing Specifies whether to apply CALS table processing
htmlTableProcessing Specifies whether to apply HTML table/DITA simpletable processing
invalidTableBehaviour This parameter declares what type of processing should be used for those tables that are marked as invalid

Element: textComparison 15

These parameters control how text is compared and whitespace handled.

Contained by
Contains
ElementDescription
whitespaceProcessingMode Specifies how to handle whitespace changes
wordByWord Specifies whether to perform detailed text comparison or not

Element: common 16

The output parameters that are either used to specify a specific output type or apply to all output types.

Contained by
Contains
ElementDescription
grouping Specifies whether adjacent changes (insertions or deletions) should be grouped into a single insertion and/or deletion block
indentOutput Sets whether the result should be indented
outputFormat Specifies what type of output is produced
preservationMode Sets the mode to use for preserving original data

Element: ditaMarkup 17

The DITA markup output format specific parameters provide control over how the 'rev' and 'status' attributes are used to represent change.

Contained by
Contains
ElementDescription
addOutputClassAtts Specifies whether to include an 'outputclass' attribute for marking changes
addRevisionAtts Specifies whether the result should use 'rev' attributes to mark change
addStatusAtts Specifies whether the result should use 'status' attributes to mark change
includeDeleted Specifies whether to include deleted content in the result
newOutputclass Specifies the string value to use for the outputclass attribute of added content
newRevision Sets the mode to use for preserving original data
newVersionAtts Specifies attributes to place on to added elements in the result
oldOutputClass Specifies the string value to use for the outputclass attribute of deleted content
oldRevision Specifies the string value to use for the rev attribute of deleted content
oldVersionAtts Specifies attributes to place on deleted elements in the result
phraseContainerExclusions Specifies any specializations where phrases have been removed from the content model
phraseElementName Specifies the element name to use in place of ph in the result
showNonPhraseChanges Specifies whether to textually mark changes to text where ph elements are not allowed

Element: trackedChanges 18

The tracked changes output format specific parameters provide a way of configuring tracked change output and editor/format specific output.

Contained by
Contains
ElementDescription
framemakerTcsTableChangeMode Specifies how changes in tables should be tracked
oxygenTcsDeletedSpaceMode Specifies how deleted spaces should be handled
oxygenTcsVersion Specifies the version of Oxygen editor used to display, accept and reject the tracked changes
trackedChangedAuthor Specifies the author name that is embedded into the generated insertion and deletion processing instruction
trackedChangesDate Specifies the time-stamp that is embedded into the generated insertion and deletion processing instruction
xmetalTcsTableChangeMode Specifies how changes in tables should be tracked

Element: forceSpecialization 19

Specifies whether or not to force result specialization when the input types are different.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable forcing result specialization.

Element: outputEncodingDeclaration 20

Sets the character encoding output to use in the XML declaration.

Contained by
Contains

Type: xs:string

Element: topicPublicId 21

Specifies the publicId to use for a Topic doctype.

Contained by
Contains

Type: xs:string

Element: topicSystemId 22

Specifies the systemId to use for a Topic doctype.

Contained by
Contains

Type: xs:string

Element: xmlVersionDeclaration 23

Sets the version to use in the XML declaration.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


1.0
Ensure the xml version is set to '1.0'.
1.1
Ensure the xml version is set to '1.1'.
system
Use the 'B' document's xml version (as provided by the parser).

Element: modifiedAttributeMode 24

Specifies how modified attributes should be included in the output.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


automatic
The behaviour will depend on other parameter settings, primarily the output-format. If the output format is able to show attribute changes, modified attributes will not be processed differently, otherwise 'B' mode will be chosen.
B
Output the 'B' version of modified attributes and any added ('B') attributes. Note that deleted ('A') attributes will not be output.
BA
Output the 'B' version of modified attributes. Output both inserted ('B') and deleted ('A') attributes.
A
Output the 'A' version of modified attributes and any deleted ('A') attributes. Note that added ('B') attributes will not be output.
AB
Output the 'A' version of modified attributes. Output both inserted ('B') and deleted ('A') attributes.
encode-as-attributes
Output the 'B' version of modified attributes and any added ('B') attributes but additionally show the changes encoded as attributes in the attribute-change ('ac') namespace.

Element: unmarkedChangeMode 25

Specifies how to handle data that cannot contain difference markup.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


B
Output the 'B' version of modified items; output inserted ('B') items; do not output deleted ('A') items.
BdA
As 'B' except when processing an internal subset declaration, in which case act as 'BA'.
BA
Output the 'B' version of modified items; output both inserted ('B') and deleted ('A') items.
A
Output the 'A' version of modified items; output deleted ('A') items; do not output inserted ('B') items.
AdB
As 'A' except when processing an internal subset declaration, in which case act as 'AB'.
AB
Output the 'A' version of modified items; output both inserted ('B') and deleted ('A') items.

Element: validateInputs 26

Specifies whether to validate input documents.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable validation of input documents.

Element: warningReportMode 27

Sets the mode to use for reporting recoverable errors and warnings.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


messageReport
The recoverable errors and warnings as XSL messages, which are typically visible when the comparison is run from a command-line terminal.
pis
Add the recoverable errors and warnings as processing instructions.
comments
Add the recoverable errors and warnings as comments.
markupAdd
the recoverable errors and warnings as document content.

Element: removeRevAttributeRegex 28

This parameter specifies the regular expression that matches 'rev' attributes to be stripped.

Contained by
Contains

Type: xs:string

Element: stepsConflictResolution 29

Specifies how to resolve conflicts between a task body's mutually exclusive steps and steps-unordered elements.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


preferA
Use the element name from the 'A' document to contain the compared entries.
preferB
Use the element name from the 'B' document to contain the compared entries.
preferSteps
Use a steps element to contain the compared entries.
preferStepsUnordered
Use a steps-unordered element to contain the compared entries.

Element: strictTaskModel 30

Specifies whether inputs are using the “strict task model” added in DITA 1.

2 (which reflects how tasks are defined pre-1.2) or the “general task model” which allows for a looser definition of elements under taskbody.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable using the "strict task model".

Element: useIdsAsKeys 31

Specifies whether to use id attribute value as keys in order to provide identity during comparison.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable using the id attribute as keys.

Element: detectMoves 32

If set to true, then elements moves are handled - if the elements have ids on them.

If this feature is set to true then it also overrides the value of the parameter ‘useIdsAsKeys’.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable moves handling.

Element: moveSourceRevision 33

Specifies the string value to use for the rev attribute for source of moved content.

Contained by
Contains

Type: xs:string

Element: moveTargetRevision 34

Specifies the string value to use for the rev attribute for target of moved content.

Contained by
Contains

Type: xs:string

Element: addInlineFormattingElements 35

A comma and/or space separated list of inline formatting elements, which will be added to the value of the inline-formatting-elements parameter.

Contained by
Contains

Type: xs:string

Element: ignoreInlineFormatting 36

If set to true, any changes that consist only of the addition, deletion or modification of DITA inline markup elements are not noted as changes.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable formatting handling.

Element: inlineFormattingElements 37

Sets the comma and/or space separated list of inline formatting elements.

Contained by
Contains

Type: xs:string

Element: removeInlineFormattingElements 38

A comma and/or space separated list of inline formatting elements, which will be removed from the value of the inline-formatting-elements parameter.

Contained by
Contains

Type: xs:string

Element: imageCompare 39

Specifies whether to compare images.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable image comparison.

Element: outputImageRefForm 40

Specifies output image ref form after image comparison.

By default outputs the href attribute as it appears in the source document.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


source
Output the href attribute as it appears in the source document.
absolute
Output the href attribute as it is resolved.

Element: mathmlGranularity 41

Specifies the granularity at which the differences between the two MathML expressions will be represented.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


adjacent
Reports the differences to the MathML by repeating A and B MathML inputs adjacent to each other.
detailedAdjacent
Reports the differences to the MathML by repeating the A and B MathML inputs adjacent to each other, with individual changes highlighted.
inline
Reports the differences within the MathML without duplicating A and B.

Element: mathmlProcessing 42

Specifies whether to apply MathML processing.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable MathML processing.

Element: calsTableProcessing 43

Specifies whether to apply CALS table processing.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable CALS table processing.

Element: htmlTableProcessing 44

Specifies whether to apply HTML table/DITA simpletable processing.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable HTML table processing.

Element: invalidTableBehaviour 45

This parameter declares what type of processing should be used for those tables that are marked as invalid.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


fail
Throw an exception.
propagateUp
Propagate the changes to the table-level.
compareAsXml
Compare the table content as well-formed XML.

Element: whitespaceProcessingMode 46

Specifies how to handle whitespace changes.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


show
Display the differences in whitespace where possible.
cdata
Ignore differences in whitespace, unless they occur within a CDATA section (or are explicitly preserved).
ignore
Ignore differences in whitespace that is not explicitly preserved.
normalize
Normalize whitespace in inputs before comparison.
automatic
Chooses the most appropriate mode based on other parameter settings. This is dependent on two other parameters 'outputFormat' and the 'preservationMode', as discussed in the main whitespace processing mode documentation.

Element: wordByWord 47

Specifies whether to perform detailed text comparison or not.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable word-by-word comparison.

Element: grouping 48

Specifies whether adjacent changes (insertions or deletions) should be grouped into a single insertion and/or deletion block.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable change grouping.

Element: indentOutput 49

Sets whether the result should be indented.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


yes
The value representing the String value 'yes'. Output is indented.
no
The value representing the String value 'no'. Output is not indented.

Element: outputFormat 50

Specifies what type of output is produced.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


dita-markup
Differences are marked up using DITA's rev and status attributes.
arbortext-tcs
Differences are marked up in the Arbortext tracked change format.
oxygen-tcs
Differences are marked up in the Oxygen tracked change format.
xmetal-tcs
Differences are marked up in the XMetaL tracked change format.
framemaker-tcs
Differences are marked up in the FrameMaker tracked change format.

Element: preservationMode 51

Sets the mode to use for preserving original data.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


automatic
Chooses the most appropriate setting based on the output format. If tracked changes are being produced, this will be 'roundTrip', otherwise 'docAndAttrib' will be used.
document
Preserve document typing information.
docAndAttrib
Preserve document typing and original attribute information.
roundTrip
Preserve document type, entity usage, and attribute usage data.
entityRef
Enhance round-trip processing by analysing entity contents.
nestedEntityRef
Enhance round-trip processing by analysing both entity and nested entity contents.

Element: addOutputClassAtts 52

Specifies whether to include an 'outputclass' attribute for marking changes.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable including an 'outputclass' attribute.

Element: addRevisionAtts 53

Specifies whether the result should use 'rev' attributes to mark change.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable using 'rev' attributes to mark change.

Element: addStatusAtts 54

Specifies whether the result should use 'status' attributes to mark change.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable using 'status' attributes to mark change.

Element: includeDeleted 55

Specifies whether to include deleted content in the result.

Contained by
Contains
AttributeTypeDescription
enabledbooleanType Set false to disable including deleted content in the result.

Element: newOutputclass 56

Specifies the string value to use for the outputclass attribute of added content.

Contained by
Contains

Type: xs:string

Element: newRevision 57

Sets the mode to use for preserving original data.

Contained by
Contains

Type: xs:string

Element: newVersionAtts 58

Specifies attributes to place on to added elements in the result

Contained by
Contains
ElementDescription
versionAtt Custom version attribute datatype

Element: oldOutputClass 59

Specifies the string value to use for the outputclass attribute of deleted content.

Contained by
Contains

Type: xs:string

Element: oldRevision 60

Specifies the string value to use for the rev attribute of deleted content.

Contained by
Contains

Type: xs:string

Element: oldVersionAtts 61

Specifies attributes to place on deleted elements in the result

Contained by
Contains
ElementDescription
versionAtt Custom version attribute datatype

Element: phraseContainerExclusions 62

Specifies any specializations where phrases have been removed from the content model.

Contained by
Contains

Type: xs:string

Element: phraseElementName 63

Specifies the element name to use in place of ph in the result.

Contained by
Contains

Type: xs:string

Element: showNonPhraseChanges 64

Specifies whether to textually mark changes to text where ph elements are not allowed.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


where-valid
Uses -[[old-text]]- +[[new-text]]+ delimiters to show change where ph is not a valid DITA.
always
Always wrap change in the element set by phrase-element-name.
never
Do not show change where a 'phrase-element-name' element is not valid.

Element: framemakerTcsTableChangeMode 65

Specifies how changes in tables should be tracked.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


down
Changes in rows and cells are pushed down to the cell content level.
up
Changes in rows and cells are pushed up to the table level.
ignoreAll
changes in a table are ignored.

Element: oxygenTcsDeletedSpaceMode 66

Specifies how deleted spaces should be handled.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


automatic
Chooses the delete space processing mode based on the declared oxygen-tcs-version parameter.
normlize
Allows deleted text to be viewed correctly prior to oXygen 14 release.
keep
Keeps the original whitespace formating of the deleted region.

Element: oxygenTcsVersion 67

Specifies the version of Oxygen editor used to display, accept and reject the tracked changes.

Contained by
Contains

Type: xs:float

Element: trackedChangedAuthor 68

Specifies the author name that is embedded into the generated insertion and deletion processing instruction.

Contained by
Contains

Type: xs:string

Element: trackedChangesDate 69

Specifies the time-stamp that is embedded into the generated insertion and deletion processing instruction.

Contained by
Contains

Type: xs:string

Element: xmetalTcsTableChangeMode 70

Specifies how changes in tables should be tracked.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


down
Changes in rows and cells are pushed down to the cell content level.
up
Changes in rows and cells are pushed up to the table level.
ignoreAll
changes in a table are ignored.

Element: versionAtt 71

Custom version attribute datatype

Contained by
Contains
AttributeTypeDescription
localName Custom version attribute local name.
value Custom version attribute value.
namespaceUri Custom version attribute namespace URI.
prefix Custom version prefix.

(This documentation was auto-generated from the XML Schema for the DITA Compare REST topic configuration file.)

JavaScript errors detected

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

If this problem persists, please contact our support.