caliper

A Typescript implementation of the IMS Caliper specification

As a work-in-progress, this library is likely still in flux. Use it at your own risk.

Development

Clone the repository and run npm install to get started. The majority of the outstanding work is in defining entities, events, and implementing the profiles as tests.

Profile Tests

Tests should be written for the 10 Metric Profiles. Because the tests POST the events to IMS for validation, you will need the IMS_TEST_TOKEN environment variable set in order to successfully run the tests. To get a token, go to the IMS Caliper testing server (you'll need an IMS Global account) and set the "Bearer Token" value in your environment:

export IMS_TEST_TOKEN=<bearer_token>

Usage

The profile tests provide real-world examples of how to construct events. For instance, a ToolUse Event:

import Caliper from 'caliper';
 
// create the sensor and add a client endpoint
const sensor = new Caliper.Sensor();
sensor.createClient({
  baseURL: 'https://www.example.com/v1',
  headers: {
    Authorization: 'Bearer my-token',
    'Content-Type': 'application/json',
  },
});
 
// use factory methods to create the actor & object, and attach them to an event
// NOTE: the ToolUseEvent automatically applies the 'Used' action
const actor = Caliper.createEntity(Caliper.Entities.Person);
const object = Caliper.createEntity(Caliper.Entities.SoftwareApplication);
const event = Caliper.createEvent(Caliper.Events.ToolUseEvent, { actor, object });
 
// send the event (returns a Promise)
sensor.send(event);

Definition

Caliper has two major components that can be used to form an event, which takes the form of a triple (subject-predicate-object in RDF language and agent-action-object in Caliper):

• Entities: the nouns (action & object) in the Caliper event triple (e.g., Person or SoftwareApplication)
  • These are the core of the spec. They are objects with many properties.
• Actions: the verbs in the Caliper event (e.g., Used or NavigatedTo)
  • Actions are just single words and are easy to implement as a collection or enum.

These are used to compose Events, which require an actor, action, and object (e.g., Person Used SoftwareApplication).

Additionally, the spec defines a Sensor component that is used to transmit the events (POST to an endpoint) in a wrapper (Envelope).

Profiles & Certification

A Caliper profile defines a collection of one or more events that are related. Profiles are used for certification and organization only. For instance, the Assessment Profile simply contains the AssessmentEvent, AssessmentItemEvent, NavigationEvent, ViewEvent, meaning to receive the Assessment Profile certification, tool authors just need to emit those four events.

While IMS defines 10 default profiles in 1.1, we are allowed to define our own profiles if we feel that theirs don’t meet all of our needs.