Re: XML Schemas: Best Practices

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

Hi Kohsuke,

Thanks for the comments!  Let me try to address them:

> > Subject: Implementing variable content containers using
> >          "dangling types".
> 
> >           <xsd:import namespace="http://www.sensor.org"/>
> >
> >           The instance document must then identify a schema
> >           that defines sensor_type.  Thus, at run time
> >           we are matching up the reference to sensor_type
> >           with the implementation of sensor_type.  Wow!
> 
> Validators are not required to honor schemaLocation attributes nor
> import elements. Nor there is no guarantee that your validator parses
> additional schemata found at the run time. In fact, I believe MSXML4.0
> doesn't honor xsi:schemaLocation at all.
> 
> It is completely legal to abandon validating sensor_type and make
> validation fail.

If a schema validator ignores schemaLocation (or, as in the case above,
there is no schemaLocation) then the validator is expected to "locate"
the appropriate schemas by some other means.   Obviously, if the
validator is unable to locate the appropriate schema then it will fail. 
This is true regardless of whether you're using dangling types or not. 
I guess that I don't really understand your point.  Perhaps you could
explain further?

> I think your technique causes an interoperability problem.
 
Applications must be written to expect that the content of an element
with a dangling type is undefined (rather, it is defined at run time). 
With that understanding, applications will need to be designed to handle
a run-time-defined collection of objects.  Certainly this is more
difficult than if the collection is statically defined, but it is
certainly possible (and desirable).
 
> Although I think your idea is a cool trick ...

No, it is not a "trick".  It is a rather simple but powerful design
pattern, and it is the only way to do many things, e.g., it is the only
way to extend a simpleType.  I think that this design pattern will be
used heavily by schema designers.  In my work we use it a lot.

> "Default namespace - targetNamespace or XMLSchema?"
> ==============================================================
> 
> >    <xsd:element name="Book" type="CardCatalogueEntry"/>
> >
> > Since there is no namespace qualifier on CardCatalogueEntry it is
> > referencing the default namespace. What is the default namespace?
> > XMLSchema is the default namespace.
> 
> It's wrong. The default namespace is the no-namespace. 

This question is a bit out of context, but let me try to explain.  What
we were saying here is that when a schema (which has a targetNamespace)
<include>s a no-namespace schema, the components in that no-namespace
schema are namespace-coerced to the namespace of the <include>ing schema
(the one with the targetNamespace).  So, after namespace coercion has
occurred the Book element and the CardCatalogueEntry type is in the
targetNamespace (of the <include>ing schema).  If the default namespace
(of the <include>ing schema) is XMLSchema then Book's reference to
CardCatalogueEntry fails (obviously the XMLSchema namespace has no type
called CardCatalogueEntry).  On the other hand, if the <include>ing
schema is designed so that the default namespace is the targetNamespace
then after namespace coercion CardCatalogueEntry is now in the default
namespace (the targetNamespace) and Book's reference to
CardCatalogueEntry is valid.  You are correct that "before"
namespace-coercion occurs the default namespace is the no-namespace. 
However, after an <include> the components are no longer in
no-namespace, they are in the targetNamespace of the <include>ing
schema.  Hope this clears things up.  

> "Hide(Localize) Namespace vs Expose Namespace"
> ==============================================================
> 
> Your "Camera.xml (namespaces hidden)" is wrong.
> 
> ---------------------------------------
> <?xml version="1.0"?>
> <my:camera xmlns:my="http://www.camera.org"
>          xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
>          xsi:schemaLocation=
>                    "http://www.camera.org
>                     Camera.xsd">
>     <body>
>         <description>Ergonomically designed casing for easy handling</description>
>     </body>
>     <lens>
>         <zoom>300mm</zoom>
>         <f-stop>1.2</f-stop>
>     </lens>
>     <manual_adapter>
>         <speed>1/10,000 sec to 100 sec</speed>
>     </manual_adapter>
> </my:camera>
> ---------------------------------------
> 
> <body>,<lens>, and <manual_adapter> are right. They should be
> unqualified. But you still need to qualify <description>,<zoom>,<f-stop>
> and <speed> because they are global declarations.

Hmm, you seem to have a different copy than I have.  I just looked at
the web site and it defines the camera schema as:

    <xsd:element name="camera">
        <xsd:complexType>
             <xsd:sequence>
                 <xsd:element name="body" type="nikon:body"/>
                 <xsd:element name="lens" type="olympus:lens"/>
                 <xsd:element name="manual_adapter" 
                              type="pentax:manual_adapter"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

The body, lens, and manual_adapter elements are all declared locally. 
Perhaps you could point me to where you see them declared globally?

> In fact, there is no reason to use elementFormDefault="unqualified". 
> As a best practice, you should state that 
> elementFormDefault="unqualified" is strongly discouraged.

For this issue we don't dictate a "Best Practice".  Rather, we point out
the pros and cons of each approach.  Each approach has scenarios for
which it is preferred, as we describe in the online document.  
 
> Multi-Schema Project: Zero, One, or Many Namespaces?
> ==============================================================
> 
> First, you can redefine any components in any namespace. You just need
> one extra layer if you want to redefine components in the other
> namespace.

Yes, you are correct.  I have been planning on putting this in but
haven't gotten around to it.  Thanks for reminding me.

> And it seems to me that your analysis misses the most important point;
> namely, reusability of instance documents.  By saying chameleon schema
> is a preferable approach, you end up creating instances like
> 
> <foo xmlns="companyA">
>   <department>
>     <person>
>       <first> Joe </first>
>       <last> Black </last>
>     </person>
>   </department>
> </foo>
> 
> <foo xmlns="companyB">
>   <department>
>     <person>
>       <first> George </first>
>       <last> Bush </last>
>     </person>
>   </department>
> </foo>
> 
> How can others recognize that person elements have the same semantics?

No, they don't have the same semantics (assuming targetNamespace
provides a level of semantics to components within it).  The whole point
is that Chameleon components can have multiple semantics.  That's the
power of Chameleon components!

> Creating Variable Content Container Elements
> ==============================================================
> 
> In "advantages" of method 1, you wrote
> 
> >    <Catalogue>
> >         <Book> ... </Book>
> >         <CD> ... </CD>
> >         <Magazine> ... </Magazine>
> >         <Book> ... </Book>
> >    </Catalogue>
> 
> But you can't do this. You will do <CD:CD> ... </CD:CD>. 

Yes, you are correct. I was somewhat loose in the description.  I will
change it to be more precise.  Thanks.

Thanks again for all your comments!   /Roger