Configuring Conditions

Conditions show or hide controlled questions based on the response a respondent provides to one or more controlling questions. Single and compound condition types are available. See Universal Survey Block Parameters on the Configuing Surveys page for more information on how to assign the conditions described below to a question or instruction block in your survey.

The following parameters will be within an array of conditions at the highest level in the survey JSON. See the example below to see where the conditions array belongs:

{
 "name": "Survey Name",
 "description": "Survey Description",
 "licenseText": "© License Text",
 "sections": [
   ...
 ],
 "conditions": [
   {
     “name”: “condition1”,
     ...
   }
 ],
 "scores" :
 [
   ...
 ]
}

Configuring Single Conditions

Single conditions are based on a specific response or range of responses to a question. A question controlled by a single condition is only displayed to respondents if the condition evaluates to true based on the controlling question.

Parameter JSON Code Example Description Requiredness
The name of the condition "name": "condition1"
  • The unique name of the condition.
  • Condition names are referenced by the controlled question or when configuring compound conditions.
 Required
The type of the condition "type": "single"
  • The type of the condition.
  • For single conditions, the type should be single.
 Required
The name of the question block "blockName": "q1" The name of the controlling question block being evaluated by the condition. Required
The operation of the condition
  • "operation": "=="
  • "operation": "<"
  • "operation": "NOT_INCLUDES"

The operation used to compare the triggering response to the respondent's response. The following operations are supported for single conditions:

  • == - The response is exactly equal to the value in the answer node.
  • != - The response is not equal to the value in the answer node.
  • < - The response is less than the value in the answer node.
  • > - The response is greater than the value in the answer node.
  • <= - The response is less than or exactly equal to the value in the answer node.
  • >= - The response is greater than or exactly equal to the value in the answer node.
  • INCLUDES - The response includes the value in the answer node. This operation can only be used for multiple-choice question types.
  • NOT_INCLUDES - The response doesn't include the value in the answer node. This operation can only be used for multiple-choice question types.

The following operations are supported for single conditions when the triggering response is an optional answer:

  • == - The optional answer is exactly equal to the value in the optionalAnswer node.
  • != - The optional answer is not equal to the value in the optionalAnswer node.
 Required
The answer
  • "answer": {...}
  • "optionalAnswer": {...}
  • The container for the response type and response value that the condition evaluates against.
  • Options include:
    • answer
    • optionalAnswer
 Required
In the "answer" node:
The type of answer
  • "type": "name"
  • "type": "number"
  • "type": "static"

The type of response value that the condition evaluates against. The type must match the controlling question's type and be consistent with the operation of the condition.

Type Controlling Question Type Operations
name singleChoice, multipleChoice singleChoice: ==, !=

multipleChoice: INCLUDES, NOT_INCLUDES
number visualScale, numberScale, numberEntry ==, !=, <, <=, >, >=
static date, time, dateTime ==, !=, <, <=, >, >=
Required
The triggering value of a name type answer "name": "1" The condition uses the operation (==, !=, INCLUDES, NOT_INCLUDES) to evaluate the respondent's response against this value. Required if type is name
The triggering value of a number type answer "number": "10" The condition uses the operation (==, !=, <, >, <=, >=) to evaluate the respondent's response against this value. Required if type is number
The triggering value of a static type answer
  • "value": "13:50"
  • "value": "2022-12-02"
  • "value": "2022-12-02T13:50"
  • The condition uses the operation (==, !=, ==, !=, <, <=, >, >=) to evaluate the respondent's response against this value.
  • The value must be in the format YYYY-MM-DD, HH:MM, or YYYY-MM-DDTHH:MM and correspond to the type of the block referenced in the blockName.
 Required if type is static
In the "optionalAnswer" node:
The name of a triggering optional answer "name": "q1-notapplicable" The condition uses the operation (==, !=) to evaluate the respondent's response against this value. Required

Example Single Condition JSON Configuration

The following JSON snippet illustrates the single condition parameters described above. The configuration below is not reviewed or licensed for use in collections.

"conditions": [
  {
    "name": "condition1",
    "type": "single",
    "blockName": "q1",
    "operation": "<=",
    "answer": {
      "type": "number",
      "number": "20",
    }
  },
  {
    "name": "condition2",
    "type": "single",
    "blockName": "q2",
    "operation": "==",
    "answer": {
      "type": "name",
      "name": "1",
    }
  }
{
    "name": "condition3",
    "type": "single",
    "blockName": "q3",
    "operation": "NOT_INCLUDES",
    "answer": {
      "type": "name",
      "name": "q1-1",
    }
  }
{
    "name": "condition4",
    "type": "single",
    "blockName": "q4",
    "operation": ">",
    "answer": {
      "type": "static",
      "value": "13:50",
    }
  }
{
    "name": "condition-optional",
    "type": "single",
    "blockName": "q5",
    "operation": "==",
    "optionalAnswer": {
      "name": "q1-notapplicable"
    }
  }
]

Configuring Compound Conditions

Compound conditions combine two or more conditions using an operation.

Parameter JSON Code Example Description Requiredness
The name of the condition "name": "condition3"
  • The unique name of the condition.
  • Condition names are referenced by the controlled question or when configuring compound conditions.
 Required
The type of the condition "type": "compound"
  • The type of the condition.
  • For compound conditions, the type should be compound.
 Required
The operation of the condition "operation": "AND"

The operation that connects the conditions within this compound condition. The following operations are supported for compound conditions:

  • AND - All conditions within this compound condition must be met to display the question.
  • OR - Any condition within this compound condition must be met to display the question.
 Required
The conditions being compounded conditions": ["condition1",
"condition2"]		 The single or compound conditions that are being evaluated in the compound condition. Required

Example Compound Condition JSON Configuration

The following JSON snippet illustrates the compound condition parameters. The configuration is not reviewed or licensed for use in survey collections.

"conditions': [
  {
      "name": "condition6",
      "type": "compound",
       "operation": "OR",
       "conditions": ["condition1", "condition2"]
  },
  {
      "name": "condition7",
      "type": "compound",
       "operation": "AND",
       "conditions": ["condition3", "condition4"]
  }
]