Event

Events describe something that happened at a specific point in time during an experiment. They are associated with timestamps and, where applicable, durations. Events can capture a wide range of occurrences, from a simple stimulus presentation or button press to complex interactions with virtual environments.

They may record changes in the agent (e.g., physiological responses), in the environment (e.g., stimulus presentation), or in the interactions between agents and the environment (e.g., a response to a stimulus). Events are typically the primary raw data of an experiment, so understanding and modeling them is crucial for interpreting experimental results.

Events schema

Events in BDM follow the xAPI specification — a standard for tracking and recording experiences — and extend it with a single canonical bdm: vocabulary (the verbs, object types, and actor types listed below) covering cognitive tests, questionnaires, and games. Just like xAPI, BDM assumes events are generated by a client app (the software that interacts with agents) and sent to an LRS (Learning Record Store; a data-collection server) for storage and analysis.

Each event is an object (in JSON or YAML) following the envelope below. For example, in YAML:

timestamp: 1996-12-19T16:39:57-08:00Z
actor:
  objectType: "bdm:Agent"
  id: "agent_001"
verb: "bdm:trial_ended"
object:
  objectType: "bdm:Trial"
  id: "trial_12"
result:
  extensions:
    bdm:response_id: 42
    bdm:response_time: 1.23
context:
  extensions:
    bdm:session_id: "0b1f…"
attachments: []

Timeseries

Timeseries represent streams of observations collected at fixed intervals — physiological signals, neural activity, or other continuous measurements. In BDM a timeseries is a specific type of event; the difference is in shape: timeseries are dense, continuous, and homogeneously typed (e.g., resting-state EEG at 500 Hz), whereas regular events are sparse, discrete, and heterogeneous.

Because raw timeseries data is dense and homogeneous, it is unsuitable for inline storage in event records. Instead, BDM treats the raw signal as a blob: the data is written to a separate, domain-appropriate file (CSV, Parquet, EDF, …) and only referenced from the event via the attachments field, alongside metadata describing the sampling rate and recording parameters.

attachments:
  - type: "bdm:Timeseries"
    contentType: "application/x-edf"
    url: "file:///eeg_timeseries_data.edf"

Schema version 26.0608 — full reference.

Event envelope

Field	Type	Requirement	Description
`actor`	object	required	Who or what performed/experienced the event — `{objectType, id, name?}`, where objectType is one of the actor types below. (Renamed from `agent`; an Agent is one type of actor — BDM deviation D5.)
`verb`	string	required	The action that occurred, drawn from the canonical verb vocabulary below.
`object`	object	required	What the action was performed on — `{objectType, id, name?}`, where objectType is one of the object types below.
`timestamp`	datetime (RFC 9557)	required	When the event occurred, as an ISO 8601 / RFC 9557 datetime with timezone offset.
`result`	object	optional	The outcome of the event (e.g. accuracy, response_time, score). Domain-specific payload lives under `result.extensions` keyed by `bdm:*` extension keys.
`context`	object	optional	Contextual information (study, studyflow, and the session→activity→runtime→block→trial scoping hierarchy) under `context.extensions`, keyed by `bdm:*` extension keys.
`version`	string	optional	The associated BDM/schema version (e.g. `v26.0608`). Typically populated by the LRS.
`stored`	datetime (RFC 9557)	optional	When the event was stored in the LRS. Populated by the LRS.
`updated`	datetime (RFC 9557)	optional	When the event was last updated in the LRS. Populated by the LRS.
`authority`	object	optional	The authority that generated the event (e.g. the client app/developer). Populated by the LRS.
`attachments`	array	optional	References to additional files/data associated with the event (stimulus blobs, recording files, timeseries), each with its own metadata. Payloads are not inlined.

Verbs

