Event Reference

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 UUID assigned by TimeBack, formatted as urn:uuid:{yourAppId}. See note below.
session Use urn:tag:auto-attach for automatic session attribution

Note on edApp: The edApp field must be the UUID that TimeBack assigns to your app during registration. You'll receive this ID when you register (see Level 0: Registration). Do not use arbitrary identifiers—events with unrecognized edApp values will be rejected.

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"
}

Session Management

When your app manages its own login/logout flow, use SessionEvent to create and close sessions explicitly. For most apps, using session: "urn:tag:auto-attach" on regular events is sufficient—see Session Management for guidance on choosing the right approach.

LoggedIn

Send when a student starts a session in your app.

SessionEvent Schema

Key Requirements:

  • Use SessionEvent with LoggedIn action when the student begins a session
  • actor must be a Person
  • object must be a SoftwareApplication (your app)
  • session must include an id, type: "Session", and startedAtTime
  • session.extensions can optionally include feature flags (see below)

Key Attributes:

Field Description
actor Student's platform ID, formatted as urn:uuid:{platformId}
object Your app as a SoftwareApplication
edApp Your app's identifier, formatted as urn:uuid:{yourAppId}
session A Session with startedAtTime

Session Extensions

The extensions object on a session allows your app to opt in to additional platform features:

Extension Type Default Description
requiresHeartbeat boolean false Allows the use of the heartbeat endpoint for this session. If false, heartbeat calls for this session will be rejected.
processInsights boolean false Allows the platform to generate coaching insights for events in this session (e.g., idling detection, topic shopping, skip assessment). If false, insights processing is skipped for all events in this session.

SessionEvent.LoggedIn

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "SessionEvent",
  "profile": "SessionProfile",
  "actor": {
    "id": "urn:uuid:student-platform-id",
    "type": "Person"
  },
  "action": "LoggedIn",
  "object": {
    "id": "urn:uuid:your-app-id",
    "type": "SoftwareApplication"
  },
  "eventTime": "2025-01-15T09:00:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": {
    "id": "urn:uuid:session-unique-id",
    "type": "Session",
    "startedAtTime": "2025-01-15T09:00:00.000Z",
    "extensions": {
      "requiresHeartbeat": true,
      "processInsights": true
    }
  }
}

LoggedOut

Send when a student ends a session (explicit logout).

Key Requirements:

  • Use SessionEvent with LoggedOut action when the student logs out
  • actor must be a Person
  • object can be the SoftwareApplication IRI or full object
  • session must include the session id and endedAtTime

SessionEvent.LoggedOut

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "SessionEvent",
  "profile": "SessionProfile",
  "actor": {
    "id": "urn:uuid:student-platform-id",
    "type": "Person"
  },
  "action": "LoggedOut",
  "object": "urn:uuid:your-app-id",
  "eventTime": "2025-01-15T10:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": {
    "id": "urn:uuid:session-unique-id",
    "type": "Session",
    "endedAtTime": "2025-01-15T10:30:00.000Z"
  }
}

TimedOut

Send when a session ends due to inactivity timeout.

Key Requirements:

  • Use SessionEvent with TimedOut action for inactivity-based session close
  • actor should be a SoftwareApplication (the system that detected the timeout)
  • object must be a Session (the session being timed out)

SessionEvent.TimedOut

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "SessionEvent",
  "profile": "SessionProfile",
  "actor": {
    "id": "urn:uuid:your-app-id",
    "type": "SoftwareApplication"
  },
  "action": "TimedOut",
  "object": {
    "id": "urn:uuid:session-unique-id",
    "type": "Session",
    "endedAtTime": "2025-01-15T10:30:00.000Z"
  },
  "eventTime": "2025-01-15T10:30:00.000Z",
  "edApp": "urn:uuid:your-app-id"
}

Related Docs

Level 3: Caliper Events

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

Session Management

Understand session lifecycle, auto-attach vs explicit sessions, heartbeat, and session APIs.

Authentication

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