WebReference.com - Part 3 of Chapter 1: Professional XML Schemas, from Wrox Press Ltd (1/5)

[next]

Professional XML Schemas

Annotations

XML Schema offers two kinds of annotation to a schema, both of which appear as children of an element called annotation:

• documentation is rather like the ability to add comments. Using the documentation element, we can add information that will help us and others understand the intended purpose of our documents.

• appinfo offers a place in which we can provide additional information to a processing application.

As with all areas of programming, the use of comments is very important (even if they can be a nuisance to add at the time of writing). Of course they help the original author when they come back to use the schema later, but their use is also important for anyone else wanting to use the schema to help them understand the constructs – whether they are authoring documents according to the schema or writing an application to process documents according to the schema. As such, they will be especially helpful if the document author or programmer is not used to the schema syntax.

If we intend that others should use our schema, we should provide enough information in documentation elements to clarify any ambiguity regarding the intended purpose of an element or type. Additional information may also help users get to grips with a schema quicker.

Good use of documentation could make the difference in getting our schema adopted by a group of users over an alternative schema that is not as well documented.

DTD authors are allowed to use comments using the same syntax used for XML comments:

<!-- comment goes here -->

Indeed, we can include comments in this form in an XML Schema because it is an XML document itself, but this is not a good way of documenting the XML Schema for these reasons:

• By putting documentation in a documentation element, you can add structured documentation including markup such as XHTML, whereas XML comments cannot.

• You can easily make the schema self-documenting by adding a stylesheet to it.

• XML parsers can ignore comments. By providing an explicit documentation element, the information becomes available to any processing application. If the processing application is an authoring tool, it can pass on information from the documentation element to document authors allowing them to use the markup as it is intended.

The annotation element can appear at the beginning of most schema constructs, although it will most commonly be used inside element, attribute, simpleType, complexType, group, and schema elements. Where we place the annotation and its child documentation will affect what the documentation applies to.

In our simple Customer example that we have been looking at through this chapter, we could provide copyright and author information at the root of the schema, and indicate to document authors that the MiddleInitial element is optional, although if the Customer has a middle name we should use it:

<?xml version = "1.0" ?>
<xs:schema xmlns:xs = "https://www.w3.org/2001/XMLSchema">
   <xs:annotation>
      <xs:documentation>
         Schema for customer name information.
         Used in Professional XML Schemas
         Copyright Wrox Press Ltd 2001, all rights reserved 
         1102 Warwick Road, Acocks Green, Birmingham, B27 6BH. UK
      </xs:documentation>
   </xs:annotation>
   <xs:element name = "Customer">
   <xs:annotation>
      <xs:documentation>
         MiddleInitial is optional, but should be used if the customer has a 
         middle name to help distinguish between customers with like names.
      </xs:documentation>
   </xs:annotation>
      <xs:complexType>
         <xs:group ref = "NameGroup" />
      </xs:complexType>
   </xs:element>
   <xs:group name = "NameGroup">
      <xs:sequence>
         <xs:element name = "FirstName" type = "xs:string" />
         <xs:element name = "MiddleInitial" type = "xs:string" />
         <xs:element name = "LastName" type = "xs:string" />
      </xs:sequence>
   </xs:group>
</xs:schema>

The appinfo child of the annotation element is designed to pass information to a processing application, stylesheet, or other tool. This will be a particular advantage to schema users if XML Schema compliant parsers implement a way of passing this information to an application, because those who used XML 1.0 processing instructions to pass information to the processing application often had to write custom parsers in order to do this. Therefore, a lot of developers who could have made use of processing instructions ended up putting that information in application code, making the resulting application less flexible. By allowing information to be put into the appinfo element, programmers can either pass information to the application about how the section of a conforming document should be processed, or they can add extra code inside the appinfo elements.

The appinfo element is subject to the same rules for appearing in an XML Schema as the documentation element, as they are both contained in the annotation element. This means that it can be used within most schema constructs. In the following example we have nested some script inside the appinfo element, which is intended to indicate to an application what action to take, depending upon which of a choice of two elements a document instance contains:

   <xs:group name="CreditOrDebitGroup">
      <xs:annotation>
         <xs:appinfo>
            if (currentNode.firstChild != "Credit")
               docParser.load(debitURL);
            else
               document.write("Your account will be credited within 24 
                              hours.");
         </xs:appinfo>
      </xs:annotation>
      <xs:choice>
         <xs:element name = "Credit" type = "CreditType" />
         <xs:element name = "Debit" type = "DebitType" />
      </xs:choice>
   </xs:group>

The script buried inside the appinfo element can be passed to an application that is using the schema to validate an instance of the document. In this case, the script in the appinfo element can be passed to a processing application to indicate how to handle each element in the choice group, depending upon which element the document contains.

We look at annotation in more detail in Chapter 10 on Schemas and XSLT. There is also an interesting example of using the appinfo element to contain Schematron rules in Chapter 14.

[next]

Created: October 25, 2001
Revised: October 25, 2001

URL: https://webreference.com/authoring/languages/xml/schemas/chap1/3/