[ XML Schema ] Caution using element substitution: the substitutingeleme

["Costello, Roger L." <costello@mitre.org>]

Hi Folks,

Elements substitutable for a head element are required to have types derived from the head element's type, but are not required to enforce the identity constraints of the head element.

In other words, the substitutable elements may not validate the same way as the head element. Beware!

Example: A BookStore consists of multiple Book elements and each Book element is uniquely identified by its ISBN. Here is an example BookStore:

<?xml version="1.0"?>
<BookStore xmlns="http://www.books.org";>
        <Book>
                <Title>Illusions The Adventures of a Reluctant Messiah</Title>
                <Author>Richard Bach</Author>
                <Date>1977</Date>
                <ISBN>0-440-34319-4</ISBN>
                <Publisher>Dell Publishing Co.</Publisher>
        </Book>
        <Book>
                <Title>The First and Last Freedom</Title>
                <Author>J. Krishnamurti</Author>
                <Date>1954</Date>
                <ISBN>0-06-064831-7</ISBN>
                <Publisher>Harper &amp; Row</Publisher>
        </Book>
</BookStore>

Note that each ISBN value is unique. We want the XML Schema to enforce that uniqueness.

A way to accomplish this is using xsd:key.

Let's look at the XML Schema code.

BookStore consists of an unbounded number of Book elements:

    <xsd:element name="BookStore">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="Book" maxOccurs="unbounded" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

Each Book element has a child ISBN element that is required to be unique:

    <xsd:element name="Book" type="BookType">
        <xsd:key name="PK">
            <xsd:selector xpath="bk:Book"/>
            <xsd:field xpath="bk:ISBN"/>
        </xsd:key>
    </xsd:element>

Here is Book's type definition:

    <xsd:complexType name="BookType">
        <xsd:sequence>
            <xsd:element name="Title" type="xsd:string" />
            <xsd:element name="Author" type="xsd:string" />
            <xsd:element name="Date" type="xsd:string" />
            <xsd:element name="ISBN" type="xsd:string" />
            <xsd:element name="Publisher" type="xsd:string" />
        </xsd:sequence>
    </xsd:complexType>

Some of my clients write Fiction books. I would like them to be able to customize their markup a bit. Namely, I would like for them to be able to use the element name "Fiction" rather than "Book".

So I declare Fiction to be substitutable for Book:

    <xsd:element name="Fiction" substitutionGroup="Book" />

My client constructs an XML document using Fiction elements:

<?xml version="1.0"?>
<BookStore xmlns="http://www.books.org";>
        <Fiction>
                <Title>Siddhartha</Title>
                <Author>Hermann Hesse</Author>
                <Date>1951</Date>
                <ISBN>0-486-40653-9</ISBN>
                <Publisher>Dover</Publisher>
        </Fiction>
        <Fiction>
                <Title>Atlas Shrugged</Title>
                <Author>Ayn Rand</Author>
                <Date>1957</Date>
                <ISBN>0-486-40653-9</ISBN>
                <Publisher>Penguin Books</Publisher>
        </Fiction>
</BookStore>

Oops! Notice that my client messed up, he mistakenly identified both books by the same ISBN value.

XML Schema validation of the document returns "valid".

Ouch!

My client has an error in his XML document and it is not being caught by schema validation.

Lesson Learned: element substitution is powerful. But without intimate knowledge of the head element, use of your substitution elements may result in XML documents with erroneous data that is not detected by schema validation.

/Roger