The xAPI profile for learning events

Commands here say viable-harness. Until it is on npm, use npx github:VIABLE-Learning-Lab/viable in its place: it takes every command.

Schools' learning record stores (LRSs) read xAPI. toStatements(record, { homePage, activityBase, includeText }) in src/xapi.js, and viable-harness xapi, turn one learner's record (schemas/learning-events.schema.json: its events and turns) into xAPI 1.0.3 statements. The harness builds the statements and sends nothing: a deployer posts them to their LRS.

viable-harness xapi record.json --home-page https://school.example.org [--activity-base <url>] [--include-text]

import { toStatements } from '@viable-lab/engine/harness/xapi.js'; // npm i github:VIABLE-Learning-Lab/viable
const statements = toStatements(record, { homePage: 'https://school.example.org' });

conformance/xapi.json holds the cases another implementation of this profile checks itself against. schemas/xapi-profile.jsonld is the same profile as an xAPI Profile (xAPI Profiles 1.0, JSON-LD): VIABLE's own verbs, activity types and extensions, each with its definition, written from VOCABULARY in src/xapi.js by npm run xapi:build. The VIABLE Developer Platform publishes it at https://developers.viablelab.org/xapi, the profile's IRI, and answers every IRI under it (each verb, activity type and extension, such as …/verbs/requested-hint) with the profile as JSON-LD. The record's schema is published there too, at its $id, https://developers.viablelab.org/schemas/learning-events.schema.json.

A statement

Activities

Activity IRIs are built from the ids the record carries, each part percent-encoded. With act = <activityBase>/<activity> (or activityBase alone when the record names no activity):

… is https://developers.viablelab.org/xapi. An object whose id is missing (a draft event without a field, a page event without a page) is the one it belongs to: the panel, or for a criterion the rubric.

Verbs

Verbs without "(ADL)" are VIABLE's, under https://developers.viablelab.org/xapi/verbs/ (…/verbs/requested-hint).

Skipped, with no statement:

• page.layout: how the page is arranged (the AI panel's width, collapsed or open), not something the learner did in the activity.
• embed.state: an embedded page's saved state, for picking up where the learner left off. xAPI keeps that in its State resource, not in statements.

An event of a type the schema doesn't list makes no statement either. Two identical events make one statement, since an LRS refuses a batch that repeats an id.

A score is sent as { raw, min: 0, max, scaled } when max_score is above 0 and the score is between 0 and it, and as { raw } alone otherwise: xAPI requires raw between min and max.

Extensions

Every extension is named after the field it comes from, under https://developers.viablelab.org/xapi/extensions/ (…/extensions/visible_ms).

• Result: an event's data, except what the statement carries elsewhere (verb, object, field, correct, success, completion, score, max_score, duration_ms, response): its numbers and true/false, strings that name something (set, skill, item_type, color, content_type, asset_id, source), and nested objects the same way. For a turn, first_output_ms, signals and after; for an answer its agent graded, skill.
• Context: the record's session, and from the event or turn, when it has them: seq, conversation_id, turn_index, agent_version, activity_version, vetting and vetting_attempts. vetting is the review's outcome: passed, unverified (it ran out of tries) or attention (a safety concern); VIABLE flags unverified and attention turns for the teacher. These turn fields are read by the names the research export's turns.csv gives them; the learning-events schema allows them on a turn without listing them yet.

What is never sent

• A name, an email address or any identifier of the learner but the record's user. A user that looks like an email address is refused, and so is a record without one.
• Without includeText (the default): what the learner wrote (a snapshot's text, an answer's response, an embedded page's response), a question's prompt, a turn's message and the AI's reply, and any other string in data, such as an app's own fields: the harness can't tell a label from something a learner typed.
• Lists inside data.
• The skipped event types above.

What includeText adds

A deployer opts in, for an LRS that may hold learners' writing. With includeText: true (--include-text), an answer's or embedded page's response becomes the result's response, and every other string, a snapshot's text, a question's prompt, a turn's message and reply and an app's own strings, becomes a result extension named after its field. Ids don't change.

Sending statements to an LRS

The deployer posts the statements; the harness makes no network call.

viable-harness xapi record.json --home-page https://school.example.org > statements.json
curl -X POST "$LRS_ENDPOINT/statements" \
  -H 'X-Experience-API-Version: 1.0.3' -H 'Content-Type: application/json' \
  -u "$LRS_KEY:$LRS_SECRET" --data @statements.json

• homePage names the system whose ids the learners' user values are: keep it the same across exports (https://school.example.org and https://school.example.org/ are different accounts).
• Exporting a record again gives the same ids, and an LRS doesn't store a statement it already has, so re-sending doesn't duplicate. A statement whose content changed under the same id (after switching includeText, or changing activityBase) is refused, often with 409 Conflict: xAPI statements can't be changed, only voided.
• LRSs limit how many statements one request may carry; split a large export into batches.
• What the LRS keeps, for how long and who can read it is the deployer's to agree with the school.

This page comes from the open repository: harness/docs/xapi.md. To change it, change it there.