1.1 Status of this Document

This document is considered the Final Release. This means that the Caliper Analytics® Sensor Certification Guide, version 1.2, is now made available as a public document following acceptance by 1EdTech member organizations, a number of whom have successfully achieved conformance certification at the time of the release of this document.

1EdTech strongly encourages its members and the greater public to provide feedback that focuses on improving the Caliper specification. To join the 1EdTech developer and conformance certification community focused on Caliper please visit https://www.imsglobal.org/activity/caliper.

Public comments and questions can be posted at the Caliper Analytics® public forum.

1.2 Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. A Sensor implementation 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 by implementers. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

2.1 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.

2.2 Certification Prerequisites

The following prerequisites MUST be met before your organization can begin the process of getting your product Caliper Analytics® certified.

• Your organization MUST be an 1EdTech Contributing or Affiliate Member.
• You MUST pass the tests using the Caliper Certification Service.
• The tests MUST be completed by a designated representative of the member organization and you MUST agree that there is no misrepresentation or manipulation of the results in the submitted report.
• You MUST submit your report via the Caliper Certification Service.

2.3 Conformance Testing Process

Visit the Caliper Certification service at https://www.imsglobal.org/sso/launch.php/caliper. You MUST be logged in to the 1EdTech website to access the Caliper certification service. If you do not have an account, please register at https://www.imsglobal.org/user/register.

The certification service provides a playground for testing your Caliper messages. Click the "Caliper Playground" link under Test Your Product to access the playground.

Once you are ready to commence certification testing, click the "Certify Your Product" link under Certify Your Product to commence testing. The following steps will guide you through the process. A screencast of the certification workflow is available for review.

1. Complete the online form by providing the following information:

   • Product name
   • Product version
   • Product URL
   • Product description
   • Caliper specification version
   • Member organization
   • Representative name
   • Representative email address
   • Information for who should be contacted about certification expiration

2. Click the green "Start Certification" button. To terminate testing click the white "Cancel" button.

3. An "Instructions" page provides both a test endpoint URL and a bearer token. Configure your software to send Caliper messages to the test endpoint URL. For each request, set the HTTP Authorization header field value to the provided bearer token, for example: Authorization: Bearer 16b33d7e-32ae-4c12-ba10-1a1f08a0d5d7 and the HTTP Host header field value to the provided endpoint URL.

4. Initiate the product test, sending messages to the certification service endpoint.

5. When the first message is received by the Certification service the "Instructions" page will be replaced with a view displaying conformance progress. A list of available Caliper metric profiles is displayed on the left side of the page. A log of submitted messages or "items" is displayed on the right side of the page. As messages are processed metric profile certifications that have been attained will be indicated by check marks. Clicking a profile's plus (+) link will display a list of profile events and actions processed successfully. Clicking the log "items" link provides additional information regarding events processed, errors encountered and individual message JSON-LD documents received.

6. Once testing is complete click the "Complete Certification" button.

7. Read the confirmation statement and then click the "Submit Certification Results" button.

8. Repeat the test as necessary in order to certify against additional metric profiles or address previous failed tests.

3.1 General Requirements

• Certain Event properties are required and MUST be specified. Required properties include: id, type, actor, action, object and eventTime.
• All other Event properties are considered optional and need not be referenced. Adherence to the rules associated with each required and/or optional property specified is mandatory.
• Each Entity participating in the Event MUST be expressed either as an object or as a string corresponding to the resource's IRI.
• The actions vocabulary is limited to the supported actions described in the Caliper Analytics® Specification, version 1.2, Actions Appendix, and no other.
• Serialized Events and Entities MUST conform to the syntactical requirements defined in the Caliper specification, and be contained within a Caliper Envelope using proper JSON-LD context and serialization

3.2 General Profile

The Caliper General Profile provides a generic Event for describing learning or supporting activities that have yet to be modeled by Caliper.

3.3 Annotation Profile

The Caliper Annotation Profile models activities related to the annotation of a DigitalResource.

3.4 Assessment Profile

The Caliper Assessment Profile models assessment-related activities including interactions with individual assessment items.

3.5 Assignable Profile

The Assignable Profile models activities associated with the assignment of digital content to a learner for completion according to specific criteria.

3.6 Feedback Profile

The Caliper Feedback Profile models providing feedback and comments on Entities.

3.7 Forum Profile

The Caliper Forum Profile models learners and others participating in online forum communities.

3.8 Grading Profile

The Caliper Grading Profile models grading activities performed by an Agent, typically a Person or a SoftwareApplication.

3.9 Media Profile

The Caliper Media Profile models interactions between learners and rich content such as audio, images and video.

3.10 Reading Profile

The Caliper Reading Profile models activities associated with navigating to and viewing digital textual content.

3.11 3.10 Resource Management Profile

The Caliper Resource Management Profile models a Person managing a DigitalResource

3.12 3.11 Search Profile

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.

3.13 3.12 Session Profile

The Caliper Session Profile models the creation and subsequent termination of a user session established by a Person interacting with a SoftwareApplication.

3.14 3.13 Survey Profile

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.

3.15 3.14 Tool launch Profile

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).

3.16 3.15 Tool Use Profile

The Caliper Tool Use Profile models an intended interaction between a user and a tool.

4.1 The Envelope

Caliper Event and Entity data are transmitted inside an Envelope, a JSON data structure that includes metadata about the emitting Sensor and the data payload. Each Event and Entity describe included in an envelope's data array MUST be expressed as a JSON-LD document.

For example Envelope JSON-LD see Caliper Analytics® Specification, version 1.2, Section 5.3.

4.2 HTTP Message Requests

Each HTTP request message sent to the certification service MUST consist of a single serialized JSON representation of a Caliper Envelope. Messages MUST be sent using the POST request method.

The following standard HTTP request headers MUST be set for each message sent to the certification service Endpoint:

4.3 HTTP Message Responses

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

• To signal a Caliper sensor that it has successfully received a message the certification service endpoint will reply with a 2xx class status code. The body of a successful response will be empty.
• If a Caliper sensor sends a message containing events and or entities without an enclosing Envelope, the certification service will reply with a 400 Bad Request response.
• If a Caliper sensor sends a malformed Caliper envelope (it does not contain sensor, sendTime, dataVersion and data properties of the required form), the certification service will reply with a 400 Bad Request response.
• If a Caliper sensor sends a message without an Authorization request header of the REQUIRED form or sends a token credential that the certification service is unable to either validate or determine has sufficient privileges to submit Caliper data, the certification service will reply with a 401 Unauthorized response.
• If a Caliper sensor sends a message with a Content-Type other than "application/json", the certification service will reply with a 415 Unsupported Media Type response.
• If a Caliper sensor sends a message with an Envelope that contains a dataVersion value that the endpoint cannot support the certification service will reply with a 422 Unprocessable Entity response.

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

4.4 Other Transport Protocols

Caliper Analytics® Specification, version 1.2 defines the use of a single transport protocol (HTTP/HTTPS). However, 1EdTech is interested in specifying the use of other transport protocols that can support the exchange of Caliper data. Organizations wishing to work with 1EdTech to add other transport protocols to the Caliper specification should contact the Caliper Working Group directly or indicate interest via the public forum.