Altova Mailing List Archives


Re: XML Schemas: Best Practices

From: "Roger L. Costello" <costello@-----.--->
To: xml-dev@-----.---.---
Date: 10/15/2000 3:33:00 PM
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

Disclaimer

These Archives are provided for informational purposes only and have been generated directly from the Altova mailing list archive system and are comprised of the lists set forth on www.altova.com/list/index.html. Therefore, Altova does not warrant or guarantee the accuracy, reliability, completeness, usefulness, non-infringement of intellectual property rights, or quality of any content on the Altova Mailing List Archive(s), regardless of who originates that content. You expressly understand and agree that you bear all risks associated with using or relying on that content. Altova will not be liable or responsible in any way for any content posted including, but not limited to, any errors or omissions in content, or for any losses or damage of any kind incurred as a result of the use of or reliance on any content. This disclaimer and limitation on liability is in addition to the disclaimers and limitations contained in the Website Terms of Use and elsewhere on the site.