CODEWITHSUNDEEP
xsd
bethesdaboys
bethesdaboys

Reputation: 1827

XSD annotation and documentation elements, and how to use them

We are creating xml files that we want to be compliant with the following xsd: http://www.topografix.com/gpx/1/1/gpx.xsd This xsd supports '...extending by adding your own elements here ...', see the extensionsType, which I have copied below for convenience.

1) I don't understand whether annotation and documentation are literal element names that would appear in compliant xml. I believe they are not but need confirmation. I'm assuming then that a compliant document would simply have any number of our own custom elements anywhere inside of any [extensions] element, correct?

2) Why are there two pairs of annotation/documentation elements below, with one in a sequence?

 <xsd:complexType name="extensionsType">
       <xsd:annotation>
        <xsd:documentation>
         You can add extend GPX by adding your own elements from another schema here.
        </xsd:documentation>
       </xsd:annotation>
        <xsd:sequence>
         <xsd:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
           <xsd:annotation>
            <xsd:documentation>
             You can add extend GPX by adding your own elements from another schema here.
            </xsd:documentation>
           </xsd:annotation>
         </xsd:any>
        </xsd:sequence>
      </xsd:complexType>

Upvotes: 5

Views: 21003

Answers (1)

Petru Gardea
Petru Gardea

Reputation: 21658

1) From the XML Schema specification: "Annotations provide for human- and machine-targeted annotations of schema components." Schema authors use xsd:documentation as, say Java or .NET, developers use comments.

Annotations are XML Schema artifacts; they are not to show up in an XML document. And yes, your extensions elements should go under <extensions/>; you may use any namespace, other than http://www.topografix.com/GPX/1/1

Sample XML showing extension elements

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<!-- Sample XML generated by QTAssistant (http://www.paschidev.com) -->
<gpx xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.1" creator="creator1" xmlns="http://www.topografix.com/GPX/1/1">
    <extensions>
        <my:element xmlns:my="urn:tempuri-org:some">Hello!</my:element>     
    </extensions>
</gpx>

2) Hard to say why there are two with the same comment; the difference though is that one documents the complex type, while the other the xsd:any element. I would personally have used different comments, first to explain what the complex type is for, the second just as shown.

Upvotes: 8

Related Questions