Protocol configuration

Researchers specify how their Lookit study works by writing a “protocol configuration” for their study. This configuration is written in JSON, which stands for JavaScript Object Notation - this is just a special text format, not code.

Your study protocol configuration tells the Lookit experiment runner what sequence of “frames” to use in your study, and set all the options for those frames like what pictures or videos to show and for how long.

JSON format

No programming is required to design a study: JSON is a simple, human-readable text format for describing data. A JSON object is an unordered set of key – value pairs, with the following rules:

  • The object itself is enclosed in curly braces.

  • Keys are unique strings enclosed in double quotes.

  • A key and value are separated by a colon.

  • Key-value pairs are separated by commas.

A JSON value can be any of the following:

  • a string (enclosed in double quotes)

  • a number

  • a JSON object (as described above)

  • an array (an ordered list of JSON values, separated by commas and enclosed by square brackets)

  • true

  • false

  • null

There are no requirements for specific formatting of a JSON document (whitespace that isn’t part of a string is ignored). Here is an example JSON object to illustrate these principles:

{
    "name": "Jane",
    "age": 43,
    "favoritefoods": [
        "eggplant",
        "apple",
        "lima beans"
    ],
    "allergies": {
        "peanut": "mild",
        "shellfish": "severe"
    }
}

The keys are the strings name, age, favoritefoods, and allergies. Favorite foods are stored as an array, or ordered list; allergies are stored as a JSON object mapping food names to severity of reaction. The same object could also be written as follows, in a different order and with none of the formatting: `{"age": 43, "allergies": {"peanut": "mild", "shellfish": "severe"}, "name": "Jane", "favoritefoods": ["eggplant", "apple", lima beans"]}

A helpful resource to check your JSON Schema for simple errors like missing or extra commas, unmatched braces, etc. is jsonlint.

The JSON you write for your protocol configuration gets interpreted by Lookit’s experiment runner, which expects to find specific types of information in the configuration file. (Formally, it expects the data to conform to a custom JSON schema.)

Study protocol structure

Studies on Lookit are broken into a set of fundamental units called frames, which can also be thought of as “pages” of the study. A single experimental trial (e.g. looking time measurement) would generally be one frame, as are the video consent procedure and exit survey. Your JSON must have two keys: frames and sequence. The frames value defines the frames used in this study: it must be a JSON object mapping frame nicknames (any unique strings chosen by the researcher) to frame objects (defined next). The sequence value must be an ordered list of the frames to use in this study. Values in this list must be IDs from the “frames” value.

Frame IDs can’t have underscores in them

Frame IDs must be made of only numbers, letters, and dashes (e.g., “motor-skills-survey-23” is fine, but “motor_skills_survey” is not).

You will see an error in the browser console if you try to use a frame ID with an underscore in it!

Frame IDs also can’t end with -repeat-N (e.g., ‘-repeat-3’), because that suffix is used when the participant navigates back to repeat a frame.

Here is the JSON for a very minimal Lookit study:

{
    "frames": {
        "my-text-frame": {
            "blocks": [
                {
                    "title": "About the study",
                    "text": "This isn’t a real study."
                }
            ]
        },
        "my-exit-survey": {
            "kind": "exp-lookit-exit-survey",
            "debriefing": {
                 "title": "Thank you!",
                 "text": "You participated."
            }
        }
    },
    "sequence": [
        "my-text-frame",
        "my-exit-survey"
    ]
}

This JSON specifies a Lookit study with two frames, consent and an exit survey. Note that the frame nicknames my-text-frame and my-exit-survey that are defined in frames are also used in the sequence. Frames may be specified but not used in sequence. Here’s the object associated with the my-exit-survey frame:

{
    "kind": "exp-lookit-exit-survey",
    "debriefing": {
        "title": "Thank you!",
        "text": "You participated."
    }
}

Within each frame object, a kind must be specified. This determines the frame type that will be used. Additional data may be included in the frame object to customize the behavior of the frame, for instance to specify instruction text or the stimuli to use for a test trial. The keys that may (or must) be included in a frame object are determined by the frame type; each frame definition includes a JSON Schema describing the expected data to be passed. Multiple frames of the same kind may be included in a study – for instance, test trials using different stimuli.

The separation of frame definitions and sequence allows researchers to easily and flexibly edit and test study protocols – for instance, the order of frames may be altered or a particular frame removed for testing purposes without altering any frame definitions.