1.2 Terminology

Actor: An actor is an Agent capable of initiating or performing an action on a thing or as part of a process. A Caliper Event includes an actor attribute for representing the Agent.

Anonymous, Anonymization: Applying a process to transform the properties of an Entity to obscure its identity such that the process cannot be reversed nor can the Entity be afterwards distinguished from other such-treated entities.

Blank Node Identifier: a string that begins with "_:" that is used to identify an Entity for which an IRI is not provided. An Entity provisioned with a blank node identifier is neither dereferenceable nor has meaning outside the scope of the JSON-LD document within which it resides.

Action: something performed or done to accomplish a purpose. Caliper Event subtypes define a controlled vocabulary of one or more actions relevant to the activity domain. A Caliper Event includes an action attribute for expressing the associated action.

Context: a special JSON-LD keyword that maps the terms employed in a JSON document to IRIs that link to one or more published vocabularies. Inclusion of a JSON-LD context provides an economical way of communicating document semantics to services interested in consuming Caliper event data.

Depersonalize, Depersonalized: applying a process to transform the properties of an Entity in order to obscure its identity such that the process might be reversed thus preserving the ability to afterwards distinguish from other such-treated entities.

Describe: a Caliper message containing an Entity that is not directly associated with an Event. Entities can be sent asynchronously using Describe messages in order to reduce verbosity (e.g. sending a Person entity as a Describe avoids having to repeat the Person object in each Event that includes it).

Endpoint: a receiver or consumer of Caliper data that is bound to a specific network protocol.

Entity: an object or a thing that participates in learning-related activity. Caliper Entity types provide coarsed-grained representations of applications, people, groups and resources that constitute the "stuff" of a Caliper Event. Each Entity corresponds to a node in a directed graph.

Envelope: a data structure that serves as a transport container of Caliper Event and Entity data. The envelope also includes metadata about the emitting Sensor and the data payload.

Event: describes a relationship established between an Agent (the actor) and an Entity (the object) formed as a result of a purposeful action undertaken by the actor in connection to the object at a particular moment in time.

JSON-LD: a specification providing a JSON-based data serialization and messaging format, processing algorithms and API for working with Linked Data. The messages described in this specification are intended to be used in programming environments that support [JSON-LD]

IRI: The Internationalized Resource Identifier (IRI) extends the Uniform Resource Identifier (URI) scheme by using characters drawn from the Universal character set rather than US-ASCII per [RFC3987]. Linked Data rely on IRIs to refer to most nodes and properties.

ISO 8601: Caliper data and time values are formatted per ISO 8601 with the addition of millisecond precision. The format is yyyy-MM-ddTHH:mm:ss.SSSZ where 'T' separates the date from the time while 'Z' indicates that the time is set to UTC.

Linked Data: A set of design principles first articulated by Tim Berners-Lee for discovering, connecting, and sharing structured data over the Web. The principles can be summarized as follows: use IRIs /URIs as names for things; use HTTP IRIs /URIs so that information about things (e.g., people, objects, concepts) can be retrieved using a standard format; link out to other relevant things by way of their IRIs/URIs in order to promote discovery of new relationships between things.

LIS: Learning Information Services® (LIS®) [LIS-20] is an 1EdTech standard that defines how systems manage the exchange of information that describes people, groups, memberships, courses and outcomes.

LTI: Learning Tools Interoperability® (LTI®) [LTI-13] is an 1EdTech standard for integration of rich learning applications within educational environments.

Profile: models a learning activity or a supporting activity that helps facilitate learning. Each profile provides a domain-specific set of terms and concepts that application designers and developers can draw upon to describe common user interactions in a consistent manner using a shared vocabulary.

Object: an Entity that an Agent interacts with that becomes the focus, target or object of an interaction. A Caliper Event includes an object attribute for representing the resource.

Profile: a segment of the information model that describes a learning activity or a supporting activity that helps facilitate learning. A Caliper profile comprises related Caliper events, entities and actions that together describe the activity. A Caliper profile also serves as a unit of certification.

Sensor: Software assets deployed within a learning application that implement the Sensor API™ for marshalling and transmitting Caliper data to a target endpoint.

Sensor API™: The standard set of methods and supported parameters that a Sensor implements according to this specification in order to transmit Caliper data in an interoperable way.

Term: a word or short expression that expands to an IRI when mapped to a JSON-LD context document. Terms are employed by Caliper as type property string values in order to distinguish between various JSON representations of entities and events defined by the Caliper information model.

Type Coercion: the process of coercing values to a particular data type.

URI: the Uniform Resource Identifier (URI) utilizes the US-ASCII character set to identify a resource. Per [RFC2396] a URI "can be further classified as a locator, a name or both." Both the Uniform Resource Locator (URL) and the Uniform Resource Name (URN) are considered subspaces of the more general URI space.

URL: A Uniform Resource Locator (URL) is a type of URI that provides a reference to resource that specifies both its location and a means of retrieving a representation of it. An HTTP URI is a URL and using HTTP IRIs /URIs to identify things is fundamental to Linked Data.

URN: A Uniform Resource Name (URN) is a type of URI that provides a persistent identifier for a resource that is bound to a defined namespace. Unlike a URL a URN is location-independent and provides no means of accessing a representation of the named resource.

UUID: a 128-bit identifier that does not require a registration authority to assure uniqueness. However, absolute uniqueness is not guaranteed although the collision probability is considered extremely low. Caliper recommends use of randomly or pseudo-randomly generated version 4 UUIDs. Each Caliper Event MUST be assigned a UUID that is expressed as a URN using the form "urn:uuid:<UUID>" as described in [RFC4122].

1.3 Conformance Statements

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MAY", "MUST", "MUST NOT", "OPTIONAL", "RECOMMENDED", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", and "SHOULD NOT" in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

The Conformance and Certification Guide for this specification may introduce greater normative constraints than those defined here for specific service or implementation categories.

1.4 Document Set

2.1 Event

For a complete list of Events, see Appendix A

A Caliper Event is a generic type that describes the relationship established between an actor and an object, formed as a result of a purposeful action undertaken by the actor at a particular moment in time and within a given learning context. The Event properties actor, action and object form a compact data structure that resembles an RDF Triple linking a subject to an object via a predicate. A learner starting an assessment, annotating a reading, pausing a video, or posting a message to a forum, are examples of learning activities that Caliper models as events.

Caliper defines a number of Event subtypes, each scoped to a particular activity domain and distinguishable by a type attribute. The type value is a string that MUST match the Term specified for the Event by the Caliper information model (e.g. "MessageEvent"). Each Event instance is assigned a 128-bit long universally unique identifier (UUID) formatted as a URN per [RFC4122], which describes a URN namespace for UUIDs.

The information model also seeks to describe the learning environment or context in which a learning activity is situated. Group affiliation, membership roles and status, recent navigation history, supporting technology and session information can all be optionally represented. An Entity generated as a result of the interaction between an action and an object can also be described; annotating a piece of digital content and producing an Annotation is one such example. An extensions property is also provided so that implementers can add custom attributes not described by the model.

IRI

https://purl.imsglobal.org/caliper/Event

Term

Event

Subtypes

AnnotationEvent, AssignableEvent, AssessmentEvent, AssessmentItemEvent, FeedbackEvent, ForumEvent, GradeEvent, MediaEvent, MessageEvent, NavigationEvent, QuestionnaireEvent, QuestionnaireItemEvent, ResourceManagementEvent, SearchEvent, SessionEvent, SurveyEvent, SurveyInvitationEvent, ThreadEvent, ToolLaunchEvent, ToolUseEvent, ViewEvent

Properties

The base set of Event properties or attributes is listed below. Considered as a data structure an Event constitutes an unordered set of key:value pairs that is semi-structured by design. Optional attributes can be ignored when describing an Event. An Entity participating in an Event can be represented as an object or as a string that corresponds to the IRI defined for the Entity. Each property MUST be referenced only once. The id, type, action, action, object and eventTime properties are required; all other properties are optional. Custom attributes not described by the model MAY be included but MUST be added to the extensions property as a map of key:value pairs. Properties with a value of null or empty SHOULD be excluded prior to serialization.

