Sollte Beispiel xml in einer xsd-Dokumentationsanmerkung escaped sein?

Question

Lets sagen, ich habe ein xsd Schema und ich habe mehrere < Annotation/> Elemente mit < Dokumentation/> Elemente in ihnen. Wenn ich Beispiel xml in die < Dokumentation/> Elemente platzieren möchte, sollte ich das Beispiel xml entkommen?

z.B .:

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

oder:

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

XmlSpy 2009 scheint zu versuchen Beispiel xml zu validieren, die in diesem Fall ist Oasis 8.1, die ich nicht schreiben, und schlägt fehl. Wenn ich den XML-Code entziehe, entblößt die Schema-Anzeige von XML Spy nicht die & lt; und & gt ;.

Es scheint die richtige Sache zu sein, die un-maskierte XML einzuschließen. XML In A Nutshell Third Edition zeigt ein Beispiel auf Seite 282, wo ein Anchor-Tag in einer xsd-Box ist, empfiehlt jedoch nicht speziell, was zu tun ist in Fällen der Dokumentation mit Beispielen des verwendeten Schemas ..

Answer 1

Kompromiss: lassen Sie die Beispiele unescaped , aber wickle sie in einen <![CDATA[ ... ]]> Block. Dies sollte verhindern, dass XML Spy versucht, Ihre Beispiele zu überprüfen, ohne dass sie maskiert werden müssen.

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

Answer 2

Das Element erlaubt es, jeden wohlgeformten XML-Inhalt zu enthalten, also ist das zweite Beispiel auch richtig.

Obwohl die XML-Schemadefinition nicht detailliert auf das Element eingeht, verwenden einige Dokumente, die ich gesehen habe, HTML, um die Dokumentation zu formatieren. Ich könnte auch daran denken, C# XML-Codezeilenkommentare zu verwenden.

Also, während Sie willkürlich wohlgeformten XML innerhalb verwenden können, würde ich davon abraten - weil einige automatische Dokumentations-Tool mit dem XSD daran ersticken kann. Stattdessen würde ich empfehlen, die Dokumentation mit <![CDATA[ zu verpacken, mit der Sie kleiner als Zeichen und Et-Zeichen schreiben können. Beenden Sie Ihre CDATA-Sektion mit ]]>.