2. EML → Rendering

EML (Experiment Markup Language) is the static contract consumed by CogGym. It specifies exactly which instructions and trials exist, how they are sequenced, what the participant sees, what responses are collected, and what optional feedback follows a trial.

2.1. Rendering Pipeline

The renderer depends only on the materialized EML package, regardless of how that package was authored.

1. Select a sequence. The renderer reads config.json and selects an explicit seq_id from experimentFlow.
2. Resolve each component. Instruction IDs are loaded from instruction.jsonl; trial IDs are loaded from trial.jsonl.
3. Render the interaction. The renderer presents instructions or trial stimuli, creates the specified query controls, and validates required responses.
4. Complete the trial. After submission, the renderer may present the trial's feedback behavior and then advances through the explicit sequence.
5. Record lineage. Responses retain the concrete trial ID, query tag, and selected sequence ID.

2.2. The EML Package

The detailed runtime schemas are organized by responsibility:

• Config Schema — experiment metadata and explicit flow.
• Trial Schema — concrete stimuli, queries, static feedback, and trial IDs.
• Instruction Schema — instruction pages, demonstrations, and checks.
• Human Data Schema — collected responses and related reference datasets.

2.3. Directory Structure

Each dataset is contained in one root directory. A study may have multiple experiments, each in its own exp1, exp2, or subsequent subdirectory. Even a single-experiment study uses an exp1 subdirectory. The study and each experiment include a narrative README.md.

[DatasetName]/
├── README.md
├── exp1/
│   ├── README.md
│   ├── config.json
│   ├── trial.jsonl
│   ├── instruction.jsonl
│   ├── human_data_ind.json
│   ├── human_data_mean.json
│   ├── build_provenance.json      # generated packages only
│   └── assets/                    # when non-text stimuli are used
│       ├── stimulus_image_01.png
│       ├── stimulus_video_01.mp4
│       └── ...
└── exp2/                          # optional additional experiment
    ├── README.md
    ├── config.json
    ├── trial.jsonl
    └── ...

2.4. Naming Convention

The root folder name follows [AuthorLastName][Year][FirstNonArticleWordOfTitle]:

• AuthorLastName: last name of the first author.
• Year: four-digit publication year.
• FirstNonArticleWordOfTitle: first title word that is not “A,” “An,” or “The.”

For “A Minimal Theory of Mind for Social Agents” (Rabinowitz et al., 2018), the root directory is Rabinowitz2018Minimal/, containing at least exp1/.

2.5. File Inventory

Renderer inputs

• config.json — required metadata and explicit experiment flow.
• trial.jsonl — required concrete trial definitions.
• instruction.jsonl — required instruction and quiz definitions.
• assets/ — required when trials or instructions reference non-text media such as images, audio, or video.

Documentation and build records

• README.md — required experiment summary and usage notes.
• build_provenance.json — produced by the v1.5 reference builder; records source hashes, generator version, primitive model-card identities, and generated trial and sequence IDs.

Data and reference files

• human_data_ind.json and human_data_mean.json — anonymized individual and aggregated human responses.
• ground_truth_mean.json and ground_truth_ind.json — optional objective answers, using the human-data key structure.
• human_data_mean_replication.json and human_data_ind_replication.json — optional replication responses.
• symbolic_representation/ — optional structured world-state associated with trials or conditions.

2.6. Field-level Schema Pages

Use the following pages for field-level definitions and examples: