The Situation:

"I'm not sure what's going on, but mixing references to different XSD files is giving me problems, something to do with namespaces, I think."

or

"I wish I could de-compose the repeatable definitions in my Alfresco Web-Forms. I'd like less redundancy in my XML data model."

(This is a follow up note based on Chris' blog entitled 'Inline Callouts in Alfresco WCM').

The Solution:

Chris talked about how an Alfresco Web-Form can include a dynamically populated drop-down list by referring to an external fragment of another XSD.

Having this new 'webscript://' protocol for inclusions is just great. The beauty is that the inclusion points to a Web-Script which itself doesn't have to return a static file, but could instead derive a list based on any sort of dynamic data. See 'Using dynamic types in schemas' for more information.

An added benefit of this approach is that multiple Web-Forms may refer to the same Web-Script without the need for redundant replication of XSD complexType definitions. You can imagine how this is very useful for project implementations with a more complex data model. Having duplicate definitions semantically meaning the same thing used for the same purpose lying around in an assortment of Web-Forms is a bit messy and prone to inconsistent changes.

Any problems with this approach? Well, possibly. What if you used a different XML namespace across different Web Forms? Or you wanted to re-use your dynamic XSD content across several WCM projects? Logical use of different namespaces can be seen as good practice.

Some Examples:

In the original example we used:

<xs:include schemaLocation="webscript://ixxus/getList..etc.." />

The problem here is that the XSD to include must have the same namespace as the enveloping XSD. This may not be a problem for you, but if it is, we'll need to do something else.

How about using this instead:

<xs:import schemaLocation="webscript://ixxus/getList...etc..." namespace="http://www.ixxus.com/util/list-include" />

Using 'import' over 'include' allows us to specify the namespace of the XSD that we're including (as a tag attribute). Very handy.

Is that all? What else do we need to change?

The FTL containing the re-usable dynamic XSD inclusion fragment would look a little like this

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns:alf="http://www.alfresco.org"
 xmlns:ix-list="http://www.ixxus.com/util/list-include"
 targetNamespace="http://www.ixxus.com/util/list-include"
 elementFormDefault="qualified">
 ...
</xs:schema>

and the base XSD that wants to include the above XSD would look a little like this:

<xs:schema
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns:alf="http://www.alfresco.org"
 xmlns:ix-list="http://www.ixxus.com/util/list-include"
 xmlns:proj1="http://www.ixxus.com/project/1"
 targetNamespace="http://www.ixxus.com/project/1"
 elementFormDefault="qualified">

 <xs:import schemaLocation="webscript://ixxus/getList?ticket={ticket}&amp;storeid={storeid}&amp;list=colours" namespace="http://www.ixxus.com/util/list-include" />
 <xs:element name="Article">
 <xs:complexType>
 <xs:sequence>
 <xs:element name="title" type="xs:normalizedString" />
 <xs:element name="Colours" nillable="false">
 <xs:annotation>
 <xs:appinfo>
 <alf:label>Colours</alf:label>
 </xs:appinfo>
 </xs:annotation>
 <xs:simpleType>
 <xs:list itemType="ix-list:colours" />
 </xs:simpleType>
 </xs:element>
 </xs:sequence>
 </xs:complexType>
 </xs:element>
</xs:schema>

The main thing to notice is that the namespace of this example Web-Form is "http://www.ixxus.com/project/1" (proj1), whilst the namespace of the inclusion is "http://www.ixxus.com/util/list-include" (ix-list). So although 'proj1' may change between Web Forms or between Web Projects, the XSD inclusion can always stay as 'ix-list'.

I'm no expert on XML schema but I hope this proves useful for beginner Alfresco developers. Incidentally, Peter Monks has a nice introduction to using includes as part of an Alfresco Web Form definition. Also, here's a well-presented discussion on the import Vs include option.