Working with Optional Elements

LightWave Client has several mechanisms to indicate the presence of optional elements. These mechanisms use a schema property to indicate the presence or absence of the element.

Using the hideIfEmpty Property

The hideIfEmpty: true property may be set on any element to indicate that if the source element is empty, it should not be included in the request payload. An element is considered empty when it is completely filled with the element's string padding character. Note that the string padding may be explicitly set on the element using the stringPadding property, or inherited from its parent. In the following example, if element optionalIfSpaces is filled with spaces, or optionalIfZeros is filled with zeros, the elements will not be included in the request payload.

JS

{
  "SampleType": {
    "elements": [
      {
        "name": "optionalIfSpaces",
        "type": "string",
		"size": 32,
        "hideIfEmpty": true,
        "stringPadding": "spaces"
      },
      {
        "name": "optionalIfZeros",
        "type": "string",
		"size": 32,
        "hideIfEmpty": true,
        "stringPadding": "zeros"
      }
    ]
  }
}

Using the isSet Property

The isSet property may be set on any element, and references an integer element which is used to indicate the presence or absence of the source element. In the following example, element theAddress is included in the request payload only if the value of element isAddressSet is nonzero. In this example, the hide property is set on the isAddressSet element to indicate that it is never included in the request payload. Note that when a response is received, the isSet target element is set to zero if the source element is not present in the response, or nonzero if it is present.

JS

{
  "SampleType": {
    "elements": [
      {
        "name": "isAddressSet",
        "type": "int",
		"size": 4,
		"hide": true
      },
      {
        "name": "theAddress",
        "type": "AddressType",
        "isSet": "isAddressSet"
      }
    ]
  }
}

Using the minOccurs Property

Using the minOccurs property as a mechanism to hide string elements is deprecated. New definitions should use hideIfEmpty.

The "minOccurs" : 0 property may be set on elements with "type" : "string" to indicate that if the source element is filled with the string padding character, it should not be included in the request payload. In the following example, if element optionalIfSpaces is filled with spaces, or optionalIfZeros is filled with zeros, the elements will not be included in the request payload

JS

{
  "SampleType": {
    "elements": [
      {
        "name": "optionalIfSpaces",
        "type": "string",
		"size" : 32,
        "minOccurs": 0,
        "stringPadding": "spaces"
      },
      {
        "name": "optionalIfZeros",
        "type": "string",
		"size": 32,
        "minOccurs": 0,
        "stringPadding": "zeros"
      }
    ]
  }
}