Back/Normalized Interview Format

Normalized Interview Format

What Is This? When you export an interview from ThirdEar using the Export Interview dialog and select JSON , you get a file in the NormalizedInterview ...

What Is This?

When you export an interview from ThirdEar using the Export Interview dialog and select JSON, you get a file in the NormalizedInterview v2.0 format. This is ThirsEar's native data format — it's how every interview is stored internally in the database.

Think of it as the "master copy" of an interview. Every other representation — what you see in the editor UI, what runs during a live Pipecat session, or what gets exported to Qualtrics — is generated from this single format on the fly. This means the NormalizedInterview is always the source of truth.

The Big Picture

Знімок екрана 2026-03-18 о 17.33.03.png

All of these are generated from the NormalizedInterview. None of them are stored separately. If someone edits an interview in the UI, the changes are converted back into this format before saving.

Format Overview

A NormalizedInterview JSON file has three top-level fields:

{
  "version": "2.0",
  "questions": [ ... ],
  "metadata": { ... }
}

Field

When exported via the UI, there's also a small _export block with tracking info (interview ID, name, export timestamp). This is not part of the core format — it's just for bookkeeping.

Questions

Each question in the questions array looks like this:

{
  "id": "QID1",
  "type": "multiple_choice_single",
  "text": "What is your age range?",
  "choices": [
    { "id": "1", "display": "18-24", "order": 0 },
    { "id": "2", "display": "25-34", "order": 1 },
    { "id": "3", "display": "35-44", "order": 2 }
  ],
  "required": true,
  "order": 0,
  "sectionId": "SID1",
  "next": "__continue__"
}

Question Fields

Question Types

Choices (for Multiple Choice Questions)

Each choice in the choices array:

Scale (for Likert and Rating Questions)

{
  "scale": {
    "min": 1,
    "max": 5,
    "minLabel": "Strongly Disagree",
    "maxLabel": "Strongly Agree"
  }
}

Validation (for Voice/Text Input Questions)

{
  "validation": {
    "minLength": 10,
    "maxLength": 500,
    "pattern": "^[A-Za-z]+"
  }
}

Metadata

The metadata object contains interview-level settings:

{
  "metadata": {
    "name": "Generation Z Research Study",
    "description": "A study exploring Gen Z attitudes toward...",
    "preamble": "You are a friendly research interviewer conducting...",
    "language": "en",
    "customStartMessage": "Hello! This is an interview for Generation Z. Are you ready to begin?",
    "customEndMessage": "Thank you for participating!",
    "sections": [
      { "id": "SID1", "name": "Demographics", "order": 0 },
      { "id": "SID2", "name": "Media Consumption", "order": 1 }
    ],
    "voiceId": "a0e99841-438c-4a64-b679-ae501e7d6091",
    "vadParams": { "stop_secs": 0.5 },
    "maxSessionDuration": 1800,
    "conversationSpeed": "normal"
  }
}

Sections

Sections are optional groupings that organize questions into logical blocks (e.g. "Demographics", "Product Feedback", "Closing"). Each section has:

Flow Control

By default, the interview moves through questions sequentially — question 1, then 2, then 3, and so on. This is the "__continue__" behavior.

But you can create more complex flows:

The `next` Field (on Questions)

Every question has an optional next field that controls where to go after it's answered:

The `transitionTo` Field (on Choices)

For multiple choice questions, individual choices can override the question's next field. This enables conditional branching — e.g., "If they answer 'Yes', go to the follow-up section; if 'No', skip ahead."

{
  "id": "QID5",
  "type": "multiple_choice_single",
  "text": "Have you used our product before?",
  "choices": [
    { "id": "1", "display": "Yes", "order": 0, "transitionTo": "SID3" },
    { "id": "2", "display": "No", "order": 1, "transitionTo": "SID4" }
  ],
  "required": true,
  "order": 4,
  "next": "__continue__"
}

In this example, even though the question's default next is "__continue__", if the participant chooses "Yes", the interview jumps to section SID3. If they choose "No", it jumps to SID4.

Priority: Choice transitionTo > Question next > Default (__continue__)

Full Example

Here's a minimal but complete NormalizedInterview:

{
  "version": "2.0",
  "questions": [
    {
      "id": "QID1",
      "type": "voice_input_single",
      "text": "What is your name?",
      "required": true,
      "order": 0,
      "sectionId": "SID1",
      "next": "__continue__"
    },
    {
      "id": "QID2",
      "type": "multiple_choice_single",
      "text": "What is your age range?",
      "choices": [
        { "id": "1", "display": "18-24", "order": 0 },
        { "id": "2", "display": "25-34", "order": 1 },
        { "id": "3", "display": "35-44", "order": 2 },
        { "id": "4", "display": "45+", "order": 3 }
      ],
      "required": true,
      "order": 1,
      "sectionId": "SID1",
      "next": "__continue__"
    },
    {
      "id": "QID3",
      "type": "voice_input_multiline",
      "text": "Tell us about your experience with our product.",
      "validation": {
        "minLength": 20
      },
      "required": true,
      "order": 2,
      "sectionId": "SID2",
      "next": "__continue__"
    },
    {
      "id": "QID4",
      "type": "likert_scale",
      "text": "How satisfied are you overall?",
      "scale": {
        "min": 1,
        "max": 5,
        "minLabel": "Very Unsatisfied",
        "maxLabel": "Very Satisfied"
      },
      "required": true,
      "order": 3,
      "sectionId": "SID2",
      "next": "__end__"
    }
  ],
  "metadata": {
    "name": "Product Feedback Interview",
    "preamble": "You are a friendly researcher. Ask each question conversationally and listen carefully to responses.",
    "language": "en",
    "customStartMessage": "Hi there! Thanks for joining us today. Ready to get started?",
    "customEndMessage": "That wraps up our interview. Thank you so much for your time!",
    "sections": [
      { "id": "SID1", "name": "Demographics", "order": 0 },
      { "id": "SID2", "name": "Product Feedback", "order": 1 }
    ]
  }
}

