Presents your 
XML E-NEWSLETTER for July 9, 2003

----------------------------------------

MAKE SMART XML DESIGN DECISIONS

When designing your XML solution, you have to make many decisions. 
These decisions will help shape your solution and define how your XML
documents are built. Let's look at some of these decisions; then, we'll 
offer tips for steering you in the right direction.

GRANULARITY

One of the first design areas to investigate is granularity. This
defines how detailed your XML document will be. On the surface, the 
answer may be obvious--it needs to be as detailed as your data. The question,
though, is how much data belongs in a single document. Will your document
contain an item, a group of items or transaction, a group of 
transactions, or something else altogether?

For example, LISTING A shows a document containing an item; LISTING B
shows a document containing a group of transactions.

Listing A: item.xml
<itm>
  <sku>1234</sku>
  <qty>10</qty>
  <prc>100<prc>
</itm>

Listing B: transgroup.xml
<TransactionGroup>
  <Transaction>
    <Item>
      <SKU>1234</SKU>
      <Quantity>10</Quantity>
      <Price>100<Price>
    </Item>
    <Item>
      <SKU>8712</SKU>
      <Quantity>15</Quantity>
      <Price>10<Price>
    </Item>
    <Item>
      <SKU>235</SKU>
      <Quantity>99</Quantity>
      <Price>44<Price>
    </Item>
  </Transaction>
  <Transaction>
    <Item>
      <SKU>98234</SKU>
      <Quantity>6</Quantity>
      <Price>45.75<Price>
    </Item>
  </Transaction>
</TransactionGroup>

The granularity of your documents may be driven less by your ideal
design and more by the systems you're integrating. For example, if the source
or target system has a predefined granularity, you may have less flexibility.

GROUPING AND CONTAINMENT

Another common design decision is how you're going to arrange the data
in your documents into meaningful, logical groups. You also need to decide
whether to constrain the items in those groups with containers. The
solution is a little more difficult depending on your particular data. 
There are many design patterns that you can apply to help define the internal
structure of your document.

The grouping and containment will be somewhat related to the granularity
of the document. At a higher level, you might have a series of sets, and
even a container for that series, depending on if there is information
outside of the transactions in your document.

CONSISTENCY

It shouldn't be a design decision to be consistent--it should be a fact of life.

A key component of a successful design is consistency. This means having
well-defined rules and patterns for your XML document. If you usually
put a series of like elements in a container, then you should always 
try to do so. LISTING C shows an example of what not to do.

Listing C: badexample.xml
<Profiles>
  <user>
    <AccountId>9976723</AccountId>
    <UserID>johndough</UserID>
    <Password>funky123</Password>
    <realname>John Doe</realname>
  </user>
  <groups>
    <Group>
      <groupIdentifer>91235</groupIdentifier>
      <GroupNm>User Group</GroupNm>
      <Groupadmin>johndough</Groupadmin>
    </Group>
  </groups>
</Profiles>

Naming standards can be particularly problematic when it comes to
consistency. Your documents should follow precise rules for element names with
regards to capitalization and abbreviations. For instance, if you use an
element called UserId in one spot, don't use ObjectID or ObjectIdentifier
somewhere else--it's confusing and difficult to remember which is which.
A single rule that says Identifier is always abbreviated as Id is much
easier to remember.

Brian Schaffner is an associate director for Fujitsu Consulting. He provides
architecture, design, and development support for Fujitsu's Technology 
Consulting practice. 

----------------------------------------