Interview Import Format

Mayetik can create a complete interview — metadata, questions, and branch rules — from a single JSON file. This document describes the format.

Two formats are accepted:

• Native Mayetik JSON (described here) — minimal, human-writable, maps directly to the Mayetik data model.
• SurveyJS JSON — automatically detected by the presence of a pages array. Types are mapped to Mayetik equivalents; unsupported types are skipped.

---

Quick start

Download one of the ready-made templates from the Import section on any interview list page:

Template	Description
interview-template.json	Full-featured example showing all 16 question types
simple-survey.json	Minimal 3-question survey — good starting point
branching-survey.json	Shows branch rules with multiple condition types

Open the template in any text editor, replace the example values, and upload it.

---

Top-level fields

{
  "title": "...",
  "description": "...",
  "language": "en",
  "stakeholderGroup": "...",
  "questions": [ ... ]
}

Field	Type	Required	Notes
title	string	Yes	Must be unique within the project
description	string	No	Shown to admins; not visible to participants
language	"en" | "es"	No	Defaults to "en"
stakeholderGroup	string	No	Used in project-level synthesis reports
questions	array	Yes	At least one question required

Imported interviews always start in draft status. Publish manually when ready.

---

Question fields

{
  "order": 1,
  "text": "...",
  "hint": "...",
  "type": "text",
  "required": false,
  "isTerminal": false,
  "options": null,
  "branchRules": []
}

Field	Type	Required	Notes
order	integer ≥ 1	Yes	Display position; must be unique; used by branch rule targetOrder references
text	string	Yes	The question body shown to participants
hint	string	No	Helper text shown below the question
type	string	No	Defaults to "text". See table below
required	boolean	No	Defaults to false
isTerminal	boolean	No	Defaults to false. Ends the interview immediately after this question is answered
options	object | array | null	Depends on type	See per-type details below
branchRules	array	No	See Branch rules section

---

Question types

text

Multi-line free-form text box. No options needed.

{ "order": 1, "text": "Describe your role", "type": "text" }

---

short_text

Single-line input with optional format validation.

{
  "order": 2,
  "text": "Employee ID",
  "type": "short_text",
  "options": {
    "patternKey": "alphanumeric",
    "pattern": "^[A-Za-z0-9]+$",
    "patternHint": "Letters and numbers only",
    "maxLength": 20,
    "placeholder": "e.g. EMP12345"
  }
}

Option	Type	Notes
maxLength	integer	Maximum characters allowed. Defaults to 64
placeholder	string	Greyed-out hint text inside the input
patternKey	string	Named preset: none, numbers_only, letters_only, alphanumeric, phone, postal_code, custom
pattern	string	Regex pattern (used when patternKey is "custom")
patternHint	string	Error message shown when the pattern is not matched

---

multiple_choice

Participant selects exactly one option. options is a non-empty array of strings.

{
  "order": 3,
  "text": "Which team are you joining?",
  "type": "multiple_choice",
  "options": ["Engineering", "Product", "Design"]
}

---

yes_no

Two-option toggle (Yes / No). No options needed.

{ "order": 4, "text": "Do you have prior experience?", "type": "yes_no" }

Branch rule condition values for yes_no: use "true" for Yes, "false" for No.

---

multi_select

Participant selects one or more options. options is a non-empty array of strings.

{
  "order": 5,
  "text": "Select all that apply",
  "type": "multi_select",
  "options": ["Option A", "Option B", "Option C"]
}

---

rating_scale

Participant picks a number within a defined range.

{
  "order": 6,
  "text": "Rate your experience",
  "type": "rating_scale",
  "options": { "min": 1, "max": 5, "minLabel": "Poor", "maxLabel": "Excellent" }
}

Option	Type	Required
min	number	Yes
max	number	Yes
minLabel	string	No
maxLabel	string	No

---

number

Free-form numeric input. No options needed.

{ "order": 7, "text": "How many years of experience do you have?", "type": "number" }

---

slider

Drag-style range selector.

{
  "order": 8,
  "text": "How confident do you feel?",
  "type": "slider",
  "options": { "min": 0, "max": 100, "step": 5 }
}

Option	Type	Required
min	number	Yes
max	number	Yes
step	number	No (defaults to 1)

---

date