Although each Event's profile property is considered optional (in order to ensure backwards compatibility) Sensors SHOULD specify for each Event created the relevant profile string value in order to inform consumers which profile governs the construction and interpretation of the Event. The profile terms are listed in the Profile Terms section.

2.2 Entity

A Caliper Entity is a generic type that represents objects that participate in learning-related activities. A variety of Entity subtypes have been defined in order to better describe people, groups, organizations, digital content, courses, software applications, and other objects that constitute the "stuff" of a Caliper Event. Each Entity is provisioned with a modest set of properties or attributes that support description and discovery.

Caliper permits Entity values to be expressed either as an object or as a string corresponding to the resource's IRI. If the Entity is expressed as an object, both the id and type properties MUST be specified. The type value is a string that MUST match the term specified for the Entity by the Caliper information model (e.g. "Person"). The id value is a string that MUST be expressed as an IRI. The IRI MUST be valid and unique. The IRI SHOULD also be dereferenceable, i.e., capable of returning a representation of the resource assuming authorization to access the resource is granted. A URI employing the URN scheme MAY be provided although care should be taken when employing a location-independent identifier since it precludes the possibility of utilizing it to retrieve machine-readable data over HTTP.

Other Entity properties are descriptive in nature, or link the Entity to other related entities. Certain Entity subtypes like Annotation, DigitalResource, Message or Organization are provisioned with additional properties that allow for a more complete representation of the object. An extensions property is also defined so that implementers can add custom attributes not described by the model. Optional properties can be ignored when describing an Entity.

IRI

https://purl.imsglobal.org/caliper/Entity

Term

Entity

Subtypes

Agent, AggregateMeasure, AggregateMeasureCollection, Annotation, Assessment, AssessmentItem, AssignableDigitalResource, Attempt, AudioObject, BookmarkAnnotation, Chapter, Collection, Comment, CourseOffering, CourseSection, DateTimeQuestion, DateTimeResponse, DigitalResource, DigitalResourceCollection, Document, FillinBlankResponse, Forum, Frame, Group, HighlightAnnotation, ImageObject, LearningObjective, LikertScale, Link, LtiLink, LtiSession, MediaLocation, MediaObject, Membership, Message, MultipleChoiceResponse, MultipleResponseResponse, MultiselectQuestion, MultiSelectResponse, MultiselectScale, NumericScale, OpenEndedQuestion, OpenEndedResponse, Organization, Page, Person, Query, Question, Questionnaire, QuestionnaireItem, Rating, RatingScaleQuestion, RatingScaleResponse, Response, Result, Scale, Score, SearchResponse, SelectTextResponse, Session, SharedAnnotation, SoftwareApplication Survey, SurveyInvitation, TagAnnotation, Thread, TrueFalseResponse, VideoObject, WebPage

Properties

Like an Event, an Entity is considered semi-structured data consisting of an unordered set of key:value pairs. The base set of Entity properties is listed below. Each property MUST be referenced only once. When representing an Entity as an object the id and type properties are required; all other properties are optional and need not be referenced when describing an Entity. Custom attributes not described by the model MAY be included but MUST be added to the extensions property as a map of key:value pairs. Properties with a value of *null* or empty SHOULD be excluded prior to serialization.

3.1 Annotation Profile

IRI

http://purl.imsglobal.org/caliper/AnnotationProfile

Term

AnnotationProfile

The Caliper Annotation Profile models activities related to the annotation of a DigitalResource. Creating a bookmark, highlighting selected text, sharing a resource, tagging a document, and viewing an annotation are modeled. The generated Annotation is also described and is subtyped for greater type specificity.

The Annotation Profile supports the following user stories:

• As an instructor,
  • I would like to know which students are generating annotations.
  • I would like to know what content is most often annotated.
  • I would like to know what types of annotations are being created.
  • I would like to know which segments of text are being highlighted.
  • I would like to know what tags or notes are being used.
• As a student,
  • I would like to know which of my content is most often annotated.
  • I would like to know what content my peers have annotated or highlighted.
  • I would like to see what tags, notes or highlights I have added.
• As a researcher,
  • I would like to determine if there is a correlation between student annotation behavior and learning objective completion.

The Annotation Profile defines an AnnotationEvent for describing the annotation of resources. Four actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• In particular, a generated Annotation SHOULD be expressed. Pair the action with the appropriate Annotation subtype (e.g., Bookmarked with BookmarkAnnotation). If the generated Annotation is expressed as an object both the annotator and annotated entities SHOULD be referenced.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.2 Assessment Profile

IRI

http://purl.imsglobal.org/caliper/AssessmentProfile

Term

AssessmentProfile

The Caliper Assessment Profile models assessment-related activities including interactions with individual assessment items. Caliper provides Assessment and AssessmentItem entities for describing the object of these activities, as well as a learner's Attempt for recording a count of the number of times an assigned resource has been attempted. Five Response types are also provided for capturing individual item responses.

The Assessment Profile supports the following user stories:

• As an instructor,
  • I want to know how much time is required to complete and submit an assessment.
  • I want to know how much time is spent answering individual assessment items.
  • I want to know which assessment items are completed or skipped.
  • I want to know when learners start their assessments, if test-taking times are flexible.
• As a student,
  • I would like to know how much time I spent completing and submitting an assessment.
  • I would like to know how much time I spent answering individual assessment items.
  • I would like to know which assessment items I skipped.
  • I would like to know the average time it has been taking for other students to complete this assessment.
• As a researcher,
  • I would like to relate assessment timing and results (correct or incorrect, attempts) with student characteristics such as demographics, navigation or score on a pre-test.

The Assessment Profile defines an AssessmentEvent, AssessmentItemEvent, NavigationEvent, and ViewEvent for describing learner interactions with tests and questions. Ten actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• For AssessmentEvent actions, the generated Attempt SHOULD be specified. If an Attempt is expressed as an object the Attempt SHOULD define, at a minimum, the assignee, the assignable, and the count. Set the Attempt count values as follows (per action):
  • Started: set the count value to 1 for a first attempt and increment by 1 for each subsequent attempt.
  • Paused, Resumed, Reset: do not change the current count value.
  • Restarted: increment the count value by 1.
• For each AssessmentItemEvent described, referencing a generated Attempt or Response depends on the action value specified. Set the Attempt count values as follows (per action):
  • Started: set the count value to 1 for a first attempt and increment by 1 for each subsequent attempt.
  • Skipped: do not increment the Attempt count by 1. The current count value MUST remain unchanged.
  • Completed: if desired, specify the learner's Response and reference the associated Attempt via the attempt property. The current count value MUST remain unchanged.
• Parent-child relationships that exist between AssessmentItem and Assessment attempts MAY be represented by use of the Attempt isPartOf property.
• As a learner navigates from one AssessmentItem to another AssessmentItem, the previous AssessmentItem MAY be specified as the referrer.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.3 Assignable Profile

IRI

http://purl.imsglobal.org/caliper/AssignableProfile

Term

AssignableProfile

The Assignable Profile models activities associated with the assignment of digital content to a learner for completion according to specific criteria. Caliper provides a generic AssignableDigitalResource for describing the object of these activities as well as a learner's Attempt for recording a count of the number of times an assigned resource has been attempted.

The Assignable Profile supports the following user stories:

• As an instructor,
  • I want to know who is assigned what material.
  • I want to know how long it takes for students to complete something that has been assigned.
  • I want to know what piece of assigned material presents the biggest challenge (i.e., involves the most retake attempts).
• As a student,
  • I would like to know what assignments are due over the course of this semester.
• As a researcher,
  • I would like to group courses with a similar number and timing of assignments, to understand whether there is correlation between the rhythm of assignments and student outcomes.

The Assignable Profile defines an AssignableEvent, NavigationEvent, and ViewEvent for describing learner interactions with assignments. Eight actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• For each AssignableEvent described, the generated Attempt SHOULD be specified for the following AssignableEvent actions:
  • Started
  • Completed
  • Submitted
  • Reviewed
