Validation Rules

These rules must be followed when authoring a survey schema to ensure the form works correctly.

Unique Field Keys

Every key in the fields array must be unique across the entire survey, and so must every sub_key. Duplicate keys will cause unpredictable behavior in conditional logic and data export.

// Correct — all keys are unique
{ "key": "full_name" }
{ "key": "age" }
{ "key": "email" }

// Incorrect — duplicate key
{ "key": "full_name" }
{ "key": "full_name" }  // ❌ duplicate

Regex Escaping

When using regular expressions in JSON, backslashes must be double-escaped. A single \ in a regex pattern becomes \\ in the JSON string.

Regex Pattern	JSON Value
\d	"\\d"
\s	"\\s"
\+	"\\+"

// Phone number — double-escaped backslashes
"regex": "^\\+?[1-9]\\d{1,14}$"

// Email address
"regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"

Array Defaults

The default_value property must always be an array, even when only a single value is pre-selected.

// Correct
"default_value": ["MALE"]

// Incorrect
"default_value": "MALE"  // ❌ must be an array

Conditional Key Matching

Keys referenced in conditionals must exactly match the key values defined in the fields array. Mismatched casing or typos will cause the logic to silently fail.

"fields": [
  { "key": "type_of_house", ... }
],
"conditionals": {
  "1": "type_of_house == 'APARTMENT' >> room_count"  // ✅ matches exactly
}

Values compared against a choice field must match one of its choices exactly. A value that isn't a choice can never match, so the rule never fires.

"choices": ["Owner-occupied", "Fully rented out", "Mixed (owner + tenants)"]

"1": "tenancy_status == 'Owner-occupied' >> estimated_annual_rent"       // ✅ a listed choice
"2": "tenancy_status == 'Vacant / unoccupied' >> estimated_annual_rent"  // ❌ not a choice

Section References

When a survey defines pages, each field's section must match a page id exactly.

"pages": [{ "id": "section_owner", "label": "Owner Information" }],
"fields": [
  { "key": "owner_name", "section": "section_owner", ... },  // ✅
  { "key": "owner_phone", "section": "owner", ... }          // ❌ no page with id "owner"
]

Grouped Choices

When choices is an object:

• Every group must be an array with at least one option.
• The field must have a sub_key, and it must not clash with any other key or sub_key.
• Option text can repeat across groups (e.g. "Other"), but group names must be unique.

TIP

The Survey Builder checks all of these rules as you edit and lists any problems under the affected field or rule.