50.9 How the XML is Validated

50.9.1 Validation at Run-Time

Connext validates the input XML files using a builtin Document Type Definition (DTD).

You can find a copy of the builtin DTD in <NDDSHOME>/resource/schema/rti_dds_qos_profiles.dtd. (This is only a copy of what the Connext core uses. Changing this file has no effect unless you specify its path with the <!DOCTYPE> tag, described below.)

You can overwrite the builtin DTD by using the XML tag, <!DOCTYPE>. For example, the following indicates that Connext must use a DTD file from a user’s directory to perform validation:

<!DOCTYPE dds SYSTEM "/local/joe/rti/dds/mydds.dtd">

• The DTD path can be absolute, or relative to the application's current working directory.
• If the specified file does not exist, you will see the following error:

RTIXMLDtdParser_parse:!open DTD file

• If you do not specify the DOCTYPE tag in the XML file, the builtin DTD is used.
• The XML files used by Connext can be versioned using the attribute version in the <dds> tag. For example:

<dds version="7.3.0">
   ...
</dds>

Although the attribute version is not required during the validation process, it helps to detect DTD incompatibility scenarios by providing better error messages.

For example, if an application using Connext 7.3.0 tries to load an XML file from Connext 4.5z and there is some incompatibility in the XML content, the following parsing error will be printed:

ATTENTION: The version declared in this file (4.5z) is different from the version of Connext (7.3.0). 
If these versions are not compatible, that incompatibility could be the cause of this error.

50.9.2 XML File Validation During Editing

Connext provides DTD and XSD files that describe the format of the XML content. We recommend including a reference to one of these documents in the XML file that contains the QoS profiles—this provides helpful features in code editors such as Visual Studio and Eclipse, including validation and auto-completion while you are editing the XML file.

The DTD and XSD definitions of the XML elements are in

<NDDSHOME>/resource/schema/rti_dds_qos_profiles.dtd and <NDDSHOME>/resource/schema/rti_dds_qos_profiles.xsd, respectively. (<NDDSHOME> is described in Paths Mentioned in Documentation.)

To include a reference to the XSD document in your XML file, use the attribute

xsi:noNamespaceSchemaLocation in the <dds> tag. For example:

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
"<NDDSHOME>/resource/schema/rti_dds_qos_profiles.xsd">
    ...
</dds>

To include a reference to the DTD document in your XML file use the <!DOCTYPE> tag. For example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dds SYSTEM 
"<NDDSHOME>/resource/schema/rti_dds_qos_profiles.dtd">
<dds>
    ...
</dds>

We recommend including a reference to the XSD file in the XML documents because it provides stricter validation and better auto-completion than the corresponding DTD file.

50.9.3 Skipping Element Validation: the must_interpret Attribute

The must_interpret attribute controls how the parser behaves when it fails to validate an XML element. It allows you to ignore the incompatibility of XML files between Connext versions, or between vendors.

XML elements that have the must_interpret attribute set to “false” will not trigger a validation failure by the XML parser. If the attribute is not specified, the default value is “true”, in which case the validation described in 50.9.1 Validation at Run-Time and 50.9.2 XML File Validation During Editing will be performed.

<reliability must_interpret="true">

    <kind>RELIABLE_RELIABILITY_QOS</kind>

</reliability>

50.9.3.1 Validation of an XML element

The XML parser checks three aspects while validating an element:

• The element tag. Is this a valid (known) tag?
• The element attributes. Are the attributes valid for the current tag? Are there required attributes not specified for the current tag?
• The element’s parent. Is this one of the possible valid elements that the parent can have as children?

If an element is valid with respect to these three aspects, the parser continues validating its children.

If an element is invalid, the parser will fail if the element's must_interpret attribute is set to true—either because must_interpret is not specified or because it is explicitly set to true.

When must_interpret is false, the parser allows invalid tags and attributes, as follows:

• If the element’s tag or parent is invalid, the parser doesn't even look at its children. Validation continues in the next element of the XML tree.
• If the element’s tag and parent are valid, the parser does look at its children. Those children for which must_interpret is not false may fail validation.
• The parser always allows unexpected or missing attributes as long as the tag's must_interpret attribute is false.

50.9.3.2 Examples

The following examples help clarify how the must_interpret attribute works. In these examples, <custom_tag>, <custom_child>, and custom_attribute represent tags or attributes that are invalid for the current XML parser. These could be elements supported only in modern versions of Connext. Or they could be custom elements that are understood only by a specific vendor implementation.

50.9.3.2.1 First example: invalid tag with must_interpret=“false”

The XML parser validation succeeds if there is an invalid tag, because this tag has the must_interpret attribute explicitly set to false. The parser in this scenario ignores the XML tag because it doesn’t understand it. The parser also ignores the children. Neither is validated.

<datareader_qos>

    <custom_tag must_interpret="false">

        <custom_child>Custom value<custom_child>

    </custom_tag>

</datareader_qos>

50.9.3.2.2 Second example: valid tag with invalid attributes and must_interpret=“false”

The XML parser validation succeeds if a tag has invalid attributes, as long as it also has the must_interpret attribute explicitly set to false. The XML parser skips validation of a tag’s attributes whenever must_interpret is false. It doesn’t enforce required attributes either. The parser continues validating the tag’s children. Validation succeeds in this case because the children are valid.

<datareader_qos>

    <durability must_interpret="false" custom_attribute="foo">

        <kind>VOLATILE_DURABILITY_QOS</kind>

        <direct_communication>true</direct_communication>

    </durability>

</datareader_qos>

50.9.3.2.3 Third example: valid tag with invalid attributes, invalid children, and must_interpret=“false”

The parent tag succeeds, even with an invalid attribute, because must_interepret is set to false. Each of the invalid children requires must_interpret=“false” if we want to prevent a validation failure of the XML parser. Validation does not succeed in this case because the invalid tag <custom_child> does not have must_interpret="false".

<datareader_qos>

    <durability must_interpret="false" custom_attribute="foo">

        <custom_child>Custom value</custom_child>

    </durability>

</datareader_qos>