Data Validation

When a numeric value is entered into Stipa, the application checks if the value is greater than the minimum bound specified for the attribute and less than the maximum bound. If not, an alert is displayed, and the value is ignored. Data Collection Protocols can also be customized to include more sophisticated data validations, targeting specific attributes. Seven types of data validations are currently supported. These include Distinct Value, Value Combination, Inclusion Set, Exclusion Set, Inclusion Switch, Exclusion Switch, and Exclusive Interval. Adding a validation requires that you manually edit the protocol XML.

A custom validation is created by adding a new Validation element to the Validations element of the relevant Attribute. The validation applies only to the attribute it was added to, but there is no limit to the number of validation you can create for each attribute. Each Validation element must include a Type element indicating the type of validation you would like to add. The Validation element may need to include additional child elements as well, depending on the type of validation being created. These include an Attributes element, within which one or more Attribute element can be listed; a Dependencies element, within which one or more Dependency element can be listed; and a Values element, within which one or more Value element can be listed. Attribute elements should contain the identifier of the relevant attribute. Likewise, for categorical attributes, Dependency and Value elements should contain the identifier of the relevant category.

Distinct Value. This validation prevents duplicate values from being entered into a set of attributes located within the same form. Attributes to include in the evaluation should be specified in a list of Attribute elements nested within Attributes. Any Dependency or Value elements included in the validation will be ignored.

<Attribute>
  <ID>color 1</ID>
  <Label>Color One</Label>
  <Type>category</Type>
  <SharedList>color choices</SharedList>
  <MaxCount>1</MaxCount>
  <Validations>
    <Validation>
      <Type>distinct value</Type>
      <Attributes>
        <Attribute>color 2</Attribute>
        <Attribute>color 3</Attribute>
        <Attribute>color 4</Attribute>
      </Attributes>
    </Validation>
  </Validations>
</Attribute>

Figure 1. XML snippet illustrating how to add a Distinct Value validation to an attribute. In this example, if a user selects red for the color 1 attribute, they cannot select red for attributes color 2, color 3, or color 4.

Value Combination. This validation prevents illegal combinations of values from being entered for the target attribute. Values to include in the evaluation should be specified in a list of Value elements nested within Values. The validation will fail if two or more values entered for the target attribute are present in the specified list. Any Dependency or Attribute elements included in the validation will be ignored.

<Attribute>
  <ID>colors</ID>
  <Label>Colors</Label>
  <Type>category</Type>
  <SharedList>color choices</SharedList>
  <MaxCount>3</MaxCount>
  <Validations>
    <Validation>
      <Type>value combination</Type>
      <Values>
        <Value>green</Value>
        <Value>red</Value>
      </Values>
    </Validation>
  </Validations>
</Attribute>

Figure 2. XML snippet illustrating how to add a Value Combination validation to an attribute. In this example, users are prohibited from selecting both green and red for the colors attribute

Inclusion Set. This validation limits what values can be entered for the target attribute based on what data has been previously entered for specific attributes of the same form. Permissible values should be specified in a list of Value elements nested within Values. Attribute-value combinations that limit permissible values should be specified in the Attributes and Dependencies elements, respectively. Constraining attributes should be specified in a list of Attribute elements nested within Attributes. Constraining values should be specified in a list of Dependency elements nested within Dependencies. If any of the values specified in Dependencies have been entered for any of the attributes specified in Attributes, only those values specified in Values will be allowed during data entry. For continuous data, specify the minimum allowable value by adding a Value element having the format <Value>min=number</Value>, where number is replaced with the desired minimum value (inclusive). A maximum allowable value can be specified in a similar way, as can the minimum and maximum values of dependencies. A Dependency element can also contain an asterisk. In that case, the constraint is invoked if any data has been entered for any of the constraining attributes.

<Attribute>
  <ID>shade</ID>
  <Label>Shade</Label>
  <Type>category</Type>
  <SharedList>color choices</SharedList>
  <MaxCount>1</MaxCount>
  <Validations>
    <Validation>
      <Type>inclusion set</Type>
      <Attributes>
        <Attribute>color</Attribute>
      </Attributes>
      <Dependencies>
        <Dependency>green</Dependency>
      </Dependencies>
      <Values>
        <Value>olive</Value>
        <Value>hunter</Value>
        <Value>lime</Value>
      </Values>
    </Validation>
  </Validations>