• If the Attempt is expressed as an object the Attempt SHOULD reference, at a minimum, the assignee, the assignable, and the count. Set the count value to 1 for a first attempt and increment by 1 for each subsequent attempt.
• Parent-child relationships that exist between AssignableDigitalResource attempts MAY be represented by use of the Attempt isPartOf property.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.4 Feedback Profile

IRI

http://purl.imsglobal.org/caliper/FeedbackProfile

Term

FeedbackProfile

The Caliper Feedback Profile models a Person providing informal feedback on a Entity, typically a piece of student work. The profile provides a FeedbackEvent along with Commented and Ranked actions for describing feedback activities. The Rating entity is used to capture quantitative feedback while the Comment entity is used to capture qualitative feedback.

The Feedback Profile supports the following user stories:

• As an instructor,
  • I would like an overview of the peer feedback my students have given to each other.
  • I would like to see the rating my course material has received from my students.
• As a student,
  • I would like to see all the feedback my work has received.
  • I would like to track the perceived quality of my group work by my peers over time.
• As a researcher,
  • I would like to compare the level of engagement different feedback question generate on similar content.
  • I would like to determine if there is a correlation between the quality of peer feedback on course work and learning outcomes.

The Feedback Profile defines a FeedbackEvent for ranking resources and recording comments. Two actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• For a Commented action a generated Comment SHOULD be provided.
• For a Ranked action a generated Rating SHOULD be provided.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.5 Forum Profile

IRI

http://purl.imsglobal.org/caliper/ForumProfile

Term

ForumProfile

The Caliper Forum Profile models learners and others participating in online discussion forums. Forums typically encompass one or more threads or topics to which members can subscribe, post messages and reply to other messages if a threaded discussion is permitted. Caliper provides Forum, Thread, and Message entities for representing the object of these activities.

Using the Forum Profile to track discussion behaviors allows instructors to better understand how students are engaged within discussion forums.

The Forum Profile supports the following user stories:

• As an instructor,
  • I want to know who is posting most often.
  • I want to know which posts in my course generate the most replies.
  • I want to compare graded vs. non-graded discussions.
• As a student,
  • I want to know which of my posts generated the most replies.
  • I want to know which of my replies generated most threads/replies.
• As a researcher,
  • I want to correlate forum participation with overall course outcome or grades.

The Forum Profile defines a ForumEvent, MessageEvent, NavigationEvent, ThreadEvent, and ViewEvent for describing Forum, Thread, and Message interactions. Nine actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• If a Message is expressed as an object and is in the form of a reply, the previous Message that prompted the reply SHOULD be referenced via the Message replyTo property.
• Parent-child relationships that exist between a Message, Thread and a Forum MAY be represented by use of the isPartOf property.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.6 Grading Profile

IRI

http://purl.imsglobal.org/caliper/GradingProfile

Term

GradingProfile

The Caliper Grading Profile models grading activities performed by an Agent, typically a Person or a SoftwareApplication. Grading a learner's Attempt of an AssignableDigitalResource and generating a Score is modeled as is viewing a Result.

The grading profile allows information to be captured about grade changes for a given assessment or submission. This may be useful to understand the way in which students and teachers may be interacting throughout the course.

The Grading Profile supports the following user stories:

• As an instructor,
  • I want to know what was distribution of scores for the most recent assignment.
  • I want to know how often grades are changed for a given assessment.
  • I want to know the number of attempts each student in my course took to submit an assignment.
• As a student,
  • I would like to know the distribution of scores for the most recent assignment.
  • I would like to know my grade compared with the average for the class.
• As a researcher,
  • I would like to measure the effectiveness of instructor feedback on overall student performance.

The Grading Profile defines a GradeEvent for describing the scoring of assignments and a ViewEvent for viewing results. Two actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• For auto-graded scenarios the SoftwareApplication MUST be specified as the actor.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• When describing a Graded action, the generated Score SHOULD be specified. If the generated Score is expressed as an object the attempt, maxScore, and scoreGiven property values SHOULD be provided.
• If a Result is expressed as an object the attempt, maxResultScore, and resultScore property values SHOULD be provided.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.7 Media Profile

IRI

http://purl.imsglobal.org/caliper/MediaProfile

Term

MediaProfile

The Caliper Media Profile models interactions between learners and rich content such as audio, images and video. Implementers can leverage a number of media-related entities including AudioObject, ImageObject, and VideoObject, each subtyped from a generic MediaObject. A MediaLocation entity is also provided in order to represent the current location in an audio or video stream.

The Media Profile supports the following user stories:

• As an instructor,
• I want to which students are using the video platform.
• I want to know which videos are being played the most.
• I want to know how long my students are spending on each video.
• I want to know when students pause a video.
• I want to know if there are instances of students replaying sections of the video.

The Media Profile defines a MediaEvent, NavigationEvent, and ViewEvent for describing interactions with media such as an AudioObject, ImageObject, or VideoObject. Twenty-one actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• A MediaLocation MAY be specified as the target in order to indicate the current playback position in an audio or video stream.
• If the MediaLocation is expressed as an object, set the currentTime value per action as follows:
  • Started, Restarted: set the currentTime value to the beginning or initial starting location in the audio or video stream.
  • Paused: set the currentTime value to the location in the audio or video stream where the pause occurred.
  • Resumed: set the currentTime value to the location in the audio or video stream where the previous pause occurred.
  • Ended: set the currentTime value to the ending or closing location in the audio or video stream.
  • For other MediaEvent supported actions the MediaLocation currentTime value MUST be set to the location in the audio or video stream where the action occurred.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.8 Reading Profile

IRI

http://purl.imsglobal.org/caliper/ReadingProfile

Term

ReadingProfile

The Caliper Reading Profile models activities associated with navigating to and viewing digital textual content. Caliper provides a number of entities representing digital content including a generic DigitalResource and DigitalResourceCollection along with Document, Chapter, Page, WebPage, Message and Frame.

The Reading Profile supports the following user stories:

• As an instructor,
  • I want to know when assigned course content is first accessed by my students.
  • I want to know what materials are being accessed.
  • I want to know how often is the content viewed.
  • I want to know what paths are taken to reach the content.
• As a student,
  • I would like to know how much time I am spending on reading by section.
  • I would like to know how much time I have spent reading today/this week/this month.
  • I would like to know what content I have read most frequently.
  • I would like to know what content is the most frequently read by my peers.
• As a researcher,
  • I would like to understand the most commonly accessed paths through the content.

When used in conjunction with the Assessment Profile viewing patterns can be correlated to performance measures.

The Reading Profile defines a NavigationEvent for traversing resources and a ViewEvent for viewing content. Two actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• A Frame MAY be specified as the target in order to indicate an indexed segment or location.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.9 Resource Management Profile

IRI

http://purl.imsglobal.org/caliper/ResourceManagementProfile

Term

ResourceManagementProfile

The Caliper Resource Management Profile models a Person managing a DigitalResource.

The Resource Management Profile supports the following user stories:

• As an instructor,
  • I would like to measure engagement between different revisions of learning resources over time in order to help determine what content is most effective.
• As a student,
  • I would like to learn about the newly published course resources.
  • I would like to know how much time I have spent reading today/this week/this month.
  • I would like to know what content I have read most frequently.
  • I would like to know what content is the most frequently read by my peers.
• As a content developer,
  • I would like to measure the interval between resource availability and learner engagement with learning resources in order to gain insights into both the administrative impact on the learning process and the timing decisions of learners who are expected to ingest the materials.
• As an administrator,
  • I would like to measure the usage of a course which is designated as a template course.
  • I would like to measure the instructor engagement in building courses which utilize one or more course components.

The Resource Management Profile defines a ResourceManagementEvent for describing the creation, management, and disposition of DigitalResource entities. Fourteen actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• For a Copied action the generated copy of the DigitalResource SHOULD be referenced.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.10 Search Profile

IRI

http://purl.imsglobal.org/caliper/SearchProfile

Term

SearchProfile

The Caliper Search Profile models an actor, typically a learner, querying a resource for information. The profile provides a SearchEvent and a Searched action for describing information retrieval activities. An optional SearchResponse entity can be employed to describe the Query submitted by a user as well as any searchResults returned as a result of the search.

