xAPI Statement 101: Beyond The Basic Elements

22 June 2016 by Ryan Smith

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 utilised 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”

}]

}

So there you have it! If you’ve worked through this 101 series, you should now have a basic technical understanding of all the elements that make up a single xAPI Statement.

For more practical tips and advice about the xAPI, download our Technology Managers Guide to xAPI

blank
Ryan Smith
Software Development Team Lead

Starting as a placement student in 2014, Ryan re-joined the Learning Locker team after graduating from Oxford Brookes University where he won the John Birch prize for the highest grade average in the University.

From his minimalist desk, Ryan leads the Learning Locker team and consults with people on all things xAPI to conscientiously craft products and services that sustain and evolve training and performance.

When he’s not swimming or injuring himself on the cricket field, Ryan enjoys playing funny (and usually inappropriate) games with his family.

View more from Ryan Smith
blank
Read more about Learning Pool
Visit our Learn and Connect section

Get a free demo

Get in touch to find out how we can help

Start your learning journey

Get started by telling us what you need and one of our team will be in touch very soon.