Handling null, empty, and missing values

Read the content on this topic to know about 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

Related topics

Editing-the-web-service-XML

Automatically-mapping-XML-elements

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 Systemis 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 Systemis consuming

Assumption

In the following tables, it is assumed that "name" is an XML element or attribute that is missing, empty, or nulled, and is mapped to a AR Systemfield 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 Systemsets the XML element or attribute to or from the AR System field.


Tip

To render a null field, create an empty element with xsi:nil=true as an attribute. This is preferred over omitting the element in the request document, or creating an empty element with the nullable attribute set to false.

Incoming XML elements mapped to fields


minOccurs=0 and nillable=false

minOccurs=0 and nillable=true

minOccurs=1 and nillable=false

minOccurs=1 and nillable=true

Missing <name>

Name is not modified, or it is set to AR default. (1)

Name is not modified, or it is set to AR default. (1)

Invalid XML (2)

Invalid XM. (2)

<name></name> OR <name/>

Name=$NULL$ or xsd default (3)

Name=$NULL$ or xsd default (3)

Name=$NULL$ or xsd default (3)

Name=$NULL$ or xsd default (3)

<name xsi:nil="true></name> OR <name xsi:nil="true"/>

Invalid XML. (5)

Name=$NULL$ (4)

Invalid XML (5)

Name=$NULL$ (4)

  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 Systemdefault 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 an invalid XML. The client should not send an invalid XML packet, but if it does, AR Systemdisplays an error message.
  3. When the XML element has empty content, AR Systemfirst tries to use the XSD default if it exists.
    There are two different defaults—the AR Systemdefault value and the XSD default value. For empty contents, AR Systemalways uses the default XSD value. Otherwise, it sets the field to NULL.
  4. When the XML element has xsi:nil=true, AR Systemsets 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 an invalid XML. Clients should not send an invalid XML packet. Also, AR Systemsets this field to NULL, disregarding the defaults.
  6. To an XML element to be returned in a Web Service output,AR Systemadds 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


use=optional

use=required

Missing <name>

Name is set to XSD default, or it is not modified, or it is set to AR default.1

Invalid XML (2)

name= ""

Name=$NULL$ (3)

Name=$NULL$ (3)

  1. If an attribute is defined with use=optional and the attribute is missing from the XML, AR Systemtries to use the XSD default. If the XSD default does not exist, AR Systemtreats the attribute like a missing field. Therefore, in a Create operation, the field to which this attribute is mapped assumes the AR Systemdefault 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 Systemdisplays an error message.
  3. If an attribute has an empty value, AR Systemsets the mapped field to NULL and disregards the defaults.

Outgoing XML elements mapped to fields


minOccurs=0and nillable=false

minOccurs=0and nillable=true

minOccurs=1and nillable=false

minOccurs=1and nillable=true

Name is $NULL$

Missing name (2)

<name xsi:nil= "true"/> (1)

<name/> (3)

<name xsi:nil= "true"/> (1)

Name is ""

<name/>

<name/> (4)

<name/> (4)

<name/> (4)

<name> is not mapped

Missing name

Missing name

Invalid XML

Invalid XML

  1. If a field is null, AR Systemgenerates the XML as xsi:nil=true. However, it can do so only if nillable=true.
  2. If nillable is false, AR Systemdoes 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 Systemgenerates an element with empty content.
  4. If a character field contains an empty string, AR Systemgenerates an element with empty content. AR Systemfields 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


use=optional

use=required

Name is $NULL$

name="" (1)

name="" (1)

Name is ""

name="" (2)

name="" (2)

<name> is not mapped

Missing name

Invalid XML

  1. If a field is null, AR Systemgenerates an attribute with empty content.
  2. If a character field contains an empty string, AR Systemgenerates an attribute with empty content. AR Systemfields 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 only have 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 an invalid XML, and the client should not send a document containing such XML. However, AR Systemignores 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 Systemreturns an error. If the number of entries is more than the maxOccurs, AR Systemreturns 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 Systemreturns an error.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*