StaxReader Features

Features of the xml.StaxReader class.

Table 1. StaxReader Features
Feature Description Default
expand-entity-references

Defines whether XML EntityReference nodes are kept or replaced during the parsing of a XML document.

FALSE
load-external-dtd

Defines whether the reader fetches the external document type definition (DTD) that a document names in its <!DOCTYPE> declaration.

With FALSE, the reader does not fetch the external DTD. On all platforms except macOS and iOS, the reader does not fetch external entities either, and the attribute default values defined inside the <!DOCTYPE> still apply, as they need no fetch.

Possible values are TRUE or FALSE. You can also pass 1 or 0, or the strings "true" or "false" in any letter case. Any other value raises error -15623 and leaves the feature unchanged.

Warning:

With the default value, the reader fetches the DTD from whatever location the document names, such as a file on the system or a network address. For a document from a source that you do not control, set load-external-dtd to FALSE. For details, go to Parsing XML from an untrusted source.

The reader takes the value when a read method starts a document: xml.StaxReader.readFrom, xml.StaxReader.readFromPipe, or xml.StaxReader.readFromText. Setting the feature while the reader is reading a document changes nothing for that document.

TRUE

Parsing XML from an untrusted source

By default, xml.DomDocument and xml.StaxReader fetch the external DTD that a document names, from the location that its system identifier gives. That location can be a file on the system that runs the program, or a network address such as an http://, https://, tcp://, or tcps:// URL.

For example, the following XML file names the external DTD order.dtd, which declares EUR as the default value of the currency attribute of the order element:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE order SYSTEM "order.dtd">
<order id="12"/>
When you parse this XML file with load-external-dtd set to TRUE, the <order> element has a currency attribute set to EUR. With load-external-dtd set to FALSE, the parse does not fetch the DTD, and the <order> element has no currency attribute.

For an http:// or https:// location, with load-external-dtd set to TRUE, the parse always sends the request. It uses the DTD only when the server response has both:

  • Status 200
  • An XML media type: application/xml, text/xml, or a type ending in +xml
Warning:

To parse a document from a source that you do not control, such as a request body, a response from a third party, or a file that a user uploads, set load-external-dtd to FALSE before you parse it.

The following example sets the feature on xml.DomDocument and xml.StaxReader:

IMPORT xml

MAIN
  DEFINE doc xml.DomDocument
  DEFINE r xml.StaxReader
  DEFINE xmlText STRING

  LET xmlText = arg_val(1)

  # DomDocument: do not read the external DTD of a document that comes from outside
  LET doc = xml.DomDocument.Create()
  CALL doc.setFeature("load-external-dtd", FALSE)
  CALL doc.loadFromString(xmlText)
  DISPLAY doc.getDocumentElement().getLocalName()

  # StaxReader: set the feature before the read call that starts the document
  LET r = xml.StaxReader.Create()
  CALL r.setFeature("load-external-dtd", FALSE)
  CALL r.readFrom("incoming.xml")
  WHILE r.hasNext()
    CALL r.next()
  END WHILE
  CALL r.close()
END MAIN
Note:

The load-external-dtd feature applies to the parse only. With the validation-type feature set to DTD, xml.DomDocument.validate fetches the external DTD to validate the document against it, whatever the value of load-external-dtd.

Note:

On macOS and iOS, the product uses the XML library of the operating system. With load-external-dtd set to FALSE, the parse does not fetch the external DTD. However, where that library is older than libxml2 2.13, the parse still fetches an external entity that the document references when expand-entity-references is TRUE, and does not apply the attribute default values defined inside the <!DOCTYPE>. To parse an untrusted document on those platforms, keep expand-entity-references set to FALSE.