xml-dev - Re: XML Schemas: Best Practices

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

Note: The below message is also online at:

http://www.xfront.com/ElementVersusType.html

Hi Folks,

Based upon last week's discussions, here is an attempt to summarize the
guidelines for:

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

When presenting the guidelines, this example will be used:

Example.  

Should "Warranty" be declared as an element:

                 <element name="Warranty">
                     …
                 </element>

or as a type:

                  <complexType name="Warranty">
                        …
                  </complexType>


** Guidelines For When To Declare An Item As An Element Versus When To
Define It As A Type **

[1] When in doubt, make it a type.  You can always create an element
from the type, if needed.  With a type other elements can reuse that
type.   

Example.  If you can't decide whether to make Warranty an element or a
type, then make it a type:

                  <complexType name="Warranty">
                        …
                  </complexType>

If you decide that you need a Warranty element, you can create one using
the Warranty type:

                 <element name="Warranty" type="a:Warranty"/>

(Recall that elements and types are in different Symbol Spaces.  Hence,
you can have an element and type with the same name.)

[2] If the item is not intended to be an element in instance documents
then define it as a type.  

Example.  If you will never see this in an instance document:

                  <Warranty> 
                       …
                  </Warranty>

then define Warranty as a complexType.   

[3] If the item's content is to be reused by other items then define it
as a type.  

Example. If other items need to use Warranty's content, then define
Warranty as a type:

                   <complexType name="Warranty">
                         …
                   </complexType>
                   …
                   <element name="PromisaryNote" type="a:Warranty"/>
                   <element name="AutoCertificate" 
                            type="a:Warranty"/>

The example shows two elements - PromisoryNote and AutoCertificate -
reusing Warranty's content. 

[4] If the item is intended to be used as an element in instance
documents, and it's required that sometimes it be nullable and other
times not, then it must be defined it as a type.  

Example.  Let's first see how not to do it.  Suppose that we create a
Warranty element:

                <element name="Warranty">
                     …
                </element>

The Warranty element can be reused elsewhere by ref'ing it: 

               <element ref="a:Warranty"/>

Suppose that we also need a version of Warranty that supports a null
value.  You might be tempted to do this:

               <element ref="a:Warranty" nullable="true"/>

However, this is not legal.  This dynamic morphing capability (i.e.,
reusing a Warranty element declaration while simultaneously adding
nullability) cannot be achieved using elements.  The reason for this is
that the ref and nullable attributes are mutually exclusive - you can
use ref, or you can use nullable, but not both.  The only way to
accomplish the dynamic morphing capability is by defining Warranty as a
type:

               <complexType name="Warranty">
                      …
               </complexType>

and then reusing the type:

               <element name="Warranty" nullable="true" 
                        type="a:Warranty"/>
                 …
               <element name="Warranty" type="a:Warranty"/>

In the first case Warranty is nullable.  In the second case it's not
nullable. 

(Note: This is a new feature of the Sept. 12 version of the spec.  The
element version was legal in earlier specs, but is no longer legal.)

[5] If the item is intended to be used as an element in instance
documents and synonyms/aliases are to be allowed to substitute for the
element, then it must be declared as an element.  

Example.  Suppose that we would like to enable instance document authors
to use the vocabulary (i.e., tag name) Warranty, Guarantee, or Promise:

                     <Warranty> 
                          …
                     </Warranty>
                      …

                     <Guarantee> 
                          …
                     </Guarantee>
                     …

                     <Promise> 
                          …
                     </Promise>
                   
To enable this substitutable-tag-name capability, Warranty, Guarantee,
and Promise must be declared as elements, and made members of a
substitutionGroup:

                 <element name="Warranty">
                     …
                 </element>
                 <element name="Guarantee"
                          substitutionGroup="a:Warranty"/> 
                 <element name="Promise" 
                          substitutionGroup="a:Warranty"/>


Have I missed any cases?  Are these guidelines clear?  Do you agree? 
Disagree?  /Roger