xAPI Statement 101: Beyond The Basic Elements
Most people have a basic understanding of how the xAPI works: Actor > Verb > Object, and maybe also Results and Context; but what else can you put into a statement?
In this post, I’ll highlight some of the other key elements, whether you should set them yourself or let the LRS handle it, and show you how the statement looks in practice.
Additional Elements To Use In Your xAPI Statements
There are a number of additional elements that can be utilized with an xAPI statement that we’ll be talking through in this post, namely:
- ID – a UUID, a unique identifier for the statement
- Timestamps – for when the activity took place and when it was recorded in the LRS
- Authority – the Agent/Group who sent the statement
- Version – the xAPI version that it conforms to
- Attachments – anything else included with the statement
ID
The UUID can be set yourself, and can be used elsewhere, without querying the LRS for it. You’ll find it looks something like this:
{
“id”: “8caba439-5455-485d-8c99-b3680ef8e46f”
}
You’ll get an error if you create an ID that already exists – so you must be aware of what else exists in the LRS.
Timestamps
There are two ISO timestamps properties in a statement.
- The “timestamp” property which represents the time that the experience took place; and
- The “stored” property which represents the time that the LRS stored the statement.
The “stored” property is set by the LRS, but you can set the “timestamp” property. If you don’t set the “timestamp” property, the LRS will set it to the same timestamp as the “stored” property. Both timestamp properties are displayed like this:
{
“timestamp”: “2016-05-27T13:06Z”
}
Authority
The Authority refers to the Agent/Group who sent the statement. This is usually set by the LRS using the credentials that were sent with the statement via Basic Authentication, etc. For example:
{
“authority”: {
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
}
Version
The version of the xAPI that the statement conforms to, which is set to the latest version by the LRS if you don’t set it. It will look something like this:
{
“version”: “1.0.3”
}
Attachments
Attachments might represent certificates or badges that have been sent with the statement to be stored in the LRS and look like this:
{
“attachments”: [{
usageType: “http://www.example.com“,
display: {},
description: {},
contentType: “application/json”,
length: 100,
sha2: “9cfe7faff7054298ca87557e15a10262de8d3eee77827417fbdfea1c41b9ec23”,
fileUrl: “https://www.example.com/files/123”
}]
}
A Complete xAPI Statement
So what does this all look like when put together in one activity statement? I hear you ask…
{
“actor”: {
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
},
“verb”: {
“id”: “https://adlnet.gov/expapi/verbs/completed”,
“display”: {
“en-GB”: “completed”
}
},
“object”: {
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/1”
},
“id”: “8caba439-5455-485d-8c99-b3680ef8e46f”,
“timestamp”: “2016-05-27T13:06Z”,
“stored”: “2016-05-27T13:06Z”,
“authority”: {
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
},
“attachments”: [{
“usageType”: “https://www.example.com”,
“display”: {},
“description”: {},
“contentType”: “application/json”,
“length”: 100,
“sha2”: “9cfe7faff7054298ca87557e15a10262de8d3eee77827417fbdfea1c41b9ec23”,
“fileUrl”: “https://www.example.com/files/123”
}]
}
Actor Element
If you’re just getting started with the xAPI, there are a few things that you need to know when setting up your learning record store (LRS), and in particular, how to set up basic xAPI statements using the Actor > Verb > Object triplet.
Next, we’ll be looking at the ‘Actor’ element – what it is, how it’s used and what correctly programmed statement anatomy looks like.
Understanding the Actor Element of an xAPI Statement
So, first things first – an actor can be one of two things: an Agent or a Group.
Agent Actors
Agents can be identified in 4 different ways:
- mbox
- mbox_sha1sum
- openid
- account
The mbox is basically the user’s email address. For example:
{
“objectType”: “Agent”,
“name”: “John Smith”,
“mbox”: “mailto:[email protected]”
}
mbox_sha1sum is an encrypted version of the email address. For example:
{
“objectType”: “Agent”,
“name”: “John Smith”,
“mbox_sha1sum”: “4445904ac65039ef7a91506207f19162ac4dea73”
}
The openid is the URL. For example:
{
“objectType”: “Agent”,
“name”: “John Smith”,
“openid”: “https://www.example.com/johnsmith”
}
The account element has both a name (which is like a user identifier) and a homepage which is usually the URL of the website that the activity is taking place on. For example:
{
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
}
Group Actors
Group actors can be either identified or anonymous.
As with agent actors, a group can also be identified by the above 4 elements – in which case it is an ‘Identified Group’. For example:
{
“objectType”: “Group”,
“name”: “HT2”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
“member”: []
}
Both group types can have members: if the group is not an ‘Identified Group’, it is an ‘Anonymous Group’ and must have at least 1 member. For example:
{
“objectType”: “Group”,
“name”: “HT2”,
“member”: [{
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
}]
}
An Example Actor Statement Summary
If you’re wondering what a complete Actor statement looks like, here it is:
{
“actor”: {
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
},
“verb”: {
“id”: “https://adlnet.gov/expapi/verbs/completed”,
“display”: {
“en-GB”: “completed”
}
},
“object”: {
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/1”
}
}
So to recap an actor can be one of two things: an Agent or a Group. You’re probably going to use an Agent for the most part. An Agent can be 4 different ways: mbox, mbox_sha1sum, openid, or an account; but we’d recommend using an account.
Next up, we’ll be taking a look at the Verb Element of an xAPI Statement.
Context Element
Having looked at the Actor, Verb, Object and Result elements of an xAPI statement, we now turn our attention to the Context – not of the Object, but context of the statement as a whole.
Understanding The Context Element of an xAPI Statement
The context consists of 9 elements that are all optional.
- Registration– an enrollment ID
- Instructor– the person who created the content
- Team– the group that you are a part of
- Context Activities
- Parent – e.g. nested activities (a level is part of a course)
- Grouping – e.g. a course is part of a qualification
- Category – e.g. a tag, e.g. xAPI course, that helps you group things together
- Other – anything else
- Revision– the revision of the activity or if there has been a previous version of the activity
- Platform– where it happened – e.g. Learning Pool Platform
- Language– what language it happened in
- Statement– a reference to another statement that is contextually relevant (NOT the Object Statement)
- Extensions– Not the Result or Object definition, this is more holistic to the whole activity
An Example Context Statement Summary
A complete Context statement that includes all elements may look something like this:
{
“actor”: {
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
},
“verb”: {
“id”: “https://adlnet.gov/expapi/verbs/completed”,
“display”: {
“en-GB”: “completed”
}
},
“object”: {
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/1”
},
“context”: {
“registration”: “957f56b7-1d34-4b01-9408-3ffeb2053b28”,
“instructor”: {
“objectType”: “Agent”,
“name”: “Joe Bloggs”
“account”: {
“name”: “321”,
“homePage”: “https://www.example.com/users/”
}
},
“team”: {
“objectType”: “Group”,
“name”: “HT2”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/groups/”
}
},
“contextActivities”: {
“parent”: [{
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/parent”
}],
“grouping”: [{
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/grouping”
}],
“category”: [{
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/category”
}],
“other”: [{
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/other”
}]
},
“revision”: “1.0.0”,
“platform”: “Example”,
“language”: “en-GB”,
“statement”: {
“objectType”: “StatementRef”,
“id”: “957f56b7-1d34-4b01-9408-3ffeb2053b28”
},
“extensions”: {
“https://www.example.com/ext”: true
}
}
}
As you can tell, if you include all of this data in your statement then it’s starting to get pretty long – but if you’re looking at really getting the most from your data, then there is one further element that we’ll look at – the results element.
Results Element
We’ve already talked about the Actor > Verb > Object triplet, but there can also be some other context derived from an xAPI statement as a such as the Result of the experience having occurred outside of those elements, and that’s what we’ll look at in this post.
Understanding The Result Element of an xAPI Statement
Result statements can include a number of optional details:
- Score
- scaled (a percentage between -1 and 1)
- raw (the actual score)
- min (minimum score achievable)
- max (the maximum score achievable)
- Success– Pass or Fail
- Completion– Yes or No
- Response– e.g. the actual comment/answer
- Duration– e.g. how long it took to complete the activity
- Extensions– e.g. more detail about the result
An Example Result Statement Summary
A complete Result statement set up correctly will look something like this:
{
“actor”: {
“objectType”: “Agent”,
“name”: “John Smith”,
“account”: {
“name”: “123”,
“homePage”: “https://www.example.com/users/”
}
},
“verb”: {
“id”: “https://adlnet.gov/expapi/verbs/completed”,
“display”: {
“en-GB”: “completed”
}
},
“object”: {
“objectType”: “Activity”,
“id”: “https://www.example.com/activities/1”
},
“result”: {
“score”: {
“scaled”: 1,
“min”: 0,
“max”: 100,
“raw”: 100
},
“success”: true,
“completion”: true,
“response”: “Example string”,
“duration”: “P1DT12H”,
“extensions”: {
“https://www.example.com/ext”: true
}
}
}
For more practical tips and advice about the xAPI, download our Technology Manager’s Guide to xAPI.
Got a learning problem to solve?
Get in touch to discover how we can help
