Caliper Events Reference

Complete event schemas, field requirements, and examples for all Caliper events supported by TimeBack Platform.

Overview

This document provides sample payloads for different types of Caliper events, along with clear guidance on when and how to use each event type.

Curriculum Content Interaction

Structured Curriculum Content

When students interact with structured curriculum content (lessons, units, courses, subjects, etc.), learning applications should fire AssignableEvent with Started and Completed actions.

AssignableEvent Schema

Key Requirements:

Use AssignableEvent with Started action when the student begins interaction
Use AssignableEvent with Completed action when the student completes the curriculum material
Started event's Attempt should include startedAtTime
Completed event's Attempt should include endedAtTime

Key Attributes:

Field	Description
actor	Student's platform ID (from LTI token's `sub`), formatted as `urn:uuid:{platformId}`
object	An AssignableDigitalResource with `mediaType: "curriculum/lesson"`
generated	The Attempt of the student on the lesson. `assignable` should match the lesson. Must include `startedAtTime`
edApp	Your app's identifier, formatted as `urn:uuid:{yourAppId}`
session	Use `urn:tag:auto-attach` for automatic session attribution

AssignableEvent.Started

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssignableEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Started",
  "object": {
    "id": "https://learningapp.com/lessons/fractions-intro",
    "type": "AssignableDigitalResource",
    "mediaType": "curriculum/lesson",
    "name": "Introduction to Fractions",
    "isPartOf": {
      "id": "https://learningapp.com/units/number-operations",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/unit",
      "name": "Basic Number Operations"
    }
  },
  "generated": {
    "id": "urn:uuid:lesson-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/lessons/fractions-intro",
    "startedAtTime": "2024-01-15T09:30:00.000Z"
  },
  "eventTime": "2024-01-15T09:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

AssignableEvent.Completed

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssignableEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Completed",
  "object": "https://learningapp.com/lessons/fractions-intro",
  "generated": {
    "id": "urn:uuid:lesson-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/lessons/fractions-intro",
    "startedAtTime": "2024-01-15T09:30:00.000Z",
    "endedAtTime": "2024-01-15T10:15:00.000Z"
  },
  "eventTime": "2024-01-15T10:15:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

Learning Resources

When students consume educational content such as textual materials (articles, documents, etc.) or videos, learning applications should fire ViewEvent with Viewed action.

ViewEvent Schema

Key Requirements:

Use ViewEvent with Viewed action when a student views learning resources
The event includes a generated Attempt with timing information

Key Attributes:

Field	Description
actor	Student's platform ID, formatted as `urn:uuid:{platformId}`
edApp	Your app's identifier, formatted as `urn:uuid:{yourAppId}`
session	Use `urn:tag:auto-attach` for automatic session attribution

ViewEvent.Viewed

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "ViewEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Viewed",
  "object": {
    "id": "https://learningapp.com/articles/algebra-introduction",
    "type": "DigitalResource",
    "name": "Introduction to Algebra",
    "mediaType": "text/html",
    "isPartOf": {
      "id": "https://learningapp.com/lessons/fractions-intro",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/lesson",
      "name": "Introduction to Fractions"
    }
  },
  "generated": {
    "id": "urn:uuid:resource-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/articles/algebra-introduction",
    "startedAtTime": "2024-01-15T11:00:00.000Z",
    "endedAtTime": "2024-01-15T11:15:00.000Z"
  },
  "eventTime": "2024-01-15T11:15:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

Assessment Interaction and Results

Assessments

When students start and submit assessments, learning applications should fire AssessmentEvent with Started and Submitted actions.

AssessmentEvent Schema

Key Requirements:

Use AssessmentEvent with Started action when student begins assessment
Use AssessmentEvent with Submitted action when student submits assessment
Started event's Attempt should include startedAtTime
Submitted event's Attempt should include endedAtTime

Key Attributes:

Field	Description
actor	Student's platform ID, formatted as `urn:uuid:{platformId}`
edApp	Your app's identifier, formatted as `urn:uuid:{yourAppId}`
session	Use `urn:tag:auto-attach` for automatic session attribution

AssessmentEvent.Started

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Started",
  "object": {
    "id": "https://learningapp.com/assessments/fractions-quiz",
    "type": "Assessment",
    "name": "Fractions Quiz",
    "isPartOf": {
      "id": "https://learningapp.com/lessons/fractions-intro",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/lesson",
      "name": "Introduction to Fractions"
    }
  },
  "generated": {
    "id": "urn:uuid:assessment-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/assessments/fractions-quiz",
    "startedAtTime": "2024-01-15T10:00:00.000Z"
  },
  "eventTime": "2024-01-15T10:00:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

AssessmentEvent.Submitted

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Submitted",
  "object": "https://learningapp.com/assessments/fractions-quiz",
  "generated": {
    "id": "urn:uuid:assessment-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/assessments/fractions-quiz",
    "startedAtTime": "2024-01-15T10:00:00.000Z",
    "endedAtTime": "2024-01-15T10:25:00.000Z"
  },
  "eventTime": "2024-01-15T10:25:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

Questions

When students interact with individual questions within assessments, learning applications should fire AssessmentItemEvent with Started and Completed actions.

AssessmentItemEvent Schema

Key Requirements:

Use AssessmentItemEvent with Started action when the question is shown
Use AssessmentItemEvent with Completed action when student answers question
Started event does not include generated field
Completed event includes Response with embedded Attempt containing timing information

Key Attributes:

Field	Description
actor	Student's platform ID, formatted as `urn:uuid:{platformId}`
edApp	Your app's identifier, formatted as `urn:uuid:{yourAppId}`
session	Use `urn:tag:auto-attach` for automatic session attribution