</Attribute>

Figure 3. XML snippet illustrating how to add an Inclusion Set validation to an attribute. In this example, if a user select green for the color attribute, they can only select olive, hunter, or lime for the shade attribute.

Exclusion Set. This validation is identical to the Inclusion Set validation, except that non-permissible values, rather than permissible values, are specified in a list of Value elements nested within Values. If any of the values specified in Dependencies have been entered for any of the attributes specified in Attributes, none of the values specified in Values will be allowed during data entry.

<Attribute>
  <ID>color</ID>
  <Label>Color</Label>
  <Type>category</Type>
  <SharedList>color choices</SharedList>
  <MaxCount>1</MaxCount>
  <Validations>
    <Validation>
      <Type>exclusion set</Type>
      <Attributes>
        <Attribute>transparency</Attribute>
      </Attributes>
      <Dependencies>
        <Dependency>*</Dependency>
      </Dependencies>
      <Values>
        <Value>white</Value>
      </Values>
    </Validation>
  </Validations>
</Attribute>

Figure 4. XML snippet illustrating how to add an Exclusion Set validation to an attribute. In this example, if a user specifies any value for the transparency attribute, they are prohibited from choosing white for the color attribute.

Inclusion Switch. This validation manages access to certain attributes based on the values entered for the target attribute. Attributes whose access will be managed should be specified in a list of Attribute elements. These attributes will be hidden unless one or more of the values specified in Dependencies is selected for the target attribute. A Dependency element can also contain an asterisk. In that case, any non-null entry will cause attributes listed in Attributes to be displayed. Any Value elements included in the validation will be ignored.

<Attribute>
  <ID>color</ID>
  <Label>Color</Label>
  <Type>category</Type>
  <SharedList>color choices</SharedList>
  <MaxCount>1</MaxCount>
  <Validations>
    <Validation>
      <Type>inclusion switch</Type>
      <Attributes>
        <Attribute>shade</Attribute>
      </Attributes>
      <Dependencies>
        <Dependency>*</Dependency>
      </Dependencies>
    </Validation>
  </Validations>
</Attribute>

Figure 5. XML snippet illustrating how to add an Inclusion Switch validation to an attribute. In this example, the shade attribute will be hidden unless a user selects a value for the color attribute.

Exclusion Switch. This validation is identical to the Inclusion Switch validation, except that attributes specified in Attributes will be visible unless one or more of the values specified in Dependencies is selected for the target attribute.

<Attribute>
  <ID>color</ID>
  <Label>Color</Label>
  <Type>category</Type>
  <SharedList>color choices</SharedList>
  <MaxCount>1</MaxCount>
  <Validations>
    <Validation>
      <Type>exclusion switch</Type>
      <Attributes>
        <Attribute>shade</Attribute>
        <Attribute>transparency</Attribute>
      </Attributes>
      <Dependencies>
        <Dependency>none</Dependency>
      </Dependencies>
    </Validation>
  </Validations>
</Attribute>

Figure 6. XML snippet illustrating how to add an Exclusion Switch validation to an attribute. In this example, the shade and transparency attributes will be visible unless a user selects none for the color attribute.

Exclusive Interval. This validation applies to numeric attributes representing an interval, where one attribute records the start of the interval, and a second records the end. The validation prevents entries that result in overlapping intervals. It also prevents entries that result in an inverted interval; that is, an interval whose start value is greater than its end value, relative to intervals that were previously recorded. Attributes representing the start and end values of the interval should be specified in a list of Attribute elements nested within Attributes. The first Attribute in the list corresponds to the interval start, and the second element corresponds to the interval end. Any additional Attribute elements will be ignored, together with any Dependency or Value elements included in the validation.

<Attribute>
  <ID>stripe top</ID>
  <Label>Stripe Top</Label>
  <Type>number</Type>
  <Precision>0</Precision>
  <Validations>
    <Validation>
      <Type>exclusive interval</Type>
      <Attributes>
        <Attribute>stripe top</Attribute>
        <Attribute>stripe bottom</Attribute>
      </Attributes>
    </Validation>
  </Validations>
</Attribute>

Figure 7. XML snippet illustrating how to add an Exclusive Interval validation to an attribute. In this example, color stripes are not permitted to overlap, as measured by the stripe top and stripe bottom attributes.