Date picker input. No options needed.

{ "order": 9, "text": "When did you start?", "type": "date" }

---

time

Time picker input. No options needed.

{ "order": 10, "text": "What time is your team stand-up?", "type": "time" }

---

email

Text input with email format validation. No options needed.

{ "order": 11, "text": "Work email address", "type": "email" }

---

address

Five-field US postal address form with optional USPS verification.

{
  "order": 12,
  "text": "Mailing address",
  "type": "address",
  "options": {
    "showStreet2": true,
    "requireStreet2": false,
    "requireCity": true,
    "requireState": true,
    "requireZip": true,
    "verify": true
  }
}

All options are booleans and default to true except showStreet2 (defaults to false) and requireStreet2 (defaults to false). Set "verify": false to skip USPS validation.

---

signature

Typed electronic signature with a handwriting font picker and an automatic timestamp. No options needed.

{ "order": 13, "text": "Sign to confirm your responses", "type": "signature", "required": true, "isTerminal": true }

---

file_upload

File attachment input. No options needed.

{ "order": 14, "text": "Upload your CV", "type": "file_upload" }

---

location

Location input. No options needed.

{ "order": 15, "text": "Where are you based?", "type": "location" }

---

ranking

Drag-to-rank list. options is a non-empty array of strings.

{
  "order": 16,
  "text": "Rank these from most to least important",
  "type": "ranking",
  "options": ["Speed", "Reliability", "Price", "Support"]
}

---

Branch rules

Branch rules route participants to a different question when their answer matches a condition. They are attached to individual questions and evaluated in priority order.

{
  "order": 1,
  "text": "Are you a current customer?",
  "type": "yes_no",
  "branchRules": [
    {
      "conditionType": "equals",
      "conditionValue": "true",
      "targetOrder": 5,
      "priority": 0
    }
  ]
}

Field	Type	Required	Notes
conditionType	string	Yes	See table below
conditionValue	string	Yes	The value to compare against (always a string, even for numbers)
targetOrder	integer	Yes	The order of the question to jump to. Must be greater than the source question's order (forward jumps only)
priority	integer	No	Higher numbers are evaluated first. Defaults to 0

Condition types

Both the full name and the short alias are accepted.

Short alias	Full name	Applicable types
eq	equals	all
neq	not_equals	all
lt	less_than	numeric, date, time, slider, rating_scale
lte	less_than_or_equal	numeric, date, time, slider, rating_scale
gt	greater_than	numeric, date, time, slider, rating_scale
gte	greater_than_or_equal	numeric, date, time, slider, rating_scale
—	contains	text, short_text, multi_select
—	not_empty	text, short_text, address, signature
—	is_empty	text, short_text, address, signature

Condition values by type

Question type	Example conditionValue
yes_no	"true" or "false"
multiple_choice	"Engineering" (exact option label)
multi_select	"Option A" (contains this option)
rating_scale, number, slider	"4" (numeric, as a string)
date	"2025-01-01" (ISO 8601 date)
time	"09:00" (HH:MM)
text, short_text	Any string for equals/contains

---

SurveyJS format

If your JSON has a pages array, Mayetik treats it as SurveyJS format and converts it automatically before import. Question types are mapped as follows:

SurveyJS type	Mayetik type
text, comment, expression	text
radiogroup, dropdown	multiple_choice
checkbox	multi_select
rating	rating_scale
boolean	yes_no
anything else	skipped (a warning is shown)

SurveyJS visibleIf expressions are not imported. Branch rules must be added manually after import.

---

Error handling

If the file fails validation, the specific error is shown inline — no interview is created. Common errors:

Error	Fix
Invalid JSON	Check for trailing commas, mismatched brackets, or unquoted keys
order values must be unique	Each question must have a different order number
targetOrder X does not match any question order	A branch rule references an order that doesn't exist in the file
rating_scale requires options: { min, max }	Add the options object with min and max fields
An interview with this title already exists	Change the title or delete the existing interview

---

Known limitations (v1)

• Import always creates a new draft interview — it cannot update or merge with an existing one.
• The file_upload and location question types are created correctly but participant-facing UI for those types is not yet fully implemented.
• SurveyJS visibleIf expressions are not converted to branch rules.
• No image or media question types are supported.