Chapter 2. Instance Document

Table of Contents

2.1. Namespaces

Because there are many types of XML documents, either for transforming or validating data, an XML file that contains data is called an instance document. Any XML document must be well-formed which means that:

But there are also other peculiarities we will describe shortly in this chapter.

In the rest of this document, we will be using as input the XML instance files shown in Example 2.2 and Example 2.3. Their global organization is given in Example 2.1. They describe a wine cellar containing wine bottles defined in a separate wine catalog. This application was inspired by the Livre de cave example used by Benoît Habert in his book on the Common Lisp Object System (CLOS) programming [23]. Some of the lines in the examples are marked with numbered callouts (such as ) linked to an explanation at the end of each example.

The structure of our instance document files is the following:

Example 2.1. Outline of CellarBook.xml including WineCatalog.xml in a different namespace

  1 <cellar-book ...
        xsi:noNamespaceSchemaLocation="CellarBook.xsd"
        xmlns:cat="http://www.iro.umontreal.ca/lapalme/wine-catalog">
        <xi:include href="WineCatalog.xml" ... />                        (1)
  5 
    <wine-catalog schemaLocation="http://www.iro.umontreal.ca/lapalme/wine-catalog WineCatalog.xsd">
        <wine name="Domaine de l'Île Margaux" ... >...</wine>
        <wine name="Riesling Hugel" ... >...</wine>
        <wine name="Château Montguéret" ... >...</wine>
 10     <wine name="Mumm Cordon Rouge" ... >...</wine>
        <wine name="Prado Rey Roble" ... >...</wine>
    </wine-catalog>
    
        <owner>...</owner>
 15     <location>...</location>
        <cellar>
            <wine code="C00043125">...</wine>
            <wine code="C00312363">...</wine>
            <wine code="C00871996">...</wine>
 20         <wine code="C00929026">...</wine>
        </cellar>
    </cellar-book>

1

Inclusion of the file WineCatalog.xml. The XML processor replaces this line at run-time by the content of the wine-catalog element shown here in bold.


Example 2.2. Excerpt of CellarBook.xml, the XML instance document holding the content of the cellar (Example D.1 shows the whole XML content)

  1 <?xml version="1.0" encoding="UTF-8"?>                               (1)
    <!DOCTYPE cellar-book [<!ENTITY guy "Guy Lapalme" >                  (2)
                           <!ENTITY eacute "&#xe9;" >
                           <!ENTITY mtl "Montr&eacute;al" >
  5                        <!ENTITY GL "&guy;, &mtl;" >]>                (3)
    <cellar-book xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   (4)
                 xmlns:cat="http://www.iro.umontreal.ca/lapalme/wine-catalog"
                 xsi:noNamespaceSchemaLocation="CellarBook.xsd">         (5)
        <xi:include href="WineCatalog.xml"                               (6)
 10                 xmlns:xi="http://www.w3.org/2001/XInclude"/>
        <owner>                                                          (7)
            <name>                                                       (8)
                <first>Jude</first>
                <family>Raisin</family>
 15         </name>
            <street>1234 rue des Châteaux</street>
            <city>St-George</city>
            <province>ON</province>
            <postal-code>M7W 7S0</postal-code>
 20     </owner>
        <location>                                                       (9)
            <street>4587 des Futailles</street>
            <city>Vallée des crus</city>
            <province>QC</province>
 25         <postal-code>H3C 4J8</postal-code>
        </location>
                                                                         (10)
        <cellar>                                                         (11)
            <wine code="C00043125">
 30             <purchaseDate>2005-06-20</purchaseDate>
                <quantity>2</quantity>
                <comment>                                                (12)
                    <cat:bold>&GL;</cat:bold>: should reorder soon
                </comment>
 35         </wine>
            ...                                                          (13)
            <wine code="C00929026">
                <purchaseDate>2003-10-15</purchaseDate>
                <quantity>1</quantity>
 40             <comment>for <cat:bold>big</cat:bold> parties</comment>
            </wine>
        </cellar>
    </cellar-book>
                

1

A processing instruction indicating the XML version used. Although XML version 1.1 exists, very few processors handle it, so most of the time version="1.0" is used. The encoding for the file, here it is UTF-8.

