validate (r9)

Survey questions sometimes need specific restrictions on how a respondent may answer them. Use the validate (alias validation) widget or tag to create custom restrictions, known as validations.

The validate tag evaluates a logical condition and prevents the respondent from continuing to the next page if the condition is false. Every validation must include a message that communicates to the respondent why they cannot proceed.

To ensure a good respondent experience, it is important to carefully test validations. The conditions should be tested to ensure respondents can't get stuck, unable to meet the requirements. It is also important to write clear validation messages so that respondents can easily determine how to pass the validation.

Syntax

Validations may be written as a tag on a question or table, or as a standalone widget. Validations consist of a condition followed by a message decorator. 

validate: [condition] { message: Text to display if condition not met }

Be sure to write the condition in terms of what is needed for the respondent to continue. The validation is triggered when the condition evaluates as false.

Multiple validation tags may be added to a single question. See below for examples.

'warn: y' decorator

Add the warn: y decorator to a validation to allow respondents to continue past a validation after it has been triggered once. Be sure to clearly indicate they may continue in the message.

validate: [condition] { message: Text to display if condition not met } { warn: y }

'flag' tag

When a validation is triggered, a validation icon will appear next to the question(s) that are referenced in the condition. Include the flag tag, along with one or more question IDs, to add this icon to other questions on the page and help direct the respondent's attention. 

validate: [condition] { message: Text to display if condition not met }
flag: QX

# Add flag to multiple questions with a comma-separated list: 
flag: QX, QY, QZ

'value' placeholder

In validation conditions, the [value] placeholder can be used instead of $QX, where 'X' is the question ID where the validation has been added. Note that the [value] placeholder is only available when the validate tag is included on a question and not used as a standalone widget.

validate: anyChecked([value],1) { message: Message here }

Validations in tables

If a validation condition for a table needs to be repeated for every row or column of the table, a row validation or column validation may be more appropriate. See Table row validation and column validation (r9) for more information and examples.

The [value] placeholder may also be used in a table with the validate tag, instead of a row validation. See the example below.

Examples

Validate response against a previous question

The following example uses validation in Q2 to ensure that one's responses in the table match the responses from the previous question (Q1). If the respondent answers that they have children in either (or both) age ranges, they must enter a quantity for the age range(s) they selected. If they leave a text field blank or enter '0' for one of the age ranges in which they indicated they have children, the validation message will be displayed, indicating there is a discrepancy, and their response in Q2 should be amended.

See demo See code Restart demo

1. Do you have children living in your home?
type: checkbox
exclusive: 99
1. 0-7 years old
2. 8-17 years old
99. No kids in those age ranges

2. How many kids do you have in the following age ranges?
type: integer table
showif: anyChecked($Q1,1,2)
maxlen: 2
datatype: whole
rowsfrom: Q1
validate: (anyChecked($Q1,1) and $Q2R1 > 0) or noneChecked($Q1,1) { message: In the previous question, you indicated you had a child between the ages of 0-7. }
validate: (anyChecked($Q1,2) and $Q2R2 > 0) or noneChecked($Q1,2) { message: In the previous question, you indicated you had a child between the ages of 8-17. }

Multiple validations with 'value' placeholder

In this example, QFAVORITE2 has two separate validations. The conditions use the [value] placeholder instead of writing out $QFAVORITE2.

See demo See code Restart demo

set list: COLORS3
1. red
2. orange
3. yellow
4. green
5. blue
6. indigo
7. violet

FAVORITE2. Pick two colors.
type: checkbox
optsfrom: COLORS3
validation: countChecked([value]) == 2 {message: Please select exactly 2 answers.}
validation: anyChecked([value],6,7) {message: You must pick a purplish color.}

Using 'value' placeholder for table row validation

The [value] placeholder functions as a row or column validation when used on a table. 

See demo See code Restart demo

