XML for Data: Using XML Schema archetypes

Adding archetypal forms to your XML Schemas

Kevin Williams (kevin@blueoxide.com), CEO, Blue Oxide Technologies, LLC

Kevin Williams is the CEO of Blue Oxide Technologies, LLC, a company that designs XML and Web service creation software. Visit their Web site at http://www.blueoxide.com. Kevin can be reached for comment at kevin@blueoxide.com.

Summary: In the first installment of his new column, Kevin Williams describes the benefits of using archetypes in XML Schema designs for data and provides some concrete examples. He discusses both simple and complex types, and some advantages of using each. Code samples in XML Schema are provided.

View more content in this series

Tag this!

Date: 01 Jun 2001
Level: Introductory
Activity: 2302 views

In my turn on the Soapbox (see Resources), I mentioned in passing how archetypes can be used in XML Schema designs for data to significantly minimize the coding and maintenance effort required for a project, and to reduce the likelihood of cut-and-paste errors. In this column, I'm going to give you some examples of the use of archetypes in XML schemas for data, and show just where the benefits lie.

What are archetypes?

Archetypes are common definitions that can be shared across different elements in your XML schemas. In earlier versions of the XML Schema specification, archetypes had their own declarations; in the released version, however, archetypes are implemented using the simpleType and complexType elements. Let's take a look at some examples of each.

Simple archetypes

Simple archetypes are created by extending the built-in datatypes provided by XML Schema. The allowable values for the type may be constrained by so-called facets, a fancy term for the different parameters that may be set for each built-in datatype. It's also possible to create a simple type by defining a union of two other datatypes or by creating a list of values that correspond to some other datatype. For our purposes, however, the restrictive declaration of simple types is the most interesting. Let's take a look at some examples.

Say you have a table in a relational database describing a loan that looks like Listing 1.

CREATE TABLE loan (
  loanID INT IDENTITY,
  duration SMALLINT,
  initialBalance DECIMAL(10, 2),
  currentBalance DECIMAL(10, 2),
  interestRate DECIMAL(5, 2))

Obviously, all of these values map directly onto built-in datatypes in XML Schema, so you could just declare the elements in the target schema as anonymous simpleType elements and be done. However, it makes sense to define some simple archetypes to use instead. Let's take a look at some reasons why.

Benefits of using data archetypes?

Less code required
Maintenance and updates are simplified
The chance for cut-and-paste errors is reduced

Consistency

The most obvious reason to use archetypes in the example is because the two balance fields both convey a similar concept -- that of a currency value -- and they are declared the same way. When designing a relational database, you'd probably go to great pains to ensure that these fields are defined the same way. The hypothetical example database may even define a user type called Balance that is defined to be a decimal with 10 significant figures and two past the decimal. You should define types with the same rigor in the XML schemas. This makes the schemas more readable -- a cleverly named data type conveys information about the type of data being described -- and ensures consistency across the entire schema (no more problems trying to store a decimal(10, 2) in a field declared as decimal(9, 2)). Also, if you define archetypal forms once and use them in all the schemas you produce from the data, it simplifies writing consumers that can handle all the schemas you create. Every time consumers need to handle a document from OurCompany, they can be assured that all the currency values will be defined the same way.

Reduced coding

If you define archetypes once and reuse them wherever necessary, you can significantly decrease the size of the schema. For example, say you were defining an element to hold the two balance fields in the SQL table described earlier. You could define the data elements with anonymous simple types, as in Listing 2.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="loan">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="initialBalance">
          <xs:simpleType>
            <xs:restriction base="xs:decimal">
              <xs:totalDigits value="10" />
              <xs:fractionDigits value="2" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="currentBalance">
          <xs:simpleType>
            <xs:restriction base="xs:decimal">
              <xs:totalDigits value="10" />
              <xs:fractionDigits value="2" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
      </xs:sequence>      
    </xs:complexType>
  </xs:element>
</xs:schema>

