XML Debugging for API Integrations

A well-formed XML document follows the syntax rules of the XML specification: every element has a matching closing tag or is self-closing, attributes are quoted, special characters are escaped, and there is exactly one root element. A parser must reject a document that is not well-formed; there is no partial parse or best-effort recovery in XML.

A valid document additionally conforms to a schema, either a DTD or an XML Schema definition. Validity is an additional constraint on top of well-formedness. Most integration debugging starts with well-formedness, because a document that is not well-formed will not even reach schema validation.

Unescaped ampersands are the most common single cause. In XML, the ampersand character begins a character reference or entity reference. A literal ampersand in text content, an attribute value, or a CDATA section outside its brackets must be written as &. An unescaped & not followed by a recognised entity or a valid numeric reference causes an immediate parse error, and the position reported by the parser is the position of the ampersand.

Typographic quotes introduced by word processors or rich-text editors cause a related class of error. The XML attribute value syntax requires straight quotation marks. A document copy-pasted from a word-processed source may contain left and right double quotation marks that are not valid attribute delimiters.

Namespace prefix mismatches are less obvious. A prefix declared in a parent element is valid in all its descendants, but a prefix used without a declaration, or one whose declaration has been removed during editing, produces a well-formedness error. The error message names the prefix rather than the element, which makes it easier to track down once you know what to look for.

Mixed content is an element that contains both child elements and text nodes at the same level, for example a paragraph element containing both text and inline emphasis elements. XHTML documents, DITA topics, and DocBook source files use this pattern extensively.

A naive XML formatter that inserts whitespace between all child nodes will corrupt mixed content. Consider a paragraph element containing the text "Press " followed by a bold element containing "OK" followed by the text " to continue". A formatter that indents the bold element by adding a newline and spaces before it changes the rendered text to "Press \n OK\n to continue". The added whitespace is now part of the document content.

The correct behaviour is to detect mixed content and leave the whitespace exactly as the source provides it. When using a reformatter, check that the tool explicitly documents how it handles mixed content, and verify the output of any element that contains both text and child elements.

A CDATA section wraps a block of text that would otherwise need extensive escaping, such as embedded HTML, a script block, or SQL. Inside a CDATA section, the only sequence that ends the section is the three-character sequence ]]>. Everything else, including ampersands and angle brackets, is treated as literal text.

CDATA sections are a convenience, not a requirement. The same content can be expressed with entity references. The practical reason to prefer CDATA for long embedded fragments is readability: a block of SQL or HTML is far easier to read unescaped. The practical reason to be cautious about CDATA is that some processors or transformers strip or flatten CDATA sections, turning them into escaped text, which can then be re-parsed incorrectly by the consuming system. If the receiving end of an integration has issues with CDATA content, verify that each step in the pipeline preserves the section rather than expanding it.

XML and JSON are not interchangeable. XML supports attributes, mixed content, comments, processing instructions, namespaces, and ordered repeated elements in ways that have no direct JSON equivalent. Any XML-to-JSON conversion requires a convention to resolve these: the most common approach treats attributes as keys with an @ prefix and text nodes as a #text key, but this is not standardised.

Before converting, ask whether the receiving system actually needs JSON or whether it can consume XML natively. If conversion is necessary, agree and document the convention: what happens to attributes, what happens to repeated sibling elements of the same name, whether namespace prefixes are included in keys, and whether CDATA text is treated the same as escaped text. Test the round trip: if the converted JSON is consumed and then the result is sent to a system that validates against the original XML schema, verify that the conversion is lossless for the fields that matter.

1. Validate well-formedness first, before inspecting the content.
2. If the validator reports an ampersand error, search for literal & characters in text and attribute values.
3. If the validator reports a namespace prefix error, find the element where the prefix was declared and check it is still present after any editing.
4. Before reformatting, check whether any element contains mixed content and verify the formatter handles it correctly.
5. When converting to JSON, document the attribute and text-node convention and test with examples that include attributes, repeated elements, and namespace declarations.