The Search Profile supports the following user stories:

• As a librarian,
  • I would like to know the frequency of searches conducted and the resources queried.
• As an instructor,
  • I would like to know how students designed and used structured queries.
• As a student,
  • I would like to have a record of the topics I searched and the query terms I employed.

When the Search Profile is used in conjunction with the Reading Profile, a learner's navigation, search, and viewing behavior can be combined to provide a richer picture of learner interactions with digital resources.

The Search Profile defines a SearchEvent for querying resources. A single action is described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• In particular, a generated SearchResponse SHOULD be expressed. The SearchResponse can be employed to describe the Query submitted by a user as well as any searchResults returned as a result of the search.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.11 Session Profile

IRI

http://purl.imsglobal.org/caliper/SessionProfile

Term

SessionProfile

The Caliper Session Profile models the creation and subsequent termination of a user session established by a Person interacting with a SoftwareApplication. A Session entity is described for representing the user session.

The Session Profile can facilitate the capture of data about who is logging into the learning environment, and more importantly, which students are not logging in.

The Session Profile supports the following user stories:

• As an instructor,
  • I want to know which students have not logged in for more than a week.
  • I want to know who logs in and logs out most and least frequently.
• As a student,
  • I would like to know what time of day I typically login.
  • I would like to know how much time I spend in the learning application each day/week/month.
  • I would like to know how my session durations compare to my peers.
  • I would like to be notified if I have not logged in for more than a week (when other students are also logging in).
• As a researcher,
  • I would like to understand patterns or trends in student login activity.
• As an administrator,
  • I would like to learn about host server IP and user agent of the users accessing my application on a given moment.

The Session Profile defines a SessionEvent for recording application log in, log out, and time out activity.

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• For LoggedIn and LoggedOut actions, a Person MUST be specified as the actor. For a TimedOut action, a SoftwareApplication MUST be specified as the actor.
• For a TimedOut action, the SoftwareApplication MUST be specified as the actor and the Session MUST be specified as the object. If a Session is expressed as an object, the user, startedAtTime, endedAtTime, and duration property values SHOULD be provided.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• For a LoggedIn action, if the actor is attempting to access a particular DigitalResource, the resource MAY be designated as the target of the interaction.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.12 Survey Profile

IRI

http://purl.imsglobal.org/caliper/SurveyProfile

Term

SurveyProfile

The Caliper Survey Profile provides a vocabulary for describing events associated with a respondent's participation in online surveys. A key use case involves instrumenting platforms that provide online surveys that explore the student learning experience, student engagement, learning activities, learning progress, and learning performance. The profile models a Person, typically a respondent or a rater, participating in a survey in order to provide feedback on their learning and academic experiences.

Everyone learns differently with a mix of their own learning styles. It is also known that a student’s time spent on online learning activities does not necessarily indicate that the student finds the materials easy or hard, interesting or boring, useful or not to their learning. Student feedback is a key source of data that can help glean insights into students’ learning styles and interests, as well as areas to improve. In that sense, student feedback data adds an additional dimension of students’ behavioral data for learning analytics, such as learning about student perceptions of how effectively activities helped student learning and what specific areas in teaching and learning can be improved to enhance students’ learning experience and performance. The Caliper Survey Profile expands the pool of Caliper-instrumented learning data profiles to enhance the learning analytics across the analytics continuum — descriptive, diagnostic, predictive, and prescriptive — by allowing student voices to be incorporated in order to make learning analytics more robust.

The Survey Profile supports the following user stories:

• As an instructor,
  • I would like to analyze survey response rates and responses to gauge the engagement level of my students.
  • I would like to analyze survey response rates and responses to identify specific actions that I need to take to improve my teaching (course design, delivery, etc) for student learning experience and outcomes.
  • I would like to analyze survey response rates and responses to measure progress on my teaching improvement efforts and inform my decisions on what actions to take to further improve my teaching - acting on the feedback.
  • I would like to use student feedback to determine the efficacy of personalized or adaptive learning interventions and to help design new learning plans and strategies with these methods.
  • I would like to analyze student feedback to find ways to measure the effectiveness of my teaching, assess student progress, and identify areas for corrective intervention.
• As a student,
  • I would like to know what are my strengths and weaknesses in comparison to other students, and identify areas that I can work on to improve my learning performance.
• As a researcher,
  • I would like to monitor and analyze survey response rates and patterns to ensure the reliability and validity of the data collected, as well as to inform future collection methods.
  • I would like to assess whether student feedback on learning experiences can help create predictive models — in combination with behavioral data, demographics, and performance — for student retention and success.
• As an administrator,
  • I would like to analyze survey response rates to track effectiveness of strategies used to get the sufficient amount of data that can give statistical confidence to interpret appropriately (as opposed to over interpreting or misusing what data says).
  • I would like to analyze feedback survey responses to identify factors that impact the quality of the program and identify areas to improve - what aspects of the program to change and where to invest resources to ensure the program success with desired student learning outcomes and faculty professional development.
  • I would like to use responses to survey questions concerning workload in combination with other behavioral data to determine whether workloads are set to optimize learning.

The Survey Profile defines a SurveyEvent, SurveyInvitationEvent, QuestionnaireEvent, QuestionnaireItemEvent, NavigationEvent, and ViewEvent for describing survey-related activities. Twelve actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• For QuestionnaireEvent actions, the generated Attempt SHOULD be specified. If an Attempt is expressed as an object the Attempt SHOULD define, at a minimum, the assignee, the assignable, and the count. For Started actions set the count value to 1 for a first attempt and increment by 1 for each subsequent attempt.
• For each QuestionnaireItemEvent described, referencing a generated Attempt or Response depends on the action value specified. Set the Attempt count values as follows (per action):
  • Started: set the count value to 1 for a first attempt and increment by 1 for each subsequent attempt.
  • Skipped: do not increment the Attempt count by 1. The current count value MUST remain unchanged.
  • Completed: if desired, specify the respondent's Response and reference the associated Attempt via the attempt property. The current count value MUST remain unchanged.
• Parent-child relationships that exist between QuestionnaireItem and Questionnaire attempts MAY be represented by use of the Attempt isPartOf property.
• As a respondent navigates from one QuestionnaireItem to another QuestionnaireItem, the previous QuestionnaireItem MAY be specified as the referrer.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.13 Tool Launch Profile

IRI

http://purl.imsglobal.org/caliper/ToolLaunchProfile

Term

ToolLaunchProfile

The Caliper Tool Launch Profile is intended to capture the utilization of learning tools from a centralized location, such as an LTI Tool Platform (often an LMS). As such, it is distinct from the Caliper Tool Use Profile, also defined in this specification, which captures tool usage as reported by the individual tools themselves (i.e. decentralized capture).

The Tool Launch and Tool Use Profiles have their own unique set of advantages; the primary advantage of the Tool Launch Profile is that it only requires a single sensor to be deployed (typically in an LMS), whereas the Tool Use Profile requires all tools being measured to implement the Caliper sensor API.

The Tool Launch Profile supports the following user stories:

• As an administrator,
  • I would like to know what student data is being passed to LTI tools.
  • I would like to know which tools are launched the most and the least.
  • I would like to know which courses utilize certain tools the most and the least.
• As a researcher,
  • I would like to know if Caliper event data combined with demographic data reveals demographic variances in the utilization of the available tools.
  • I would like to know if there are temporal variances in the utilization of the available tools.

The Tool Launch Profile defines a ToolLaunchEvent for describing a Person launching a tool from a platform or returning to a platform after completing a tool session. Two actions are described:

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• A generated DigitalResource or, more likely, one of its specific subtypes MAY be expressed if the workflow includes a resource intended for the receiver of the workflow message associated with this event (for example, a file, or image, or LTI resource link for the receiver to embed within its system).
• For a Launched action a target MAY be specified to record the fully qualified entry-point URL on the external tool to which the platform launches.
• For a Returned action a target MAY be specified to record the fully qualified entry-point URL on the platform to which the tool is redirecting the workflow after user activity from the original launch finishes (this could be the launch_presentation_return_url in the case of a simple LTI Resource Link request; it could also be the deep_link_return_url in the case of a Deep Linking Response message).
• For a Launched action, the federatedSession MUST be referenced. Workflows that include a specific "return message" component (e.g. LTI Deep Linking response messages) SHOULD provide the federatedSession and SHOULD populate its messageParameters property with the message parameters in the response message.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.14 Tool Use Profile