3. Select red or blue in each row.
type: checkbox table
rowsfrom: series[1..3]
1. Red 
2. Blue 
3. Yellow
validate: anyChecked([value],1,2) { message: Select red or blue. }

With row validation, the example above would be written as follows:

row validate: anyChecked($Q3R[id],1,2) { message: Select red or blue. }

Open-end text validation

The validate tag can also evaluate text responses. Q4 in the example below requires an answer of 'yellow' to continue.

See demo See code Restart demo

4. What color is a banana?
type: text
maxlen: 6
validate: [value] eq 'yellow' { message: Sorry, that is not the correct color. Try again. }

Allowing respondents to continue with 'warn: y'

The following example uses a validation with the warn decorator. If '1' is selected, the respondent may click the continue button a second time to move past the validation without changing their response. It's a good idea to make this clear in the validation message so that the respondent doesn't think they're stuck.

See demo See code Restart demo

S5. Make a selection.
type: radio
1. 1
2. 2
validate: $QS5 == 1 { message: Are you sure? Click continue again to confirm. } { warn: y }

Using listUnique for table validation

Use the listUnique function in a validation to require respondents to enter a unique response for every row or column in a table.

This basic example references the series function as the list name, and uses [id] as the iterator, which pulls in each option ID established in the series. Each field reference constructed becomes '$Q6R1', '$Q6R2', and so on. The function then returns the result of the evaluated statement, examining whether any of the rows' text entries match the others.

See demo See code Restart demo

6. Try writing the exact same text in more than one row.
type: text table
rowsfrom: series[1..5]
validation: listUnique(series[1..5]; $Q6R[id]) {message: Every row must be unique.}

Using other tags alongside validations

There are many tags in SPL that provide built-in validations, especially for numeric and open-end text questions. Tags such as datatype, maxlength and minlength, or maxchecked, minchecked, and numchecked are designed to handle many common use cases. It is often a good idea to review the available tags and see if they can provide the desired validation.

If needed, validate tags can be used alongside other tags to produce the desired restrictions. In the following example, we want to ensure the respondent enters a six-digit number. The datatype: whole tag restricts the allowed input to numeric characters. The maxlen: 6 tag sets the size of the text field on the page and limits the length of the response to six characters. Lastly, the validate condition length($Q7) == 6 specifies that the response must be six characters long.

See demo See code Restart demo

7. Please enter your six digit catalog number:
instructions: Enter exactly six digits.
prefix: Catalog Number:
type: integer
datatype: whole
maxlen: 6
validate: length($Q7) == 6 {message: Try again. The number you enter must be a 6 digit number.}

In this example, Q8 must be eight characters long and contain only letters or numbers. The datatype: word tag restricts the allowed input to letters and numbers (no spaces or special characters). The maxlen: 8 tag sets the size of the text field on the page and limits the length of the response to eight characters. Lastly, the validate condition length($Q8) == 8 specifies that the response must be eight characters long.

See demo See code Restart demo

8. Please create an eight character username.
instructions: Use only letters and numbers.
type: text
datatype: word
maxlen: 8
validate: length($Q8) == 8 { message: Please use only letters and numbers. You must enter eight characters. }

Validations with Perl and regular expressions

As with other tags and decorators such as cvalue or condition decorators, validation conditions accept Perl syntax. For text entry questions, regular expressions (a.k.a. "regex") is useful for validating responses. In the example below, regex is used to ensure that only letters are entered for the first name and last name fields. For more information, see Perl code in surveys.

See demo See code Restart demo

starttable: 9 
intro: Please enter your contact information to receive your incentive. 
type: text
cellalign: left
validate: ($Q9RFIRST =~ /^[a-zA-Z]+$/) {message: Please ensure there are only letters in your first name.}
validate: ($Q9RLAST =~ /^[a-zA-Z]+$/) {message: Please ensure there are only letters in your last name.}

FIRST. First Name

LAST. Last Name 

EMAIL. Email 
datatype: email 

endtable