Grouping types

Param combos

It's also possible in XINS to defined a group of input or output parameters. There are 4 kinds of group:

  • inclusive-or

    If a group is inclusive-or then at least one of the parameters defined in the param-ref should have a value.

  • exclusive-or

    If a group is exclusive-or then one and only one of the parameters defined in the param-ref should have a value.

  • all-or-none

    If a group is all-or-none then either none of the of the parameters defined in the param-ref should have a value or all.

  • not-all

    If a group is not-all then at least one of the parameters defined in the param-ref should not have a value.

Example:

<input>
  <param name="birthYear" required="false" type="_int32">
    <description>The birth date's year.</description>
  </param>
  <param name="birthMonth" required="false" type="_int32">
    <description>The birth date's month.</description>
  </param>
  <param name="birthDay" required="false" type="_int32">
    <description>The birth date's day.</description>
  </param>
  <param name="birthCountry" required="false" type="_text">
    <description>The country where the person is born.</description>
  </param>
  <param name="birthCity" required="false" type="_text">
    <description>The city where the person is born.</description>
  </param>
  <param name="age" required="false" type="Age">
    <description>An example of input for a int8 type with a minimum and maximum.</description>
  </param>
  <!-- One of the two parameters must be filled but not both -->
  <param-combo type="exclusive-or">
    <param-ref name="birthYear" />
    <param-ref name="age"       />
  </param-combo>
  <!-- At least one of the two parameters must be filled -->
  <param-combo type="inclusive-or">
    <param-ref name="birthCountry" />
    <param-ref name="birthCity"    />
  </param-combo>
  <!-- These parameters must be filled together or not filled at all -->
  <param-combo type="all-or-none">
    <param-ref name="birthYear"  />
    <param-ref name="birthMonth" />
    <param-ref name="birthDay"   />
  </param-combo>
</input>

If the condition is not met, XINS will return a result with an _InvalidRequest error code if the request does not match the input param-combo or an _InvalidReponse error code if the result does not match the output param-combo.

You can find an example using the groups in the function demo\xins-project\apis\allinone\spec\ParamCombo.fnc.

Attribute combos

It is also possible to defined similar constraint on attributes of elements defined in the data section (See next chapter). This is done using the attribute-combo and the attribute-ref elements.

Example:

<data>
  <contains>
    <contained element="person" />
  </contains>
  <element name="person">
    <description>A person</description>
    <attribute name="birthCountry" required="false" type="_text">
      <description>The country where the person is borned.</description>
    </attribute>
    <attribute name="birth-city" required="false" type="_text">
      <description>The city where the person is borned.</description>
    </attribute>
    <attribute name="age" required="false" type="Age">
      <description>An example of input for a int8 type with a minimum and maximum.</description>
    </attribute>
    <!-- At least one of the two attributes must be filled -->
    <attribute-combo type="inclusive-or">
      <attribute-ref name="birthCountry" />
      <attribute-ref name="birth-city" />
    </attribute-combo>
  </element>
</data>

Combos based on values

It is also possible to define constraints based on the value of one parameter (and not only on whether the parameter is set or not). This is done by added the value attribute to the param-ref element or attribute-ref element for attribute-combo.

Example:

<input>
  <param name="salutation" required="true" type="Salutation">
    <description>The gender of the person.</description>
  </param>
  <param name="maidenName" required="false" type="_text">
    <description>The maiden name.</description>
  </param>
  <!-- If the salutation is Madam, the maiden name is required -->
  <param-combo type="inclusive-or">
    <param-ref name="salutation" value="Madam" />
    <param-ref name="maidenName" />
  </param-combo>
</input>

The description of the type associated with the param-combo is then a bit different:

  • inclusive-or

    If the parameter has the defined value then the second parameter is required.

  • exclusive-or

    If the parameter has the value then the other parameter should not be filled, otherwise the second parameter is required.

  • all-or-none

    If the parameter has the value then the others parameters are required, otherwise the other parameters should not be set.

  • not-all

    If the parameter has the value then the other parameters should not be set.

For a better understanding, look at the ParamComboValue.fnc function provided in the allinone API.

It is also possible to have more than one param-ref with a value in the same param-combo.