DomDocument Features

A list of features for the xml.DomDocument class.

DomDocument features

Table 1. DomDocument Features
Feature Description Default
format-pretty-print

Formats the output by adding whitespace to produce a pretty-printed, indented, human-readable form.

Possible values are TRUE or FALSE.

FALSE
comments

Defines whether the XML comments are kept during the loading of a document into an xml.DomDocument object.

Possible values are TRUE or FALSE.

TRUE
whitespace-in-element-content

Defines whether XML Text nodes that can be considered "Ignorable" are kept during the loading of an XML document into an xml.DomDocument object.

Possible values are TRUE or FALSE.

TRUE
cdata-sections

Defines whether XML CData nodes are kept or replaced by XML Text nodes during the loading of an XML document into an xml.DomDocument object.

Possible values are TRUE or FALSE.

TRUE
expand-entity-references

Defines whether XML EntityReference nodes are kept or replaced during the loading of an XML document into an xml.DomDocument object.

Possible values are TRUE or FALSE.

See security issues with expand-entity-references.

FALSE
load-external-dtd

Defines whether xml.DomDocument.load, xml.DomDocument.loadFromPipe, and xml.DomDocument.loadFromString fetch the external document type definition (DTD) that a document names in its <!DOCTYPE> declaration.

With FALSE, the parse does not fetch the external DTD. On all platforms except macOS and iOS, the parse 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. TRUE, 1, or the string "true" in any letter case enables the feature. Any other value, including "yes", disables the feature without raising an error.

Warning:

With the default value, the parse 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.

TRUE
validation-type

Defines what kind of validation is performed.

Possible values are: DTD, Schema.

Schema
external-schemaLocation

Defines a list of namespace-qualified XML schemas to use for validation on an xml.DomDocument object.

Value is a space-separated string of one or several pairs of strings representing the namespace URI of the schema, followed by its location.

Example:

"http://tempuri/org/NS mySchema1.xsd http://www.mycompany.com mySchema2.xsd"

None
external-noNamespaceSchemaLocation

Defines a list of XML schemas to use for validation on an xml.DomDocument object.

Value is a space-separated string of one or several strings representing the location of a schema.

Example:

"mySchema1.xsd mySchema2.xsd"

None
schema-uriRecovery

Changes the schema location of an XML schema referenced by import tags in other schemas.

Value is a space-separated string of one or several pairs of strings representing the original schema location followed by the new schema location

Example:

"http://www.w3.org/2001/xml.xsd myXML.xsd http://www.mycompany.com/GWS.xsd myGWS.xsd"

None
load-save-base64-string

Changes methods loadFromString() and saveToString() to handle Base64 strings.

Parsing an XML document is done from a BASE64 encoded string, and saving an XML document results in a BASE64 encoded string.

Possible values are TRUE or FALSE.

FALSE
auto-id-attribute

Changes the parsing of an XML document in order to set all unqualified attributes named ID, Id, iD or id to be of type ID.

They can then be retrieved with method getElementById() or with an XPath expression without calling setIdAttribute().

Possible values are TRUE or FALSE.

FALSE
auto-id-qualified-attribute

Changes the parsing of an XML document in order to set all qualified attributes named ID, Id, iD or id to be of type ID.

They can then be retrieved with method getElementById() or with an XPath expression without calling setIdAttributeNS().

Possible values are TRUE or FALSE.

FALSE
enable-html-compliancy

Changes methods to parse, normalize and save HTML document via the xml.DomDocument object.

Possible values are TRUE or FALSE.

The HTML parsing isn't namespace qualified, and document is considered as an XML document after loading.
Note:

This feature works only for HTML 4, it is not supported for HTML 5.

The load-external-dtd feature has no effect on an HTML parse. The document keeps a load-external-dtd value set while enable-html-compliancy is TRUE, and applies it to the XML parses that follow once enable-html-compliancy is FALSE again.

FALSE

Security issues with expand-entity-references

When the expand-entity-references document feature is set to TRUE, XML entities referencing sensitive data may be included when loading the XML document with xml.DomDocument.load, xml.DomDocument.loadFromPipe, xml.DomDocument.loadFromString, or xml.DomDocument.normalize.

For example, in its DTD, the following XML file defines the myref ENTITY element referencing the /etc/passwd file:
<?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE foo [  
      <!ELEMENT foo ANY >
      <!ENTITY myref SYSTEM "file:///etc/passwd" >
   ]>
<foo>&myref;</foo>
When loading this XML file with expand-entity-references set to TRUE, the resulting DOM document will have a <foo> node containing a text node with the content of /etc/passwd.

On all platforms except macOS and iOS, with load-external-dtd set to FALSE, the parse does not fetch the external entity. For details, go to Parsing XML from an untrusted source.

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.