Should example xml in an xsd documentation annotation be escaped?

Question

Lets say I have an xsd schema and I have several <annotation/> elements with <documentation/> elements in them. If I wanted to place example xml in the <documentation/> elements, should I escape the example xml?

e.g.:

<annotation>
    <documentation>Example Xml: &lt;element&gt;some text&lt;/element&gt;</documentation>
</annotation>

or:

<annotation>
    <documentation>Example Xml: <element>some text</element></documentation>
</annotation>

XmlSpy 2009 seems to try to validate example xml, which in this case is Oasis 8.1 which I did not write, and fails. If I escape the xml, the schema display view of XML Spy does not unescape the &lt; and &gt;.

It would seem the correct thing to do is include the un-escaped xml. XML In A Nutshell Third Edition shows an example on page 282 where there is an anchor tag in an xsd box, but does not recommend specifically what to do in cases of the documentation containing examples of the schema being used..

Answer 1

Compromise: leave the examples unescaped, but wrap them in a <![CDATA[ ... ]]> block. This should prevent XML Spy from attempting to validate your examples without requiring they be escaped.

<annotation>
    <documentation><![CDATA[Example Xml: <element>some text</element>]]></documentation>
</annotation>

Answer 2

The element permits any well-formed XML content to be inside, so yes, the second example is correct as well.

Although the XML Schema definition does not go into detail about the element, several documents I've seen use HTML inside to format the documentation. I could also think of using C# XML cocumentation-line comments inside.

So, while you may use arbitrary well-formed XML inside , I would advise against it - because some automatic documentation tool using the XSD may choke on it. Instead, I would recommend wrapping the documentation with <![CDATA[ which lets you write smaller-than-signs and ampersands. End your CDATA-section with ]]>.