IRI

http://purl.imsglobal.org/caliper/ToolUseProfile

Term

ToolUseProfile

The Caliper Tool Use Profile models an intended interaction between a user and a tool. In other words, when a Person utilizes a SoftwareApplication in a manner that the application determines to be its intended use for learning, an application that implements the Tool Use Profile can emit a ToolUseEvent indicating such usage.

The Tool Use Profile enables the gathering of basic usage information. It provides an easy way to get started with a base level of instrumentation by allowing the learning tool to make the determination of its own use. Any learning app can be instrumented using this profile to detect when a learner accesses the tool and uses it in the way it was intended.

The Tool Use Profile supports the following user stories:

• As an instructor,
  • I want to know what tools are being used, and how often.
  • I want to know who are the most active and least active users of tools.
  • I want to know whether or not tool usage helps or hinders student performance.
  • I want to know which tools have the greatest impact on student performance.
  • I want to know how much time learners are spending using a tool.
  • I want to know how much curricular progress learners have made in a tool.
  • I want to be able to view my students' "time on task" across multiple learning tools using a dashboard powered by a Caliper event store.
• As a student,
  • I want to confirm that the progress and time metrics I see in a learning tool matches the metrics I see in an aggregated dashboard.
• As a researcher,
  • I want to be able to study the impact of a student's curricular progress in a learning tool on his or her academic achievement.

The Tool Use Profile defines a ToolUseEvent for describing a Person using a learning tool in a way that the tool's creators have determined is an indication of a learning interaction. A single action is described.

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• A generated AggregateMeasureCollection containing one or more AggregateMeasure entities providing information on a learner's "progress" using the tool MAY be expressed. The following metrics MAY be recorded:
  • AssessmentPassed
  • AssessmentSubmitted
  • MinutesOnTask
  • SkillsMastered
  • StandardsMastered
  • UnitsCompleted
  • UnitsPassed
  • WordsRead
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

3.15 General Profile

Use of the General Profile is strictly limited to describing interactions not modeled by the current set of Caliper Profiles. Only the generic Event may be utilized to describe such activities.

IRI

http://purl.imsglobal.org/caliper/GeneralProfile

Term

GeneralProfile

The Caliper General Profile provides a generic Event for describing learning or supporting activities that have yet to be modeled by Caliper. Any of the Caliper actions described in this specification can be used to describe the interaction between the actor and the object.

• The properties id, type, actor, action, object, and eventTime are required and MUST be referenced.
• Although optional, the governing profile SHOULD also be specified.
• Likewise, if activity context data is available and relevant the optional properties generated, edApp, group, membership, target, referrer, and session SHOULD be referenced.
• If an LTI Tool mints the event, the federatedSession SHOULD be referenced.
• A map of additional extensions MAY be included but beware the inherent interoperability limitations of transmitting data not described by the model.

4.1 JSON-LD Context

JSON-LD documents require inclusion of a context, denoted by the @context keyword, a property employed to map document Terms to IRIs. JSON-LD contexts can be embedded inline or referenced externally in a document. Inclusion of a JSON-LD context provides an economical way for Caliper to communicate document semantics to services interested in consuming Caliper event data.

1EdTech provides a Caliper JSON-LD context document (http://purl.imsglobal.org/ctx/caliper/v1p2/) for remote mapping of Caliper Terms to IRIs. Implementers are encouraged to familiarize themselves with the term definitions described therein.

Requirements

• Each Caliper Event and Entity describe document generated by a Sensor MUST be provisioned with a JSON-LD @context defined as a property of the top-level object.
• The top-level @context property type MUST be defined as a string or an array.
• If the top-level @context value is defined as a string it MUST be set to the Caliper remote context URL "http://purl.imsglobal.org/ctx/caliper/v1p2".
• If the top-level @context value is defined as an array of multiple contexts, the remote Caliper JSON-LD context MUST be listed last in order to ensure that Caliper terms retain their primacy given that JSON-LD parsers rely on a "most-recently-defined-wins" approach when evaluating duplicate terms.
• Referencing the remote Caliper JSON-LD context document in the top-level @context is mandatory. The terms it defines MUST NOT be defined inline as an object.
• Additional remote or inline local contexts may be referenced any time a JSON object is defined in order to ascribe meaning to terms not described by the model. These contexts are additive in nature and can be defined as a string, object or array. Duplicate context references SHOULD be omitted when serializing the object. Nested local contexts that are added to the active context at processing time MUST NOT override Caliper terms defined by the top-level context.

In the following example, @context is a top-level Event property with a value that references the remote Caliper JSON-LD context document. All of the Event key:value pairings are mapped to [IRIs] in the referenced context.

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:fcd495d0-3740-4298-9bec-1154571dc211",
  "type": "SessionEvent",
  "profile": "SessionProfile",
  "actor": {
    "id": "https://example.edu/users/554433",
    "type": "Person"
  },
  "action": "LoggedIn",
  "object": {
    "id": "https://example.edu",
    "type": "SoftwareApplication",
    "version": "v2"
  },
  "eventTime": "2016-11-15T10:15:00.000Z",
  "edApp": "https://example.edu",
  "session": {
    "id": "https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259",
    "type": "Session",
    "user": "https://example.edu/users/554433",
    "dateCreated": "2016-11-15T10:00:00.000Z",
    "startedAtTime": "2016-11-15T10:00:00.000Z"
  }
}

As noted above, a JSON-LD document can reference more than one context. Subject to the requirements listed above additional contexts MAY be defined for a Caliper Event or Entity describe in order to map non-Caliper vocabulary terms to their respective IRIs. The Caliper JSON-LD context MUST be listed last if an array of contexts is referenced.

{
  "@context": ["https://schema.org/docs/jsonldcontext.json", "http://purl.imsglobal.org/ctx/caliper/v1p2"]
  . . .
}

Contexts embedded inline can be combined with externally referenced contexts. Again, order matters.

{
TODO: DEFINE NEW EXAMPLE. v1p1 example superseded by new SearchEvent.
}

4.2 Identifiers

Linked Data relies on IRIs/URIs for the identification and retrieval of resources. Likewise, JSON-LD specifies the use of IRIs/URIs for identifying most nodes (i.e., JSON objects) and their attributes. Caliper too specifies the use of IRIs for identifying nodes (i.e., the things or entities being described) and their attributes.

IRI values MUST be absolute containing a scheme, path and optional query and fragment segments. A URI employing the URN scheme MAY be used as an identifier although care should be taken when employing a location-independent identifier since it precludes the possibility of utilizing it in future to retrieve machine-readable data over HTTP. If an IRI is deemed inappropriate for the resource a blank node identifier may be assigned.

JSON-LD provides a special @id keyword for assigning identifiers to nodes. For Caliper, the JSON-LD @id keyword is aliased as id in the external 1EdTech Caliper JSON-LD context. This is done in order to avoid the temptation of employing JSON-LD keywords as property names and is aligned with JSON-LD community practice. Thus, each Caliper Event and Entity described by the model is provisioned with an id rather than @id property for identifying the resource.

Every Entity MUST be assigned an identifier in the form of a valid IRI or a blank node identifier. The IRI MUST be unique and persistent. The IRI SHOULD be dereferenceable; i.e., capable of returning a representation of the Entity. A URI employing the URN scheme MAY also be utilized.