Importing This Format

A NormalizedInterview JSON file can be imported back into ThirdEar. The system auto-detects the format by checking for version: "2.0" and a questions array. No special steps needed — just upload the JSON file through the import flow. JSON file can be imported back into ThirdEar. The system auto-detects the format by checking for version: "2.0" and a questions array. No special steps needed — just upload the JSON file through the import flow.

The system also supports importing from other formats (Qualtrics QSF, SurveyJS, Google Forms), which are automatically converted to NormalizedInterview on import.

Source Code Reference

For developers who want to dig into the implementation:

`version`	Always `"2.0"`. Identifies this as the current format.
`questions`	The list of all questions in the interview, in order.
`metadata`	Settings for the interview — the system prompt, language, voice configuration, etc.

`id`	Yes	Unique identifier, e.g. `"QID1"`, `"QID2"`. These follow a sequential naming pattern.
`type`	Yes	The kind of question (see table below).
`text`	Yes	The question text shown/spoken to the participant.
`choices`	Only for multiple choice	The answer options the participant can pick from.
`validation`	Only for text/voice input	Rules like min/max length for open-ended responses.
`scale`	Only for Likert/rating	Defines the numeric range (e.g. 1-5) and optional labels.
`required`	Yes	Whether the participant must answer this question.
`order`	Yes	Position in the interview (0-based). Controls the sequence.
`sectionId`	No	Which section this question belongs to, e.g. `"SID1"`. If omitted, the question isn't grouped into a section.
`next`	No	Where to go after this question. Defaults to `"__continue__"` (just go to the next question in order).

`multiple_choice_single`	Pick exactly one option from a list (like a radio button).
`multiple_choice_multiple`	Pick one or more options from a list (like checkboxes).
`voice_input_single`	Short spoken/typed response (a single line of text).
`voice_input_multiline`	Longer spoken/typed response (paragraph-length).
`likert_scale`	Agreement scale, e.g. "Strongly Disagree" to "Strongly Agree". Uses the `scale` field.
`rating_scale`	Numeric rating, e.g. 1-10. Uses the `scale` field.

`id`	Yes	Unique identifier within the question, e.g. `"1"`, `"2"`.
`display`	Yes	The text shown to the participant.
`value`	No	An optional internal value for data analysis. If omitted, the `display` text is used as the value.
`order`	Yes	Display order (0-based).
`transitionTo`	No	Conditional branching — if the participant picks this choice, jump somewhere specific instead of following the default `next`. See "Flow Control" below.

`min`	Yes	Lowest value on the scale.
`max`	Yes	Highest value on the scale.
`minLabel`	No	Label for the low end (e.g. "Not at all likely").
`maxLabel`	No	Label for the high end (e.g. "Extremely likely").

`minLength`	No	Minimum character count for the response.
`maxLength`	No	Maximum character count for the response.
`pattern`	No	A regex pattern the response must match.

`preamble`	Yes	The system prompt — instructions that tell the AI interviewer how to behave, what tone to use, and how to conduct the interview. This is the most important field.
`language`	Yes	Language code, e.g. `"en"` for English.
`name`	No	Human-readable name for the interview.
`description`	No	Description of the interview's purpose.
`customStartMessage`	No	A specific greeting message to use when the interview begins. If omitted, the AI generates one based on the preamble.
`customEndMessage`	No	A specific closing message when the interview ends.
`sections`	No	Defines named groups for organizing questions (see "Sections" below).
`voiceId`	No	A Cartesia voice ID that controls which AI voice is used for text-to-speech during live interviews.
`vadParams`	No	Voice Activity Detection settings. `stop_secs` controls how many seconds of silence the system waits before deciding the participant is done speaking. Default is 0.5 seconds.
`maxSessionDuration`	No	Maximum interview length in seconds. After this time, the interview ends automatically. For example, `1800` = 30 minutes.
`conversationSpeed`	No	Pacing of the conversation: `"slow"`, `"normal"`, or `"fast"`.

`id`	Unique identifier, e.g. `"SID1"`. Questions reference this via their `sectionId` field.
`name`	Human-readable name, e.g. `"Demographics"`.
`order`	Display/execution order (0-based).

`"__continue__"`	Go to the next question in order. This is the default if `next` is omitted.
`"SID2"` (a section ID)	Jump to the first question of that section.
`"__end__"`	End the interview immediately after this question.

lib/interview-converter/types.ts	TypeScript type definitions — the authoritative schema.
lib/interview-converter/InterviewConverter.ts	The main converter class with all conversion methods.
lib/interview-converter/converters/from-editor.ts	Converts the editor UI format into NormalizedInterview.
lib/interview-converter/converters/to-editor.ts	Converts NormalizedInterview back to the editor UI format.
lib/interview-converter/converters/to-rtvi.ts	ConvertsNormalizedInterview to the Pipecat runtime flow for live interviews.
lib/interview-converter/exporters/toQsf.ts	Converts NormalizedInterview to Qualtrics QSF format.
lib/interview-converter/adapters/	Format adapters for importing from external formats (QSF, SurveyJS, Google Forms).