AssessmentItemEvent.Started

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentItemEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Started",
  "object": {
    "id": "https://learningapp.com/questions/fraction-addition-q1",
    "type": "AssessmentItem",
    "name": "Fraction Addition Question 1",
    "isPartOf": {
      "id": "https://learningapp.com/assessments/fractions-quiz",
      "type": "Assessment",
      "name": "Fractions Quiz"
    }
  },
  "eventTime": "2024-01-15T10:05:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

AssessmentItemEvent.Completed

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentItemEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Completed",
  "object": "https://learningapp.com/questions/fraction-addition-q1",
  "generated": {
    "id": "urn:uuid:response-id",
    "type": "Response",
    "attempt": {
      "id": "urn:uuid:question-attempt-id",
      "type": "Attempt",
      "assignee": "urn:uuid:student-platform-id",
      "assignable": "https://learningapp.com/questions/fraction-addition-q1",
      "startedAtTime": "2024-01-15T10:05:00.000Z",
      "endedAtTime": "2024-01-15T10:07:00.000Z"
    }
  },
  "eventTime": "2024-01-15T10:07:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

Grading

When the answered question is graded, learning applications should fire GradeEvent with Graded action.

GradeEvent Schema

Key Requirements:

Use GradeEvent with Graded action when question is graded
Event includes Score with scoreType extension linking to the Attempt

Key Attributes:

Field	Description
actor	Student's platform ID, formatted as `urn:uuid:{platformId}`
edApp	Your app's identifier, formatted as `urn:uuid:{yourAppId}`
generated	A Score object. `maxScore` should always be `1`. `scoreGiven` should be `0` for incorrect answer, `1` for correct. `scoreType` must be `QUESTION_RESULT`
session	Use `urn:tag:auto-attach` for automatic session attribution

GradeEvent.Graded

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "GradeEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Graded",
  "object": "urn:uuid:question-attempt-id",
  "generated": {
    "id": "urn:uuid:score-id",
    "type": "Score",
    "scoreType": "QUESTION_RESULT",
    "attempt": "urn:uuid:question-attempt-id",
    "maxScore": 1,
    "scoreGiven": 1
  },
  "eventTime": "2024-01-15T10:07:30.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

Performance Reporting

When learning applications need to report student progress such as curriculum mastery, they should fire GradeEvent with Graded action. These events use the Score entity with different scoreType values to differentiate between mastery achievements and XP awards.

Mastery

When students achieve mastery of curriculum standards or learning objectives, learning applications should fire GradeEvent with Graded action.

GradeEvent Schema

Key Requirements:

Use GradeEvent with Graded action when reporting curriculum mastery
Score entity must include scoreType: MASTERY

Key Attributes:

Field	Description
actor	Student's platform ID, formatted as `urn:uuid:{platformId}`
edApp	Your app's identifier, formatted as `urn:uuid:{yourAppId}`
generated	A Score object with `scoreType: "MASTERY"`
object	An Attempt object. Include `assignable` chain to indicate the curriculum mastered
session	Use `urn:tag:auto-attach` for automatic session attribution

GradeEvent.Graded (Mastery)

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "GradeEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Graded",
  "object": {
    "id": "urn:uuid:mastery-attempt-id",
    "type": "Attempt",
    "assignee": "https://learningapp.com/users/student-456",
    "assignable": {
      "id": "https://learningapp.com/standards/fractions-basics",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/standard",
      "name": "Basic Fractions Understanding",
      "isPartOf": {
        "id": "https://learningapp.com/clusters/number-operations",
        "type": "AssignableDigitalResource",
        "mediaType": "curriculum/cluster",
        "name": "Number Operations",
        "isPartOf": {
          "id": "https://learningapp.com/domains/numbers-operations",
          "type": "AssignableDigitalResource",
          "mediaType": "curriculum/domain",
          "name": "Numbers and Operations",
          "isPartOf": {
            "id": "https://learningapp.com/courses/mathematics-grade-4",
            "type": "AssignableDigitalResource",
            "mediaType": "curriculum/course",
            "name": "Mathematics Grade 4"
          }
        }
      }
    }
  },
  "generated": {
    "id": "urn:uuid:score-id",
    "type": "Score",
    "scoreType": "MASTERY",
    "attempt": "urn:uuid:mastery-attempt-id",
    "maxScore": 100,
    "scoreGiven": 100
  },
  "eventTime": "2024-01-15T14:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

XP

When students are awarded XP, learning applications should fire GradeEvent with Graded action to report the awarded XP.

GradeEvent Schema

Key Requirements:

Use GradeEvent with Graded action when reporting XP
Object should reference the XP's Attempt entity
XP can be optionally linked to a learning resource through the Attempt object's assignable field

Key Attributes:

Field	Description
actor	Student's platform ID, formatted as `urn:uuid:{platformId}`
edApp	Your app's identifier, formatted as `urn:uuid:{yourAppId}`
generated	A Score object with `scoreType: "XP"`
object	An Attempt object. Can optionally include `assignable` chain for the related resource
session	Use `urn:tag:auto-attach` for automatic session attribution

GradeEvent.Graded (XP)

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "GradeEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Graded",
  "object": {
    "id": "urn:uuid:xp-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": {
      "id": "https://learningapp.com/standards/fractions-basics",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/lesson",
      "name": "Introduction to Fractions"
    }
  },
  "generated": {
    "id": "urn:uuid:score-xp-id",
    "type": "Score",
    "scoreType": "XP",
    "attempt": "urn:uuid:xp-attempt-id",
    "scoreGiven": 150
  },
  "eventTime": "2024-01-15T14:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}

Related Docs

Level 2: Caliper Events

Quick start guide for implementing Caliper event integration with TimeBack Platform.

Authentication

Obtain OAuth client credentials and access tokens required for sending Caliper events.