Unlike Entities, each Event MUST be assigned a 128-bit long universally unique identifier (UUID) formatted as a URN per [RFC4122], which describes a URN namespace for UUIDs.

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:ff9ec22a-fc59-4ae1-ae8d-2c9463ee2f8f",
  "type": "NavigationEvent",
  "profile": "ReadingProfile",
  "actor": {
    "id": "https://example.edu/users/554433",
    "type": "Person"
  },
  "action": "NavigatedTo",
  "object": {
    "id": "https://example.edu/terms/201601/courses/7/sections/1/pages/2",
    "type": "WebPage",
    "name": "Learning Analytics Specifications",
    "description": "Overview of Learning Analytics Specifications with particular emphasis on 1EdTech Caliper.",
    "dateCreated": "2016-08-01T09:00:00.000Z"
  },
  "eventTime": "2016-11-15T10:15:00.000Z",
  "referrer": {
    "id": "https://example.edu/terms/201601/courses/7/sections/1/pages/1",
    "type": "WebPage"
  },
  "edApp": "https://example.edu",
  "group": {
    "id": "https://example.edu/terms/201601/courses/7/sections/1",
    "type": "CourseSection",
    "courseNumber": "CPS 435-01",
    "academicSession": "Fall 2016"
  },
  "membership": {
    "id": "https://example.edu/terms/201601/courses/7/sections/1/rosters/1",
    "type": "Membership",
    "member": "https://example.edu/users/554433",
    "organization": "https://example.edu/terms/201601/courses/7/sections/1",
    "roles": [ "Learner" ],
    "status": "Active",
    "dateCreated": "2016-08-01T06:00:00.000Z"
  },
  "session": {
    "id": "https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259",
    "type": "Session",
    "startedAtTime": "2016-11-15T10:00:00.000Z"
  }
}

4.3 Types and Type Coercion

JSON-LD employs the @type keyword in two ways. Individual nodes (i.e., the thing being described) can be assigned a type. Values can also be associated with or coerced to a particular type. Both node types and typed values are specified in the Caliper JSON-LD context. As with the aliasing of @id as id, the @type keyword is aliased as type in the external 1EdTech Caliper JSON-LD context in keeping with JSON-LD community practice.

Caliper permits Entity values to be expressed either as a JSON object or as a string corresponding to its IRI. JSON-LD also supports the coercion of data values to specified types based on value type mappings defined in a JSON-LD context. For a given @type the keywords @id or @vocab may be assigned as a value in order to signal to a JSON-LD parser that if a term's instance value is set to a string it is to be interpreted as an IRI. Type coercion of this sort provides representational flexibility that implementers are encouraged to leverage.

The following MessageEvent example utilizes an inline context to illustrate how JSON-LD types can be specified in a context. The MessageEvent, Person and Message terms are all considered node types. Other terms illustrate the coercion of values to specified data types. In the example below, the values of the actor, object and edApp terms are coerced to the @id keyword. Use of this convention informs JSON-LD parsers that string values are to be interpreted as IRIs (as in the case of edApp). In a like manner, the action value is coerced to the @vocab keyword indicating that the value is to be interpreted as a Term defined in the active context or as an IRI; in this case Posted. Terms such as name, description, dateCreated, dateModified and duration are coerced to a particular value type such as a string, integer, boolean or date.

{
  "@context": {
    "id": "@id",
    "type": "@type",
    "caliper": "http://purl.imsglobal.org/caliper/",
    "verb": "http://purl.imsglobal.org/caliper/actions/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "ForumProfile": "caliper:profiles/ForumProfile",
    "MessageEvent": "caliper:MessageEvent",
    "Message": "caliper:Message",
    "Person": "caliper:Person",
    "actor": {"@id": "caliper:actor", "@type": "@id"},
    "action": {"@id": "caliper:action", "@type": "@vocab"},
    "edApp": {"@id": "caliper:edApp", "@type": "@id"},
    "object": {"@id": "caliper:object", "@type": "@id"},
    "profile": {"@id": "caliper:profile", "@type": "@vocab"},
    "body": {"@id": "caliper:body", "@type": "xsd:string"},
    "dateCreated": {"@id": "caliper:dateCreated", "@type": "xsd:dateTime"},
    "eventTime": {"@id": "caliper:eventTime", "@type": "xsd:dateTime"},
    "Posted": "verb:Posted"},
  "id": "urn:uuid:0d015a85-abf5-49ee-abb1-46dbd57fe64e",
  "type": "MessageEvent",
  "profile": "ForumProfile",
  "actor": {
    "id": "https://example.edu/users/554433",
    "type": "Person"
  },
  "action": "Posted",
  "object": {
    "id": "https://example.edu/sections/1/forums/2/topics/1/messages/2",
    "type": "Message",
    "body": "What does Caliper Event JSON-LD look like?",
    "dateCreated": "2018-12-15T10:15:00.000Z"
  },
  "eventTime": "2018-12-15T10:15:00.000Z",
  "edApp": "https://example.edu"
}

As the abbreviated ForumEvent example below demonstrates, in cases where an Event references the same Entity more than once (e.g., actor, member, user; group, organization), or a property is associated with a specific type (e.g., edApp) or an Entity possesses an IRI that is dereferenceable, consider expressing the value as a string corresponding to the entity's IRI.

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:a2f41f9c-d57d-4400-b3fe-716b9026334e",
  "type": "ForumEvent",
  "profile": "ForumProfile",
  "actor": {
    "id": "https://example.edu/users/554433",
    "type": "Person"
  },
  "action": "Subscribed",
  "object": {
    "id": "https://example.edu/terms/201601/courses/7/sections/1/forums/1",
    "type": "Forum",
    "name": "Caliper Forum",
    "isPartOf": {
      "id": "https://example.edu/terms/201601/courses/7/sections/1",
      "type": "CourseSection"
    },
    "dateCreated": "2016-09-14T11:00:00.000Z"
  },
  "eventTime": "2016-11-15T10:16:00.000Z",
  "edApp": {
    "id": "https://example.edu/forums",
    "type": "SoftwareApplication",
    "version": "v2"
  },
  "group": {
    "id": "https://example.edu/terms/201601/courses/7/sections/1",
    "type": "CourseSection",
    "courseNumber": "CPS 435-01",
    "academicSession": "Fall 2016"
  },
  "membership": {
    "id": "https://example.edu/terms/201601/courses/7/sections/1/rosters/1",
    "type": "Membership",
    "member": "https://example.edu/users/554433",
    "organization": "https://example.edu/terms/201601/courses/7/sections/1",
    "roles": [ "Learner" ],
    "status": "Active",
    "dateCreated": "2016-08-01T06:00:00.000Z"
  },
  "session": {
    "id": "https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259",
    "type": "Session",
    "startedAtTime": "2016-11-15T10:00:00.000Z"
  }
}

Indeed, the example ForumEvent could be thinned still further if each referenced Entity is provisioned with a dereferenceable IRI that permits consumers to retrieve a more robust representation of the object if required.

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:a2f41f9c-d57d-4400-b3fe-716b9026334e",
  "type": "ForumEvent",
  "profile": "ForumProfile",
  "actor": "https://example.edu/users/554433",
  "action": "Subscribed",
  "object": "https://example.edu/terms/201801/courses/7/sections/1/forums/1",
  "eventTime": "2018-11-15T10:16:00.000Z",
  "edApp": "https://example.edu/forums",
  "group": "https://example.edu/terms/201801/courses/7/sections/1",
  "membership": "https://example.edu/terms/201801/courses/7/sections/1/rosters/1",
  "session": "https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259"
}

4.4 Anonymous Entities

Caliper has a formal convention for serializing anonymous entities. When a Sensor application wants to explicitly indicate that an Entity it is sending in an Event is anonymous, it should transmit an anonymous form of that Entity in its normal place within the Event. Caliper indicates an anonymous Entity by using the full Caliper vocabulary type IRI value for that Entity as its id value.

Note that because a Caliper Endpoint might choose to store received Caliper entities as individual nodes in a data graph, it may not be appropriate for a Sensor to send more properties in an anonymous Entity than its id and type, as these properties may not get recorded or may get overwritten by subsequent uses of the same type of anonymous Entity. By best practice, a Sensor should always send anonymous entities fully composed in-line within an Event and not separately described. Also by best practice, a Caliper Endpoint should treat this anonymous use in a distinct way to preserve any additional properties that might also be carried with the anonymous Entity within the Event.

Sensor applications SHOULD NOT use this method to convey depersonalized entities. The methods by which Sensor applications might depersonalize entities to obscure or safeguard their identity are not within the scope of this document.

