WebReference.com - Part 3 of Chapter 1: Professional XML Schemas, from Wrox Press Ltd (1/5)
Professional XML Schemas
XML Schema offers two kinds of annotation to a schema, both of which appear as children
of an element called
documentationis rather like the ability to add comments. Using the
documentationelement, we can add information that will help us and others understand the intended purpose of our documents.
appinfooffers 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
documentationelement, 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
documentationelement, the information becomes available to any processing application. If the processing application is an authoring tool, it can pass on information from the
documentationelement to document authors allowing them to use the markup as it is intended.
annotation element can appear at the beginning of most schema constructs,
although it will most commonly be used inside
elements. Where we place the
annotation and its child
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 = "http://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>
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
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
appinfo element is subject to the same rules for appearing in an XML Schema
documentation element, as they are both contained in the
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
<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
appinfoelement to contain Schematron rules in Chapter 14.
Created: October 25, 2001
Revised: October 25, 2001