Docs > Experiment JSON Reference

Each experiment can be described by a JSON file. This page details the format of the JSON file, including the datatypes and possible values.

  • Experiment

    The experiment object is at the top level of the JSON file.

    Properties

    canvas object An object describing the experiment layout with the following properties:
    size Size The size of the experiment canvas.
    stages array(Stage) The stages of the experiment.
    trials array(Trial) An array containing the experiment's trials.
    lists array(List) An array containing the experiment's lists.
    questionnaire object An object describing the experiment's questionnaire, using the following properties:
    questions array(Question) An array of Questions.
    intro string Optional text to be added to the experiment's intro screen.
    outro string Optional text to be added to the experiment's outro screen.

    Example

    This example contains several layers and other objects, plus into and outro text.

    {
    • "canvas": {},
    • "stages": [],
    • "trials": [],
    • "lists": [],
    • "intro": "Hello",
    • "outro": "Bye!"
    }

  • Hotspot

    The hotspot object describes a clickable area of an image asset.

    Properties

    name string Used to identify the hotspot.
    asset string The name of the asset on which the hotspot will be drawn.
    geometry Geometry Describes the shape of the hotspot.

    Example

    A hotspot with its geometry.

    {
    • "name": "fruit",
    • "layer": "image1",
    • "geometry": {
      • "position": {
        • "x": 10,
        • "y": 10
        },
      • "size": {
        • "width": 50,
        • "height": 50
        }
      }
    }

  • Geometry

    The geometry object describes a shape by a top-left coordinate system. Note that currently the assumed geometry type is rectangle, though others may be added in future.

    Properties

    position Position Describes the origin point of the shape.
    size Size Describes the size of the shape.

    Example

    {
    • "position": {
      • "x": 10,
      • "y": 10
      },
    • "size": {
      • "width": 50,
      • "height": 50
      }
    }

  • Stage

    The stage object describes a single stage of the experiment.

    Properties

    layers array(Layer) Describes where content will be presented within the stage.
    events array(Event) Describes the interactions between the participant and items in the stage.

    Example

    {
    • "layers": [],
    • "events": []
    }

  • Layer

    The layer object determines how an item from a Trial will be presented on the stage.

    Properties

    type string Denotes the type of asset that will be placed here, either image, audio or text.
    name string Used to refer to the layer with Trials.
    geometry Geometry|null For image layers, describes where the layer should appear on the stage.
    delay integer The number of milliseconds after the stage is shown that the layer should appear. The default is 0.

    Example

    Intro text that will appear immediately.

    {
    • "type": "text",
    • "name": "intro_text",
    • "geometry": {},
    • "delay": 0
    }

  • Event

    The event object describes interaction between stages or between the user and a stage.

    Properties

    layer string|null The layer on which the event can be triggered. If no layer is specified, the event will be triggered on the stage itself.
    hotspot string Optional; if the layer is an image layer, you can specify the hotspot on which the event must occur.
    type string Denotes the type of event to listen for. One of:
    • onstagestart - called when the stage starts.
    • onclick - called when the target is clicked.
    • onplaybackstart - called as soon as the target audio clip starts.
    • onplaybackend - called as soon as the target audio clip ends.
    action string Denotes what should happen when the event is detected on the layer. One of
    • stage.next - moves the trial on to the next stage.
    delay integer The number of milliseconds after the event is detected that the action should occur. The default is 0.

    Example

    1 second after the "intro_audio" audio clip finishes playing, move to the next stage.

    {
    • "type": "onplaybackend",
    • "layer": "intro_audio",
    • "action": "stage.next",
    • "delay": 1000
    }

  • Trial

    The trial object describes a single trial of the experiment.

    Properties

    name string A name for the trial.
    conditions array(Condition) Describes the different conditions the trial can have.

    Example

    {
    • "name": "food",
    • "conditions": []
    }

  • Condition

    The condition object describes a single condition of a trial.

    Properties

    name string A name for the condition.
    variables array(Variable) Describes which assets will be used for each layer.

    Example

    {
    • "name": "adult",
    • "variables": []
    }

  • Variable

    The variable object describes a variable within a condition.

    Properties

    layer string The name of the layer.
    value string The name of the asset to assign to the layer, or for text layers, the text to display within the layer.

    Example

    {
    • "layer": "image1",
    • "value": "kermit.jpg"
    }

  • List

    The list object describes an ordered list of trials and conditions.

    Properties

    name string The name of the list.
    trials array(string) Denotes the trial and condition to display, separated with a semi-colon. For example, "food:adult".

    Example

    {
    • "name": "1",
    • "trials": [
      • "food:adult",
      • "drink:kid",
      • "cars:filler"
      ]
    }

  • Question

    Describes a single question in a questionnaire.

    Properties

    text string The question text.
    answers array(Answer) An array of possible answers for the question.
    required boolean Optional; determines if the participant must provide an answer. Defaults to true.
    multiple boolean Optional; determines if the participant is allowed to select more than one answer. Defaults to false.

    Example

    {
    • "text": "Which languages do you speak fluently?",
    • "answers": [
      • {
        • "text": "English"
        },
      • {
        • "text": "Español"
        },
      • {
        • "text": "普通话"
        }
      ],
    • "multiple": true
    }

  • Answer

    Describes a single answer to a question.

    Properties

    text string The answer text.
    list string Optional; if the participant selects this answer, the list given here will be assigned to the participant.
    custom boolean Optional; determines if the participant is allowed to enter their own answer. Defaults to false.

    Example

    {
    • "text": "Blue",
    • "list": "1",
    • "custom": false
    }

  • Size

    The size object describes the size of a shape.

    Properties

    width integer The width of the rectangle.
    height integer The height of the rectangle.

    Example

    {
    • "width": 50,
    • "height": 50
    }

  • Position

    The position object describes the size of a shape.

    Properties

    x integer The shape's origin along the X axis.
    y integer The shape's origin along the Y axis.

    Example

    {
    • "x": 10,
    • "y": 10
    }