The following example illustrates how an anonymous Person might be transmitted by a Sensor:

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "http://purl.imsglobal.org/caliper/Person",
  "type": "Person"
}

A Caliper Event can include multiple anonymous entities, as in the case of the following ToolUseEvent where the edApp has been configured to report only the times and context of its use, but not to identify the actor or the group using the SoftwareApplication.

{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:7c0fc54b-cf2a-426f-9203-b2c97fb77bfd",
  "type": "ToolUseEvent",
  "profile": "ToolUseProfile",
  "actor": {
    "id": "http://purl.imsglobal.org/caliper/Person",
    "type": "Person"
  },
  "action": "Used",
  "object": {
    "id": "https://example.edu",
    "type": "SoftwareApplication"
  },
  "eventTime": "2018-11-15T10:15:00.000Z",
  "edApp": "https://example.edu",
  "group": {
    "id": "http://purl.imsglobal.org/caliper/CourseSection",
    "type": "CourseSection"
  },
  "membership": {
    "id": "http://purl.imsglobal.org/caliper/Membership",
    "type": "Membership",
    "member": {
      "id": "http://purl.imsglobal.org/caliper/Person",
      "type": "Person"
    },
    "organization": {
      "id": "http://purl.imsglobal.org/caliper/CourseSection",
      "type": "CourseSection"
    },
    "roles": [ "Learner" ],
    "status": "Active"
  }
}

5.1 Behavior

A Sensor MUST implement the following behaviors:

• create JSON object representations of Caliper Event and Entity types as described in the Serialization Section. The particular Event and Entity types that a Sensor must be capable of expressing are determined by the profiles implemented as described in Section 3.0.
• express Entity values as either an object or a string corresponding to the resource's IRI as described in Section 2.2.
• serialize Caliper Envelope objects as JSON as described in Section 5.2. Event and Entity describe data serialized as JSON-LD MUST be transmitted inside an Envelope as described in Sections 5.2 and 5.3.
• transmit serialized Caliper Envelopes containing Event and/or Entity describe data to a target Endpoint over HTTP as described in Section 5.4.

A Sensor MAY be assigned other responsibilities such as validating Caliper Event and Entity data but such capabilities need not be exposed to learning data providers.

5.2 Envelope

Caliper Event and Entity data MUST be transmitted inside a Caliper Envelope, a purpose-built JSON data structure that includes metadata about the emitting Sensor and the data payload.

Properties

Caliper Envelope properties are listed below. The sensor, sendTime, dataVersion and data properties are required. Each property MUST be referenced only once. No custom properties are permitted.

5.3 JSON-LD Payload

Each Event and Entity describe transmitted inside an Envelope MUST be serialized as a JSON-LD document.

{
  "sensor": "https://example.edu/sensors/1",
  "sendTime": "2016-11-15T11:05:01.000Z",
  "dataVersion":  "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "data": [
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594",
      "type": "AssessmentEvent",
      "profile": "AssessmentProfile",
      "actor": {
        "id": "https://example.edu/users/554433",
        "type": "Person"
      },
      "action": "Started",
      "object": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1",
        "type": "Assessment",
        "name": "Quiz One",
        "dateToStartOn": "2016-11-14T05:00:00.000Z",
        "dateToSubmit": "2016-11-18T11:59:59.000Z",
        "maxAttempts": 2,
        "maxSubmits": 2,
        "maxScore": 25.0,
        "version": "1.0"
      },
      "generated": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/users/554433/attempts/1",
        "type": "Attempt",
        "assignee": "https://example.edu/users/554433",
        "assignable": "https://example.edu/terms/201601/courses/7/sections/1/assess/1",
        "count": 1,
        "dateCreated": "2016-11-15T10:15:00.000Z",
        "startedAtTime": "2016-11-15T10:15:00.000Z"
      },
      "eventTime": "2016-11-15T10:15:00.000Z",
      "edApp": {
        "id": "https://example.edu",
        "type": "SoftwareApplication",
        "version": "v2"
      },
      "group": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1",
        "type": "CourseSection",
        "courseNumber": "CPS 435-01",
        "academicSession": "Fall 2016"
      },
      "membership": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/rosters/1",
        "type": "Membership",
        "member": "https://example.edu/users/554433",
        "organization": "https://example.edu/terms/201601/courses/7/sections/1",
        "roles": [ "Learner" ],
        "status": "Active",
        "dateCreated": "2016-08-01T06:00:00.000Z"
      },
      "session": {
        "id": "https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259",
        "type": "Session",
        "startedAtTime": "2016-11-15T10:00:00.000Z"
      }
    }
  ]
}

{
  "sensor": "https://example.edu/sensors/1",
  "sendTime": "2016-11-15T11:05:01.000Z",
  "dataVersion": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "data": [
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "https://example.edu/users/554433",
      "type": "Person",
      "otherIdentifiers": [
        {
          "type": "SystemIdentifier",
          "identifier": "example.edu:71ee7e42-f6d2-414a-80db-b69ac2defd4",
          "identifierType": "LisSourcedId"
        },
        {
          "type": "SystemIdentifier",
          "identifier": "https://example.edu/users/554433",
          "identifierType": "LtiUserId",
          "source":  {
            "id": "https://example.edu",
            "type": "SoftwareApplication"
          }
        },
        {
          "type": "SystemIdentifier",
          "identifier": "jane@example.edu",
          "identifierType": "EmailAddress",
          "source": "https://example.edu"
        },
        {
          "type": "SystemIdentifier",
          "identifier": "4567",
          "identifierType": "SystemId",
          "extensions": {
            "com.examplePlatformVendor.identifier_type": "UserIdentifier"
          }
        }
      ],
      "dateCreated": "2016-08-01T06:00:00.000Z",
      "dateModified": "2016-09-02T11:30:00.000Z"
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1?ver=v1p0",
      "type": "Assessment",
      "name": "Quiz One",
      "items": [
        {
          "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/items/1",
          "type": "AssessmentItem"
        },
        {
          "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/items/2",
          "type": "AssessmentItem"
        },
        {
          "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/items/3",
          "type": "AssessmentItem"
        }
      ],
      "dateCreated": "2016-08-01T06:00:00.000Z",
      "dateModified": "2016-09-02T11:30:00.000Z",
      "datePublished": "2016-08-15T09:30:00.000Z",
      "dateToActivate": "2016-08-16T05:00:00.000Z",
      "dateToShow": "2016-08-16T05:00:00.000Z",
      "dateToStartOn": "2016-08-16T05:00:00.000Z",
      "dateToSubmit": "2016-09-28T11:59:59.000Z",
      "maxAttempts": 2,
      "maxScore": 15.0,
      "maxSubmits": 2,
      "version": "1.0"
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "https://example.edu",
      "type": "SoftwareApplication",
      "version": "v2"
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "https://example.edu/terms/201601/courses/7/sections/1",
      "type": "CourseSection",
      "academicSession": "Fall 2016",
      "courseNumber": "CPS 435-01",
      "name": "CPS 435 Learning Analytics, Section 01",
      "otherIdentifiers": [
        {
          "type": "SystemIdentifier",
          "identifier": "example.edu:SI182-001-F16",
          "identifierType": "LisSourcedId"
        }
      ],
      "category": "seminar",
      "subOrganizationOf": {
        "id": "https://example.edu/terms/201601/courses/7",
        "type": "CourseOffering",
        "courseNumber": "CPS 435"
      },
      "dateCreated": "2016-08-01T06:00:00.000Z"
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594",
      "type": "AssessmentEvent",
      "profile": "AssessmentProfile",
      "actor": "https://example.edu/users/554433",
      "action": "Started",
      "object": "https://example.edu/terms/201601/courses/7/sections/1/assess/1?ver=v1p0",
      "generated": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/users/554433/attempts/1",
        "type": "Attempt",
        "assignee": "https://example.edu/users/554433",
        "assignable": "https://example.edu/terms/201601/courses/7/sections/1/assess/1?ver=v1p0",
        "count": 1,
        "dateCreated": "2016-11-15T10:15:00.000Z",
        "startedAtTime": "2016-11-15T10:15:00.000Z"
      },
      "eventTime": "2016-11-15T10:15:00.000Z",
      "edApp": "https://example.edu",
      "group": "https://example.edu/terms/201601/courses/7/sections/1",
      "membership": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/rosters/1",
        "type": "Membership",
        "member": "https://example.edu/users/554433",
        "organization": "https://example.edu/terms/201601/courses/7/sections/1",
        "roles": [ "Learner" ],
        "status": "Active",
        "dateCreated": "2016-08-01T06:00:00.000Z"
      },
      "session": {
        "id": "https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259",
        "type": "Session",
        "startedAtTime": "2016-11-15T10:00:00.000Z"
      }
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:dad88464-0c20-4a19-a1ba-ddf2f9c3ff33",
      "type": "AssessmentEvent",
      "profile": "AssessmentProfile",
      "actor": "https://example.edu/users/554433",
      "action": "Submitted",
      "object": "https://example.edu/terms/201601/courses/7/sections/1/assess/1?ver=v1p0",
      "generated": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/users/554433/attempts/1",
        "type": "Attempt",
        "assignee": "https://example.edu/users/554433",
        "assignable": "https://example.edu/terms/201601/courses/7/sections/1/assess/1?ver=v1p0",
        "count": 1,
        "dateCreated": "2016-11-15T10:15:00.000Z",
        "startedAtTime": "2016-11-15T10:15:00.000Z",
        "endedAtTime": "2016-11-15T10:55:12.000Z",
        "duration": "PT40M12S"
      },
      "eventTime": "2016-11-15T10:25:30.000Z",
      "edApp": "https://example.edu",
      "group": "https://example.edu/terms/201601/courses/7/sections/1",
      "membership": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/rosters/1",
        "type": "Membership",
        "member": "https://example.edu/users/554433",
        "organization": "https://example.edu/terms/201601/courses/7/sections/1",
        "roles": ["Learner"],
        "status": "Active",
        "dateCreated": "2016-08-01T06:00:00.000Z"
      },
      "session": {
        "id": "https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259",
        "type": "Session",
        "startedAtTime": "2016-11-15T10:00:00.000Z"
      }
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:a50ca17f-5971-47bb-8fca-4e6e6879001d",
      "type": "GradeEvent",
      "profile": "GradingProfile",
      "actor": {
        "id": "https://example.edu/autograder",
        "type": "SoftwareApplication",
        "version": "v2"
      },
      "action": "Graded",
      "object": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/users/554433/attempts/1",
        "type": "Attempt",
        "assignee": "https://example.edu/users/554433",
        "assignable": "https://example.edu/terms/201601/courses/7/sections/1/assess/1?ver=v1p0",
        "count": 1,
        "dateCreated": "2016-11-15T10:15:00.000Z",
        "startedAtTime": "2016-11-15T10:15:00.000Z",
        "endedAtTime": "2016-11-15T10:55:12.000Z",
        "duration": "PT40M12S"
      },
      "eventTime": "2016-11-15T10:57:06.000Z",
      "edApp": "https://example.edu",
      "generated": {
        "id": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/users/554433/attempts/1/scores/1",
        "type": "Score",
        "attempt": "https://example.edu/terms/201601/courses/7/sections/1/assess/1/users/554433/attempts/1",
        "maxScore": 15.0,
        "scoreGiven": 10.0,
        "scoredBy": "https://example.edu/autograder",
        "comment": "auto-graded exam",
        "dateCreated": "2016-11-15T10:56:00.000Z"
      },
      "group": "https://example.edu/terms/201601/courses/7/sections/1"
    }
  ]
}

