Handling null, empty, and missing values

This topic discusses the rules for handling null, empty, and missing values.

Elements and attributes mapped to fields

The rules for mapping XML elements and attributes to fields can be divided into four groups.

• Incoming XML elements
• Incoming XML attributes
• Outgoing XML elements
• Outgoing XML attributes

AR System has two sources for incoming XML:

• The request for published web service published through AR System
• A response from an external web service that AR System is consuming

Similarly, there are two sources for outgoing XML:

• The response from a web service published through AR System
• The request to an external web service that AR System is consuming

In these tables it is assumed that "name" is an XML element or attribute that is missing, empty, or nulled, and is mapped to a AR System field called Name. The column headers are the design-time properties. For example, "name" is defined with minOccurs=0 and nillable=false. The row headers are run-time representations. For example, in the incoming XML packet "name" appears as <name></name>. The table specifies how AR System sets the XML element or attribute to or from the AR System field.

Incoming XML elements mapped to fields

1. When an XML element is missing, AR System treats it the same way as a missing field. Therefore, in a create operation, the field to which the XML element is mapped assumes the AR System default value (or NULL if there is no default). In a set operation and in consumption, the field remains unchanged.
2. When an XML element is missing, in spite of minOccurs=1, it is invalid XML. The client should not send such an XML packet, but if it does, AR System displays an error message.
3. When the XML element has empty content, AR System first tries to use the xsd default if it exists. (There are two different defaults—the AR System default value and the xsd default value. For empty contents, AR System always uses the default xsd value.) Otherwise, it sets the field to NULL.
4. When the XML element has xsi:nil=true, AR System sets the field to NULL and disregards the defaults.
5. When the XML element has xsi:nil=true but is not defined with nillable=true, it is invalid XML. Clients should not send such an XML packet. Also, AR System sets this field to NULL, disregarding the defaults.
6. To an XML element to be returned in a Web Service output, AR Server adds the xsi:nil attribute only if the XML element has a NULL value, is defined to allow NULL values (nillable=true), and there is no default value assigned to it.

Incoming XML attributes mapped to fields

1. If an attribute is defined with use=optional and the attribute is missing from the XML, AR System tries to use the xsd default. If the xsd default does not exist, AR System treats the attribute like a missing field. Therefore, in a create operation, the field to which this attribute is mapped assumes the AR System default value (or NULL if there is no default). In a set operation and in consumption, the field remains unchanged.
2. If an attribute is defined with use=required, it should not be missing. Otherwise, the XML is invalid and clients should not send such an XML packet. AR System displays an error message.
3. If an attribute has an empty value, AR System sets the mapped field to NULL and disregards the defaults.

Outgoing XML elements mapped to fields

1. If a field is null, AR System generates the XML as xsi:nil=true. However, it can do so only if nillable=true.
2. If nillable is false, AR System does not generate the element at all for null fields. However, it can do so only if minOccurs=0.
3. If nillable is false and minOccurs=1, AR System generates an element with empty content.
4. If a character field contains an empty string, AR System generates an element with empty content. AR System fields with empty strings are extremely unusual; they can be specified only with the driver program or an API call.

Outgoing XML attributes mapped to fields

1. If a field is null, AR System generates an attribute with empty content.
2. If a character field contains an empty string, AR System generates an attribute with empty content. AR System fields with empty strings are extremely unusual; they can be specified only with the driver program or an API call.

Elements mapped to forms

While elements mapped to fields should have only maxOccurs=1, elements mapped to forms can have maxOccurs>1. (Elements mapped to fields can have maxOccurs>1, but at run time, only one element should appear in the incoming XML.)

For incoming XML, you can map the base form only to an element with maxOccurs=1. (It is acceptable if maxOccurs>1 at design time, but at run time there is one element at most.) 

You can map the child forms to elements with maxOccurs>1. If the number of XML elements does not fall in the range set by minOccurs and maxOccurs, it is invalid XML, and the client should not send a document containing such XML. However, AR System ignores the minOccurs and maxOccurs constraints while parsing this XML.

For outgoing XML, you can map the base form to an element with maxOccurs>1 in case of publishing and a get operation. This implies that multiple entries in the base form are to be retrieved. If the number of entries in the base form is less than the minOccurs, AR System returns an error. If the number of entries is more than the maxOccurs, AR System returns only until the maxOccurs amount. 

You can map child forms to elements with maxOccurs>1. If the number of matching entries in the child form does not fall in the range set by minOccurs and maxOccurs, AR System returns an error.