Verb	Layer	Object types	Description
`bdm:initialized`	lifecycle	`bdm:RuntimeInstance`	RuntimeInstance record minted; instrument loaded; engine ready. Nothing shown yet.
`bdm:started`	lifecycle	`bdm:RuntimeInstance`	First content actually shown to the participant; starts the experiential clock.
`bdm:paused`	lifecycle	`bdm:RuntimeInstance`	RuntimeInstance suspended (extended visibility loss, idle threshold, or explicit pause).
`bdm:resumed`	lifecycle	`bdm:RuntimeInstance`	RuntimeInstance continued after a pause. Carries bdm:pause_duration.
`bdm:completed`	lifecycle	`bdm:RuntimeInstance`	All required content done. Distinct from submitted.
`bdm:submitted`	lifecycle	`bdm:RuntimeInstance`	Data left the engine (POST to Orchestrator acknowledged).
`bdm:abandoned`	lifecycle	`bdm:RuntimeInstance`	RuntimeInstance ended without completion. Carries bdm:abandon_reason.
`bdm:presented`	presentation	`bdm:Screen`, `bdm:Panel`, `bdm:Stimulus`, `bdm:Option`, `bdm:Feedback`, `bdm:ConsentForm`	Something became perceivable (rendered or played). Typically the response-time anchor for Stimulus/Option.
`bdm:clicked`	interaction	`bdm:Option`, `bdm:UIComponent`	Pointer click (mouse, tap, stylus); the lowest-level click event.
`bdm:drag_and_dropped`	interaction	`bdm:Option`, `bdm:UIComponent`	A drag-and-drop gesture completed. Carries bdm:drag_source and bdm:drop_target.
`bdm:key_pressed`	interaction	`bdm:UIComponent`, `bdm:Stimulus`	A single key event. Carries bdm:key and bdm:key_code.
`bdm:typed`	interaction	`bdm:UIComponent`	A text input was committed (debounced). Carries bdm:typed_text and bdm:key_sequence.
`bdm:selected`	interaction	`bdm:Option`, `bdm:UIComponent`	Discrete option selected (radio, checkbox, dropdown).
`bdm:deselected`	interaction	`bdm:Option`, `bdm:UIComponent`	Discrete option deselected (e.g. checkbox unchecked).
`bdm:adjusted`	interaction	`bdm:UIComponent`	A continuous-value control was set (slider, spinner, dial). Carries bdm:current_value.
`bdm:got_focus`	interaction	`bdm:UIComponent`, `bdm:Window`	Focus gained by an input control or by the runtime window/tab.
`bdm:lost_focus`	interaction	`bdm:UIComponent`, `bdm:Window`	Focus lost. Window-level loss may (by threshold) lead to bdm:paused.
`bdm:consented`	interaction	`bdm:Consent`	The agent committed to consent. Carries bdm:consent_text_hash and bdm:consent_scope.
`bdm:trial_started`	system	`bdm:Trial`	A trial began. Carries bdm:trial_index and (when applicable) bdm:block_index / bdm:block_type.
`bdm:trial_ended`	system	`bdm:Trial`	Trial finalised; a Response (trial) row is created. Carries the canonical response_*, response_time, correct/score, and bdm:response_id. Exactly one per trial.
`bdm:state_changed`	system	`bdm:Timer`, `bdm:Scorer`, `bdm:LocaleSwitch`	A software-internal state change not tied to a presentation (timer, scorer, locale switch).
`bdm:recording_started`	recording	`bdm:Recording`	A continuous-data recording opened. Carries bdm:source and bdm:sample_rate.
`bdm:recording_ended`	recording	`bdm:Recording`	A recording closed and was stored. Carries bdm:recording_url, bdm:recording_sha256, bdm:duration.
`bdm:navigated`	navigation	`bdm:Screen`	Participant moved between Screens. Carries bdm:from_screen_id and bdm:to_screen_id.

Object types

Object type	Description
`bdm:RuntimeInstance`	One specific runtime execution of an Activity (distinguishes restarts).
`bdm:Screen`	One screen unit (questionnaire page, instructions screen, trial screen).
`bdm:Panel`	A within-screen layout grouping (e.g. matrix rows).
`bdm:Stimulus`	A displayed/audible thing the participant perceives within a trial.
`bdm:Option`	A response option shown to the participant (radio, checkbox, dropdown entry).
`bdm:Trial`	The participant-administered unit; one Response (trial) row per Trial.
`bdm:UIComponent`	An interactive UI control (radio, checkbox, slider, text field, button, key listener).
`bdm:Window`	The runtime window or browser tab (system-wide focus context).
`bdm:Feedback`	A post-response feedback display (correctness, score, band label, explanation).
`bdm:ConsentForm`	The consent form presented for review (what was shown).
`bdm:Consent`	The consent record — the audit entity capturing the agreement (what was committed to).
`bdm:Recording`	A continuous-data capture record (mouse, keyboard, EEG, …).
`bdm:Timer`	An internal software timer (trial timeout, idle detector).
`bdm:Scorer`	A Scorer entity invocation.
`bdm:LocaleSwitch`	A programmatic locale change.

Actor types

Actor type	Description
`bdm:Agent`	A specific agent — usually the human participant; may be an AI/automated participant.
`bdm:Group`	A collection of agents acting together (xAPI compatibility; rare).
`bdm:Engine`	The runtime software acting on its own (web viewer, Godot viewer, game engine, CLI runner).
`bdm:Orchestrator`	The backend service that schedules Activities, mints RuntimeInstances, manages submission.
`bdm:Researcher`	A researcher acting on the data (post-hoc annotation/correction).