ISSUE-7 basic patterns text

This is the text worked on at the Tech Plenary for Issue 7.
 
Also attached are examples of the supporting wsdl and instance documents
that would drive the creation of testsuite entries for this. (N.B these
are for info only not for detailed review. Paul Downey is working on the
auto generation of  wsdl these which is a more sustainable way to go and
will allow people to submit schema fragments only as input to the
process.)  JonC
 
 

Defining Null Values


In addition to defining empty content models for elements, resulting in
a serialisation of : 

<emptyItem/> 

XMLSchema also permits the specification of a null value and the
omission of an element from the serialisation. 

<xs:element name="nullElement" type="xs:string" nillable="true"/> 

<xs:element name="omittableElement" type="xs:string" minOccurs="0"/> 

It is also legal in Schema to combine the two techniques: 

<xs:element name="name" nillable="true" minOccurs="0" /> 

meaning that the element may be absent from the document or annotated
with xsi:nil="true" and a different semantic interpretation associated
with each. 

In the databinding world this combination is problematic in that
toolkits must be able to distinguish between content that has not been
assigned (minOccurs="0") and content that is to be represented as null
(xsi:nil="true"). The generated code for some tools do not allow the
developer to specify that an element is null and should be serialised or
that it has not been specified and does not, in fact, exist. 

In the worst case scenario toolkits can serialise any unassigned
elements as an empty tag with the xsi:nil="true" attribute irrespective
of whether the schema element definition is nillable="true" or not. In
addition Some tooling is unable to correctly serialise elements that
have a value of 'null' but also have content (in the form of attributes)
and will represent these elements as empty in the serialisation. 

Guidance to schema authors


The following table shows the possible combinations of nillable and
minOccurs values: 


	nillable="false"	 nillable="true"	
minOccurs="0"	 OK(see below)	 Ambiguous	
minOccurs="1"	 OK	 OK	
minOccurs >1	 OK	 OK	

nillable="true" and minOccurs="0". It is only this combination of
nillable="true" and minOccurs="0" that is ambiguous and should be
avoided by the schema author. All other combinations will give a good
experience with the majority of toolkits. 

nillable="false" & minOccurs="0". This combination may prove problematic
with a very small number of toolkits. Where appropriate the schema
author MAY need to code the schema defensively specifying
nillable="true" and minOccurs="0" to accommodate instance documents
already in use that generated by incorrectly implemented toolkits that
send unassigned variables in the code as elements in the documents
decorated with 'xsi:nil="true" ' 

Note that the combination of 'nillable' with minOccurs cardinality
greater than 1 is permitted and may be useful in the creation of a
partially populated array that will be well handled by all toolkits. 

e.g. 

<xs:complexType name="PartialArray"
<xs:sequence>
<xs:element name="item" type="xs:string" nillable="true" minOccurs="5"/>
</xs:sequence>


<xs:element name="partialArray" type="tns:PartialArray"/>


<partialArray>
<item>raised</item>
<item xsi:nil="true"/>
<item>in progress</item>
<item xsi:nil="true"/>
<item>complete</item>
</partialArray>


Advice to implementers.


*	The Basic Patterns test suite exercises the ability to cope with
all legal combinations of nillable and minOccurs="0" with and without
the presence of attributes. 
*	Developers SHOULD have full control over the existence of an
element in the resultant serialisation as well as its value. 
*	The annotation of an element with xsi:nil="true" is only
permissible if the schema specifies nillable="true". Implementations
MUST NOT send an element with xsi:nil="true" to represent an unassigned
element. 



When to use nillable="true" or minOccurs="0"

The decision when to use nillable="true" or minOccurs="0" is a semantic
decision on the part of the schema author. 

Use nillable='true' when you wish to make a semantic distinction in your
documents between something that is unknown and something that is just
'left unsaid'. Consider also the importance of this decision with
respect to how this data will be stored in a database and communicate
the meaning of nillable/minOccurs in annotations to the schema or
supporting documentation.