xml-dev - Re: XML Schemas: Best Practices

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

Paul, 

Thanks for your input on "guidelines for when to hide/localize
namespaces in the schema versus when to expose namespaces in the
instance documents".  In your message you argued for the case of
hiding/localizing namespaces in the schema.  Let me try to summarize
your arguments.

You presented a nice example of a schema which has type definitions for
a postal address.  These are general definitions and would be placed in
a "schema of common address definitions".

One could imagine someone coming along wishing to define a schema for
moving from one address to another.  You argued that the "address change
schema" could take advantage of the common address schema.

An instance document conforming to the address change schema would
simply need to qualify the MovingFromAddress and MovingToAddress
elements.  The namespace of the elements from the common address schema
would be hidden.  Thus, the complexity of the common address schema
definitions are hidden from the user - they are localized to the
schema.  You argue that it is good to shield the user from the namespace
of those elements that come from the common address schema.

Is this an accurate depiction of your argument?  If so, please allow me
to play "devil's advocate"...  

WHY is it good to "shield the user from the namespace of those elements
that come from the common address schema"?  Some people would argue that
it is better to expose the namespace of the common address elements in
the instance document. UNDER WHAT CIRCUMSTANCES would you want to shield
the user from the namespaces and under what circumstances would you want
to explicitly expose the namespaces?  

In earlier discussions on xml-dev we came up with a pretty good set of
guidelines for when you want to shield and when you want to expose
namespaces, but I would like to get your thoughts on this (and other
people's thoughts as well).  /Roger


Paul Spencer wrote:
> 
> I have had some private communication with Roger, but been too busy to keep
> up with this thread. However, it is of great interest to me as I am
> developing best practice guidelines for the UK Government. (Roger - I now
> have authority to "participate in any best practice initiatives as long as
> they are not proprietary". I take that to mean that we can share information
> from the document I sent you.)
> 
> I am not totally up to date with the thread yet, but these are some thoughts
> on hiding namespace complexity:
> 
> <Caveat text="I am using the April draft"/>
> 
> In many cases, you will have a schema from which you wish to import
> definitions while hiding the imported schema namespace from the instance
> documents. It is simple and safe to re-use type definitions from one schema
> but make the resulting definitions part of the importing schema.
> 
> For example, consider a change of address. You might have a "common" schema
> full of re-usable types. This will have a namespace and contain a complex
> type:
> 
>   <xsd:complexType name="AddressUKpostalStructure">
>     <xsd:element name="Line" type="xsd:string" minOccurs="2" maxOccurs="5"/>
>     <xsd:element name="PostCode" type="egif:AddressPostCodeUKtype"
> minOccurs="0" maxOccurs="1"/>
>     <xsd:choice minOccurs="0" maxOccurs="1">
>       <xsd:element name="MailSortCode" type="egif:AddressMailSortCodeType"/>
>       <xsd:element name="WalkSortCode" type="egif:AddressWalkSortCodeType"/>
>     </xsd:choice>
>   </xsd:complexType>
> 
> This contains some simple types that I have not included. "egif:" is the
> namespace qualifier I have chosen to use here and in the importing schema
> for this namespace.
> 
> Now look at a change of address schema. This will contain the elements
> "MovingFromAddress" and "MovingToAddress". Both of these are of type
> egif:AddressUKpostalStructure. (Actually they are not in the real world, but
> I am trying to keep this simple).
> 
> A change of address instance document now just has to have a namespace for
> the change of address, not for the common definitions. That complexity is
> hidden from the user, but I still have complete control over namespaces and
> tag name clashes in my change of address schema.
> 
> How does this apply to the camera? I would suggest it doesn't. If you are
> using the "Nikon" schema, you need to make this explicit since it might have
> different definitions from a "Pentax" schema. OTOH, if you make a camera
> schema from generic "lens" and "body" schemas, I would use the techniques I
> mentioned. You could also derive types to make an explicit "Nikon" schema
> from the generic "lens" and "body".
> 
> A side issue: By re-using the address as a data type not an element, I have
> created two different address-type elements with different names. This is a
> benefit of re-using types rather than elements. On the other hand, there are
> instances where you will always give the resulting element the same name. In
> the USA, SSN might be an example. We have generally discouraged this because
> it is hardly harder to write:
> 
> <element name="SSN" type="common:SSNtype">
> 
> than
> 
> <element ref="common:SSN">
> 
> but we keep consistency by always re-using types (remembering that many
> inexperienced people will be writing the 16,000 schemas we believe we need).
> 
> Now to carry on reading and find that somebody else has written the same ...
> 
> Paul Spencer
> Author: XML Design and Implementation (Wrox Press)
> Co-author: Beginning XML (Wrox Press)
> Boynings Consulting - Delivering XML to industry and government
> http://www.boynings.co.uk/
> 
> -----Original Message-----
> From: Roger L. Costello [mailto:costello@mitre.org]
> Sent: 22 September 2000 15:45
> To: xml-dev@lists.xml.org
> Cc: costello@mitre.org; Cokus,Michael S.; Pulvermacher,Mary K.;
> Heller,Mark J.; JohnSc@crossgain.com; Ripley,Michael W.
> Subject: Re: XML Schemas: Best Practices
> 
> Hi Folks,
> 
> I am delighted to see the responses to my last message.  Clearly people
> are thinking about this issue and have strong feelings about hiding
> namespace complexities in the schema versus making namespaces explicit
> in instance documents.  This is good!  Now let's see if we can distill
> out some general guidelines on when to hide and when to make explicit.
> 
> ...