2

Element !DOCTYPE, not a well-formed XML element, defines entities that can be used in the XML instance document. This notation will be explained further in Section 3.1 but for the moment they can be considered as text macros that will allow string substitutions before the XML file is processed. Substitution occurs when an entity is referred to by enclosing its name between & and ;. For example, entity guy is replaced by Guy Lapalme when &guy; is encountered in the file.

3

Entities can refer to other entities: &GL; will be replaced by Guy Lapalme, Montréal. When an entity declaration is followed by SYSTEM and the name of a file, then a reference to this entity is replaced by the content of the file.

4

Starting tag indicating that this is an instance file to be validated with a given schema.

5

Name of the file containing the schema for this instance file.

6

Inclusion of another XML file describing the wine catalog.

7

Description of the owner of the cellar book.

8

Name of the owner of the cellar book.

9

Location of the owner of the cellar book.

10

Description of the cellar.

11

Information about a given wine, such as quantity and comments; the wine is identified by a code that must match one in the wine catalog.

12

As the bold element is defined in the schema associated with the catalog, it must be given the namespace prefix of the catalog.

13

Description of another wine of the cellar.


Example 2.3 is the catalog of available types of wines storing information such as their properties (color, alcoholic strength), their origin, their price and their year of production. This information was inspired by data found on the web site of the Société des Alcools du Québec. Other information such as the name, the code and format are given as attributes within the start-tag. While the value of an element can be an arbitrarily complex tree of elements, attribute values can only be single string values. Strings for attribute values must be delimited by either matching ' or ". These delimiters have the same meaning and this convention is convenient when embedding a quote of one type within a string value. In case the two types of quotes are needed within a single string, one can use the predefined entities &apos; and &quot; (explained in Section 3.1).

The structure of an XML instance file may seem arbitrary and, in a sense, it is. In order to make sure that its processing is efficient, it is important that the structure of the information be in the right format (i.e. embedded within the correct tags and in the correct order) and that all the mandatory information be present. This verification could be performed by the program using the information but it would more interesting to detect errors or lack of information when the instance file is created. Thus the program needing the data can be sure that the file structure follows the expected format. This validation process, similar to the static type checking for a programming language, is explained in the next chapter but before, we will look at namespaces, another important concept in XML instance documents.

Example 2.3. Excerpt of WineCatalog.xml, the XML instance document holding the content of the wine catalog, it is included in Example 2.2 (Example D.2 shows the XML content)

  1 <wine-catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  (1)
        xsi:schemaLocation="http://www.iro.umontreal.ca/lapalme/wine-catalog  (2)
                            WineCatalog.xsd"
        xmlns="http://www.iro.umontreal.ca/lapalme/wine-catalog">        (3)
  5     <wine name="Domaine de l'Île Margaux" ... >                      (4)
            <properties>
                <color>red</color>
                <alcoholic-strength>12.5</alcoholic-strength>
                <nature>still</nature>
 10         </properties>
            <origin>
                <country>France</country>
                <region>Bordeaux</region>
                <producer>
 15                 SCEA Domaine de L'Île Margaux (B.P. 5)
                </producer>
            </origin>
            <comment>Ready for drinking now</comment>
            <food-pairing>
 20             Accompanies <emph>Bordelaise ribsteak</emph>,            (5)
                <bold>pork with prunes</bold> or magret de canard.
            </food-pairing>
            <price>22.80</price>
            <year>2002</year>
 25     </wine>
        ...
        <wine name="Prado Rey Roble" ... >
            <properties>
                <color>red</color>
 30             <alcoholic-strength>12.5</alcoholic-strength>
                <nature>still</nature>
            </properties>
            <origin>
                <country>Spain</country>
 35             <region>Old Castille</region>
                <producer>Real Sitio de Ventosilla SA</producer>
            </origin>
            <price>35.25</price>
            <year>2002</year>
 40     </wine>
    </wine-catalog>

1

Start of the wine catalog description.

2

Namespace and file name of the Schema for this instance file.

3

Namespace for the wine catalog, useful to differentiate the wine elements that appear both in the catalog and the cellar book.

4

Description of a wine.

5

Some words can be emphasized by surrounding them with bold and emph tags.