The code in Listing 2 seems fine, but what happens if you encounter megainflation and need to change the upper bound on loans from $100 million to $10 billion? You'd have to change it everywhere you have a balance declared, which, of course, is asking for trouble. However, you could instead use a named simple archetype for the balance, as in Listing 3.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="loan">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="initialBalance" type="balance" />
        <xs:element name="currentBalance" type="balance" />
      </xs:sequence>      
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="balance">
    <xs:restriction base="xs:decimal">
      <xs:totalDigits value="10" />
      <xs:fractionDigits value="2" />
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

In Listing 3, the advantages of named simple archetypes are obvious. The schema declaration is much shorter (even if you squash the declarations for whitespace, it's still about 30 or so bytes smaller), making the schema definition more manageable. Plus, if that megainflation does kick in (due to unreasonably large tax cuts or some other ludicrous reason), changing the spec to handle the larger loan sizes involves changing one declaration, that of the balance simple type.

Complex archetypes

You can apply the same sort of logic to the issue of complex archetype reuse. Say you have a customer table in a manufacturing database. The table might, in part, look like Listing 4.

CREATE TABLE customer (
  customerID int IDENTITY,
  mailingAddress varchar(50),
  mailingAddress2 varchar(50) NULL,
  mailingCity varchar(30),
  mailingState char(2),
  mailingZip char(10),
  shippingAddress varchar(50),
  shippingAddress2 varchar(50) NULL,
  shippingCity varchar(30),
  shippingState char(2),
  shippingZip char(10))

Again, you have some alternatives: You can declare all of these fields as simple types, or you can create an address complex archetype and reuse that where necessary. Let's see in Listing 5 how this would be done.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="customer">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="mailingAddress"> 
          <xs:complexType> 
            <xs:sequence>
              <xs:element name="address">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="50" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="address2" minOccurs="0">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="50" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="city">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="30" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="state">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:length value="2" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="zip">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="10" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="shippingAddress"> 
          <xs:complexType>
            <xs:sequence>
              <xs:element name="address">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="50" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="address2" minOccurs="0">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="50" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="city">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="30" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="state">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:length value="2" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="zip">
                <xs:simpleType>
                  <xs:restriction base="xs:string">
                    <xs:maxLength value="10" />
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Whew. Did I mention that schemas tend to get a little long winded? In the case of Listing 5, an obvious alteration presents itself -- creating an address complex archetype. If you do that, our schema becomes a little bit shorter, as shown in Listing 6.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="customer">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="mailingAddress" type="addressType" /> 
        <xs:element name="shippingAddress" type="addressType" /> 
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:complexType name="addressType">
    <xs:sequence>
      <xs:element name="address">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:maxLength value="50" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="address2" minOccurs="0">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:maxLength value="50" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="city">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:maxLength value="30" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="state">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:length value="2" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="zip">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:maxLength value="10" />
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Again, the version in Listing 6 is much shorter and, I submit, easier to understand. Combine this example with the fact that you can introduce more archetypes, such as a simple archetype for an address line that will be used by the address and address2 elements, and you can see how proper use of archetypes can help keep your schemas manageable.

Conclusion

This installment has taken a look at the use of archetypes in the design of XML schemas. You've seen that judicious use of archetypes, together with smart naming conventions, can make schemas shorter and easier to maintain. There's an additional benefit to using archetypes -- a little trick to ensure consistent styling of your information -- but that's a topic for another installment (look for it soon).

Resources

Information on defining XML Schema structures may be found in the first part of the W3C's XML Schema specification. For information on built-in datatypes and the constraining facets that are available for them, check the second part of the XML Schema specification. For a more easily digested summary of both parts of the XML Schema spec, take a look at the W3C Primer on XML Schema.
More accessible information about schemas can be found in my book Professional XML Schemas, from Wrox Press (which should be on the shelves by the time you read this).
Again, I can't emphasize enough what a great tool IBM's XML Schema Quality Checker is. Download it and check it out -- it's a lifesaver.
Catch up with Kevin Williams's opinion piece on why XML Schema works much better than DTDs when working with data.
IBM's DB2 database provides relational database storage, plus pureXML to quickly serve data and reduce your work in the management of XML data.
Find other articles in Kevin William's XML for Data column.

About the author

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=XML

ArticleID=12010

ArticleTitle=XML for Data: Using XML Schema archetypes

publish-date=06012001

author1-email=kevin@blueoxide.com

author1-email-cc=