Changes to Qt XML

Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use.

We try to maintain binary and source compatibility for all the public APIs in each release. But some changes were inevitable in an effort to make Qt a better framework and align with modern standards.

Qt 6 enforces XML 1.0 rules more strictly than Qt 5. In Qt 5,the XML parser was more lenient, allowing certain constructs that were not compliant with the XML 1.0 specification. Qt 6 corrects this behavior, ensuring that XML handling follows the standard properly. If your application relies on behavior that was incorrectly permitted in Qt 5, you may need to adjust your XML documents or processing logic accordingly.

For more details on XML 1.0 rules, see the official W3C XML specification: Extensible Markup Language (XML) 1.0 (Fifth Edition)

In this topic we summarize those changes in Qt XML, and provide guidance to handle them.

Simple API for XML (SAX) parser

All SAX classes have been removed from Qt XML. Use QXmlStreamReader for reading XML files. Here are some simple steps to port your current code to QXmlStreamReader:

For example, if you have code like

QFile *file = new QFile(...);
QXmlInputSource *source = new QXmlInputSource(file);

Handler *handler = new Handler;

QXmlSimpleReader xmlReader;
xmlReader.setErrorHandler(handler);
xmlReader.setContentHandler(handler);

if (xmlReader.parse(source)) {
    ... // do processing
} else {
    ... // do error handling
}

you can rewrite it as

QFile file = ...;
QXmlStreamReader reader(&file);

while (!reader.atEnd()) {
    reader.readNext();
    ... // do processing
}
if (reader.hasError()) {
    ... // do error handling
}

QDom and QDomDocument

As SAX classes have been removed from Qt XML, QDomDocument has been re-implemented using QXmlStreamReader. This causes a few behavioral changes:

• Attribute values will be normalized. For example, <tag attr=" a \n b " /> is equivalent to <tag attr="a b"/>.
• Identical qualified attribute names are no longer allowed. This means attributes of an element must have unique names.
• Undeclared namespace prefixes are no longer allowed.

For more details see: Attribute-Value Normalization in XML 1.0

Control characters

In Qt 6, control characters such as U+0000—U+001F, U+007F, and U+0080—U+009F are now correctly rejected per XML 1.0 rules. They were incorrectly allowed in Qt 5. Before using XML with Qt6 ensure that your XML documents contain only valid XML 1.0-compliant characters. If control characters are necessary, encode them using text-safe format.

For more details see: Characters in XML 1.0

HTML Entities in XML

In Qt 6, HTML entities are no longer valid unless explicitly declared in a Document Type Definition (DTD). In Qt 5, certain HTML-specific entities (e.g.,  ) were allowed, even without declaration. To ensure compatibility in Qt 6 use numeric character references, define required entities in a DTD or if your content relies on HTML entities, process the XML as HTML instead.

For more details see: Character Encoding in Entities in XML 1.0

Spacing-only text nodes

By default, text nodes containing only spacing characters are stripped and won't appear in the QDomDocument. The Qt 5 way of changing this behavior was using the QDomDocument::setContent() overload that allowed a QXmlReader to be supplied. That overload was removed in Qt 6.0, but since Qt 6.5, you can pass QDomDocument::ParseOption::PreserveSpacingOnlyNodes as a parse option, to specify that spacing-only text nodes must be preserved.

If you use QDomDocument and rely on any of these, you must update your code and XML documents accordingly.

Qt Core5 compatibility library

If your application or library cannot be ported right now, the QXmlSimpleReader and related classes still exist in Qt5Compat to keep old code-bases working. If you want to use those SAX classes further, you need to link against the new Qt5Compat module and add this line to your qmake .pro file:

QT += core5compat

In case you already ported your application or library to the cmake build system, add the following to your CMakeList.txt:

PUBLIC_LIBRARIES
    Qt::Core5Compat