Writing a Simple Statement for xAPI

The Activity Statement is a critical part of xAPI. Without an Activity Statement, we have no record of what a learner has experienced. Previously we talked about almost everything you wanted to know about an activity statement.

What we didn’t talk about was exactly how to create one. It’s important to know that there are tools to help you do this. Most authoring tools will generate the code to create statements for you. Yet the benefit of knowing how to create a statement is that it will also help you to read a statement.

Hey, Someone Read a Book! Let’s Make an Activity Statement

The good news is that activity statements are, for the most part, just text. You could read one in a text editor or any similar type of application. But an activity statement also requires structure. That is provided through JSON. The acronym is short for JavaScript Object Notation. It’s made specifically for this type of thing – transacting data. It’s easy for humans to read and write but also easy for machines to read and parse.

Let’s see how a statement is put together by creating one for a particular activity. Here we have a student who has read a book titled Do Over by Jon Acuff. We want to create an activity statement that records them completing the book.

The three main parts of an activity statement is an Actor, Verb, and an Object. Each part of the statement deals with that. We will take them one by one and then look at the whole.


Here we identify the person who performed what we are recording. We need to use some unique identifier. The good news is that it can be as simple as an email address. In fact, it often is.

Optionally we can also include the actor’s actual name. We must also identify the type of actor. Usually this is either an “agent” meaning an individual or a group.

The brackets are part of the syntax for grouping content. Let’s focus on the descriptive text. The word actor in quotes is a string that identifies the section of the statement and the subset of data. The word mbox is the unique identifier; as we mentioned usually an email address and objectType identifies the type of actor. Therefore, the first part of the statement looks like this.

the actor section of a xAPI activity statement


There is basically only two parts typically used in the Verb section and only one of them is required. You must include the ID element. This element is expressed as a string value of a UUID (Universally Unique Identifier). And that value is usually a URI, like what you would put in your browser.

The question is, how do you know what to put in there? The idea is that the UUID directs to a place that provides metadata for the verb being used. While technically you can use any past-tense verb you want, the challenge is it has to be defined. Therefore, at least when you are starting out, you should use the established verbs that are already part of the xAPI specification.

Using a standardized verb makes this easy. ADL’s site has a URI for each verb and you can just include that. In our case the verb is completed. There isn’t one established yet for read.

The only other part of this is the plain language version of the verb. The display element identifies it as US English and the string value of the verb. As a result, the section looks like this.

the verb part of a xapi activity statement


We want to use three parts with the Object section. We want to identify the type of object we are acting upon. In many cases this will be an activity. But it could also be an agent or group, such as if we wanted to record that person A met with person B or joined group C. It could be a statement or a sub-statement.  We will go simple here and say that our actor completed reading the book Do Over by Jon Acuff. So for this our objectType will be “activity”.

With that in mind, we need an ID associated with the activity. That ID must be unique for that activity and must be a UUID which would ideally lead to a full identification of the activity. In our case, the UUID could be a URI to the book’s website or a page in our own domain describing it.

Finally, we need a definition. The definition will include a plain language name and description of the activity. With all of that, our Object section comes out thusly.

the object portion of a xapi activity statement

A Complete Activity Statement

So when we put it all together, it looks like this. That statement, once we send it, goes into a record in the Learning Record Store.

a complete simple activity statement for xapi

We can retrieve this record from the LRS through queries, depending on the type of LRS you have. And there you have it, we have recorded that our actor has completed the book.

Want to get started on the road to using Experience API or simply want to leverage SCORM more? Contact us today to see how we can help you at support@jcasolutions.com.

Share on facebook
Share on google
Share on twitter
Share on linkedin
Share on pinterest
Leave a reply

Your email address will not be published. Required fields are marked *

eLearning Learning