xml-dev - Re: XML Schemas: Best Practices

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

Hi Folks,

I feel like we have covered very well the issues involved in deciding 
whether to hide/localize namespaces in a schema versus expose namespaces
in instance documents (see http://www.xfront.com/BestPractices.html).

I would like to now move on to the issue of element versus type reuse.  
First, let's recall what this issue is about: 

"When should an item be declared as an element versus when should an
item be declared as a type?"

As always, I think best with a concrete example to look at:

Case 1. Element Reuse

   - Declare an element for reuse:

      <element name="Elevation">
         <simpleType>
              <restriction base="integer">
                  <minInclusive value="-1290"/>
                  <maxInclusive value="29028"/>
              </restriction>
         </simpleType>
      </element>

   - Reuse the element:

      <element name="Boston">
         <complexType>
            <sequence>
               <element ref="city:Elevation"/>
            </sequence>
         </complexType>
      </element>

Case 2.  Type Reuse

   - Declare a type for reuse:

      <simpleType name="Elevation">
           <restriction base="integer">
               <minInclusive value="-1290"/>
               <maxInclusive value="29028"/>
           </restriction>
      </simpleType>

   - Reuse the type:

      <element name="Boston">
         <complexType>
            <sequence>
               <element name="Elevation"  type="city:Elevation"/>
            </sequence>
         </complexType>
      </element>

Regardless of which of the above approaches is taken, the following
instance document snippet is valid:

<Boston>
      <Elevation>125</Elevation>
</Boston>

When is it best to declare Elevation as an element and reuse the
element, and when is it best to declare Elevation as a type and reuse
the type?  More generally, what guidelines would you give to someone who
asks you whether to declare a component as a type or as an element?

Here is something to consider with regards to element versus type reuse:

Element substitution versus type substitution.  

Declaring Elevation as an element allows us to create a
substitutionGroup and then substitute <Elevation> with other members of
the substitutionGroup.  For example:

      <element name="BostonElevation" 
               substitutionGroup="city:Elevation">
          <simpleType>
              <restriction base="city:Elevation"> 
                  <minInclusive value="0"/> 
                  <maxInclusive value="400"/>
              </restriction>
           </simpleType>
      </element>

      <element name="Elevation">
         <simpleType>
              <restriction base="integer">
                  <minInclusive value="-1290"/>
                  <maxInclusive value="29028"/>
              </restriction>
         </simpleType>
      </element>

      <element name="Boston">
         <complexType>
            <sequence>
               <element ref="city:Elevation"/>
            </sequence>
         </complexType>
      </element>

An instance document can take either of these forms:

      <Boston>
            <Elevation>125</Elevation>
      </Boston>

or:

      <Boston>
            <BostonElevation>125</BostonElevation>
      </Boston>

Observe how element substitution enables us to substitute <Elevation>
with <BostonElevation>.

On the other hand, declaring Elevation as a type allows us to create a
new type which derives from the Elevation type.  Where the Elevation
type is used, types derived from Elevation may also be used.  For
example:

      <simpleType name="BostonElevation">
          <restriction base="city:Elevation">
              <minInclusive value="0"/> 
              <maxInclusive value="400"/>
          </restriction>
      </simpleType>

      <simpleType name="Elevation">
           <restriction base="integer">
               <minInclusive value="-1290"/>
               <maxInclusive value="29028"/>
           </restriction>
      </simpleType>

      <element name="Boston">
         <complexType>
            <sequence>
               <element name="Elevation"  type="city:Elevation"/>
            </sequence>
         </complexType>
      </element>

An instance document can take either of these forms:

      <Boston>
            <Elevation>125</Elevation>
      </Boston>

or:

      <Boston>
            <Elevation xsi:type="BostonElevation">125</Elevation>
      </Boston>

Observe how type substitution enables us to substitute the Elevation
type with BostonElevation type.

These examples illustrate that declaring an item as an element enables
element substitution, declaring an item as a type enables type
substitution.  This, of course, does not answer our question of when
should an item be declared as an element versus when it should be
declared as a type.  Rather, it pushes us to ask more questions - 

     When do we want to enable element substitution?  Does it make 
     sense to allow any element in an instance document to be 
     element substitutable?  If not, why not?  What characterizes
     those elements for which it is desirable to allow element 
     substitution?  What characterizes those elements for which it 
     is not desirable to allow element substitution?

      When do we want to enable type substitution?  Does it make 
      sense to allow any element in an instance document to be type 
      substitutable?  If not, why not?  What characterizes
      those elements for which it is desirable to allow type 
      substitution?  What characterizes those elements for which 
      it is not desirable to allow type substitution?

My feeling is that if we can answer these questions then our original
question will be answered.  Would anyone care to take a shot at
answering these questions?   /Roger