4. File Specification: Instruction Schema (`instruction.jsonl`)

The instruction.jsonl file defines the sequence of screens (instructions, test trials, quizzes) that a participant sees before the main experiment begins. Each line contains one JSON object representing a "Module" object, which are presented in order.

4.1. Top-Level Structure

The file contains one "Module" object per line. Each Module object must have a type field, which determines the other required fields.

{ "type": "instruction", ... }
{ "type": "test_trial", ... }
{ "type": "comprehension_quiz", ... }

4.2. Module Type: `instruction`

This is the most common Module. It displays a page of text and/or images to the participant.

Key	Type	Description
`id`	String	A unique identifier for this module (e.g., "instruction_01").
`type`	String	Must be `"instruction"`.
`text`	String	The main body of text for the page. Can contain simple HTML tags like `<p>`, `<strong>`, `<ul>`, `<li>`.
`media_url`	Array of Strings	(Optional) An array of image/video paths to display, identical to the `media_url` in `trial.jsonl`.

4.3. Module Type: `test_trial`

This Module displays a fully functional trial (a stimulus and queries) from trial.jsonl. This allows participants to practice the task. Important: A test_trial should feature an identical looking trial that participants would encounter in the main experiment, allowing them to familiarize themselves with the interface and task format before proceeding.

Key	Type	Description
`id`	String	A unique identifier for this module (e.g., "test_trial_01").
`type`	String	Must be `"test_trial"`.
`feedback`	String	(Optional) A text block to show after the user clicks "Submit", e.g., "The correct answer for this practice trial is X."

4.4. Module Type: `comprehension_quiz`

This Module presents one or more questions (identical to the Query Object format) to check the participant's understanding. It provides immediate feedback. Important: Unlike test_trial, a comprehension_quiz focuses on high-level questions about the experiment itself (e.g., "What is your main task?", "How should you respond?"), rather than presenting actual experimental stimuli.

Key	Type	Description
`id`	String	A unique identifier for this module (e.g., "comprehension_quiz_01").
`type`	String	Must be `"comprehension_quiz"`.
`text`	String	(Optional) Introductory text to display above the questions.
`queries`	Array of Objects	An array of Query Objects (as defined in Section 3.2). These are the quiz questions. See note below.

Note on Quiz Queries: Queries within a comprehension_quiz (usually multi-choice) must include an answer field to provide real-time feedback to the user. The answer field is defined in the Trial Schema (Section 3.2).

4.5. Full `instruction.jsonl` Example

This example shows a sequence containing a welcome page, an instruction page with an image, a test trial, and a final comprehension quiz for a simple shape size detection task.

{
  "id": "instruction_01",
  "type": "instruction",
  "text": "Thank you for participating in this experiment.
Your task is to identify which shape is larger.
You will see two shapes side by side. Please carefully compare their sizes and select your answer."
}
{
  "id": "instruction_02",
  "type": "instruction",
  "text": "In each trial, you will see two shapes displayed side by side. Your task is to determine which shape has the larger area.",
  "media_url": [
    "https://placehold.co/600x400/e2e8f0/334155?text=Example+Shapes"
  ]
}
{
  "id": "test_trial_01",
  "type": "test_trial",
  "feedback": "In this practice example, the circle is larger than the square."
}
{
  "id": "comprehension_quiz_01",
  "type": "comprehension_quiz",
  "text": "Please answer the following questions to confirm your understanding.",
  "queries": [
    {
      "prompt": "What is your main task in this experiment?",
      "type": "multi-choice",
      "tag": "quiz_q1",
      "option": [
        "To count the number of shapes.",
        "To identify which shape is larger.",
        "To name the shapes."
      ],
      "answer": 1
    },
    {
      "prompt": "How many shapes will you see in each trial?",
      "type": "multi-choice",
      "tag": "quiz_q2",
      "option": [
        "One",
        "Two",
        "Three"
      ],
      "answer": 1
    }
  ]
}

4.6. Live Demo of Instruction Sequence

Below is a simulation of how the sequence from the example JSON above would be rendered to the participant, one Module at a time. Click the options in Module 4 to see the feedback.

Module 1 of 4: Instruction

Thank you for participating in this experiment.

Your task is to identify which shape is larger.

You will see two shapes side by side. Please carefully compare their sizes and select your answer.

Module 2 of 4: Instruction

In each trial, you will see two shapes displayed side by side. Your task is to determine which shape has the larger area.

Module 3 of 4: Practice Trial

Circle

Square

Which shape is larger?

Circle Square

Feedback: In this practice example, the circle is larger than the square.

Module 4 of 4: Comprehension Check

Please answer the following questions to confirm your understanding.

What is your main task in this experiment?

To count the number of shapes. To identify which shape is larger. To name the shapes.

How many shapes will you see in each trial?

One Two Three

4. File Specification: Instruction Schema (instruction.jsonl)

4.1. Top-Level Structure

4.2. Module Type: instruction

4.3. Module Type: test_trial