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