5.4 HTTP Requests

A Caliper Sensor MUST be capable of transmitting Caliper data successfully to a Caliper Endpoint. Communication with an Endpoint is limited to message exchanges using the Hypertext Transport Protocol (HTTP) with the connection encrypted with Transport Layer Security (TLS). See the 1EdTech Security Framework for more information on complete security practices.

Each message request MUST consist of a single JSON representation of a Caliper Envelope. Messages MUST be sent using the POST request method. The HTTP Host and Content-Type request header fields MUST be set.

The Caliper endpoint also provides configuration information if a GET request is sent. This is explained in the Configuration Information section.

A Sensor SHOULD also set the Authorization request header field using the "Bearer" authentication scheme described in [RFC6750], Section 2.1. The b64token authorization credential sent by a Sensor MUST be one the Endpoint can validate although the credential MAY be opaque to the emitting Sensor itself.

6.1 HTTP Responses

Following receipt of a Sensor HTTP request message, the Endpoint MUST reply with an HTTP response message. The response will include a three-digit status code indicating whether or not the Endpoint was able to understand and satisfy the request, as defined by [RFC7231].

When signalling to a Sensor that the endpoint has successfully received the request message, the Endpoint MUST reply with a 2xx class status code. By best practice, the Endpoint SHOULD use the 200 OK response but might instead choose to send a 201 Created (to indicate successful receipt of the message and creation of a new resource) or a 202 Accepted (to indicate successful receipt of the message and queueing for further processing). By best practice, the Endpoint SHOULD send back successful responses with an empty body.

An Endpoint MAY send back responses other than those with 2xx class indicating success; if so, it MUST adhere to these response status codes for these specific cases (for other cases, the Endpoint may offer other responses):

• If the request message has no enclosing Caliper Envelope, reply with a 400 Bad Request status code.
• If the request message's Caliper Envelope is malformed (for example, missing fields required by the Envelop's version), reply with a 400 Bad Request status code.
• If the Sensor sends an unauthorized request, or the Endpoint is unable to validate the authorization, or the Endpoint cannot determine that the Sensor has sufficient privilege to send such a message, reply with a 401 Unauthorized.
• If the request message has a content-type other than application/json, reply with a 415 Unsupported Media Type.
• If the Endpoint cannot support the version of Caliper data indicated by the Caliper Envelope's dataVersion field, reply with a 422 Unprocessable Entity status code.

The Endpoint MAY respond to Sensor messages with other standard HTTP status codes to indicate result dispositions that vary from the cases described above. The Endpoint MAY also communicate more detailed information about problem states, using the standard method for reporting problem details described in [RFC7807].

Caliper Endpoint implementers should bear in mind that some Caliper Sensor implementations may lack sophisticated error handling.

6.2 Configuration Information

Before sending Caliper data, a Sensor MAY choose to check the current status of an Endpoint using the standard GET request method, with the same restrictions on transport security and authorization as enforced when sending Caliper data.

• If an Endpoint receives this request alongside appropriate authorization, it MUST respond with a 200 OK status code. The body of a successful response MUST contain its configuration parameters in a JSON data structure.
• If the Sensor sends a message without an Authorization request header of the RECOMMENDED form or sends a token credential that the Endpoint is unable to either validate or determine has sufficient privileges to submit Caliper data, the Endpoint SHOULD reply with a 401 Unauthorized response.

A Sensor sending a ping request SHOULD interpret any status code besides 200 OK or 401 Unauthorized as the Endpoint indicating that its service is currently unavailable.

The properties of an Endpoint configuration are listed below. Each property MUST be included no more than once. No custom properties are permitted.

{
  "caliperMaximumPayloadSize": 512,
  "caliperSupportedVersions": [
    "http://purl.imsglobal.org/ctx/caliper/v1p1",
    "http://purl.imsglobal.org/ctx/caliper/v1p2"
  ],
  "caliperSupportedExtensions": {
    "endpointName": "Example Endpoint",
    "endpointVersion": "1.3.0"
  }
}

6.3 String Lengths and Storage

Certain Caliper data properties are expressed as strings of variable length. JSON-LD also defines a set of processing algorithms for transforming JSON-LD documents in ways that can change the length of keys and values that are expressed as IRIs, compact IRIs or Terms. Many implementers will choose to store each incoming Event and Entity describe received as a JSON-LD document or as a graph data structure consisting of nodes, edges and properties. Others may opt to normalize or "flatten" some or all of the nested JSON objects that comprise a Caliper Event or Entity. If the chosen persistence strategy involves normalizing Caliper semi-structured data, care should be taken to ensure that strings of character data can be stored without truncation.