The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

All information submitted is secure.

My developerWorks:

My notifications:

Sign out

Select a language:

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

Date: 01 Jun 2001
Level: Introductory
Also available in: Japanese

Activity: 14272 views
Comments:

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

Close [x]

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.

Close [x]

Report abuse help

Report abuse

Report abuse submission failed. Please try again later.

Close [x]

developerWorks: Sign in

All information submitted is secure.

Close [x]

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.