Designing Your xAPI Data Strategy: xAPI-Statement Framework

When you use a faucet in your home, you don’t think much about the plumbing. You simply expect that running water will come from the faucet. Generally, I encourage people not to think about xAPI and instead think of the results you want—xAPI is just the plumbing.

If you are starting out on an xAPI project, it is helpful to at least know what kinds of data you can store. Then you can design your reporting tools and work backward to the actual xAPI statements (handing off that part to a technical developer or programmer if necessary). This article is designed to help you determine what kinds of data xAPI can store.

(Author’s note: This is a bit more of a technical article and is designed to show what is available in an xAPI statement, not how to write xAPI statements. For xAPI geeks like myself who are reading this, I am not covering every possibility with this article—it’s an introduction.)

Parts of an xAPI statement

At the highest level, these are the components of an xAPI statement that you are most likely to use as data in reporting:

• Actor
• Verb
• Object
• Result
• Context

There are other components to a statement—such as Attachments—that might be used in reporting, but in my opinion these are less common, and they are beyond the scope of this article. I’ll save Attachments for a future “advanced” article on xAPI statements.

Finally, there are components that you are more likely to use in filtering than in actual reporting, such as the time stamp of a statement (i.e., when a statement was generated). These are also beyond the scope of this article.

Actor

An actor can be either a person (John Doe) or a group (John Doe, Katy Person, and Tim Human). If we consider the xAPI statement “John completed War and Peace,” then the actor is John. Tip: When the actor is a person, it is called the “Agent.” Also, a group is either a collection of Agents or a group can be “anonymous.” An Actor is required for every statement.

Important considerations

If you want to get good reporting, it is important that you identify your Agents consistently. xAPI has several ways of identifying an Agent. Although some learning record stores (LRSs) have the ability to cleverly map the different identification methods to a single Agent, you should not count on it. Choose one Agent identification method and use it consistently for all your xAPI statements. If possible, adopt an agent-naming method across your organization.

Verb

The verb identifies the action of the Actor. In our sample statement of “John completed War and Peace,” the verb is “completed.” Well … sort of. xAPI actually uses a unique identifier for a verb, such as “http://adlnet.gov/expapi/verbs/completed.” In our example, “completed” is a “display value” for a verb. There could be multiple display values for the same verb, such as completó if the reader of the statement is a Spanish speaker.

xAPI allows you to create your own verbs. If you do so, remember that you need to create both the unique identifier and at least one display value, or your LRS might reject your statement.

Important considerations

While you can create your own verbs, your first instinct should be to use existing verbs. This will enable consistent reporting across systems. For example, ADL has a working group defining an xAPI vocabulary. There are also communities of practice that are defining xAPI vocabularies.

Object

The object is the thing on which the Actor took action. Using our sample statement again, War and Peace is the object in “John completed War and Peace.” An object can be one of the following:

• Activity—For example, in “John completed forklift training,” the object (forklift training) is an activity.
• Agent or Group—In the statement “John rated Bob,” the object is an Agent (Bob).
• A sub-statement or statement reference—For example, consider “Bob commented on ‘John completed War and Peace.’” In this case, the object is another statement: “John completed War and Peace.”

Activity object

Like verbs, Activities have a unique identifier. This identifier should never be used for two different activities. For example, the object War and Peace should not have the same identifier as the object To Kill A Mockingbird. Activities may also have a “definition.” The definition may include:

• Description—This is a language-specific description of the activity. It is possible to provide the description in more than one language.
• Type—Like verbs, you can make up your own activity types. But also like verbs, you should avoid creating new ones if at all possible. ADL also has some generally accepted activity types defined in the xAPI vocabulary.
• More information—This is a link to provide more information about the activity.
• Interactions—This is similar to the SCORM 2004 “cmi.interactions” properties. You can also make up your own interactions that you wish to track.
• Extensions—Many data objects in xAPI have an “extensions” area where you can add extra information. (I’ll talk more about extensions later in this article.)

Agent or Group object

This is basically the same as “Actor” (see above).

Statement Reference object

This is just a reference to another previously recorded xAPI statement.

Sub-Statement object

A single xAPI statement can include another complete xAPI statement as a sub-statement. Kind of strange, huh? According to the xAPI specification, “A common use case for Sub-Statements would be any experience that would be misleading as its own Statement.” (This is pretty technical, so that’s all I’m going to say about sub-statements.)

Result

The Result is an optional component of an xAPI statement. For example, in “Bob started test3,” there is no result. Bob started the test, but we don’t know yet how well he’ll do. Later, we might see the statement “Bob passed test3 with a score of 90.” Score is one of the properties of the Result object in an xAPI Statement. Let’s take a look at the other properties of a Result, all of which are optional.      

• Success—This is a true/false field indicating whether the Actor achieved success in the activity (see “Object” section earlier in this article).
• Completion—This is a true/false field indicating whether the Actor completed the activity.
• Response—This is the response given by the Actor to the activity. For example, if you write a statement about a test question, you could include the answer selected by the student.
• Duration—This is how long the student spent in the activity.
• Extensions—We’ll talk more about extensions later in this article.

Context

Context is another optional component of an xAPI Statement. In my opinion, however, it is one of the most valuable components of a statement. One of the great advantages of xAPI is that you can record information about activities and the context in which they occurred. For example, in the statement “Christie experienced the Great Wall in Second Life,” the Context is very important. If we left it out, you’d have “Christie experienced the Great Wall,” which is wildly different than the original statement. Without the Context, it looks like Christie went to China to see the Great Wall, as opposed to experiencing a simulated version of the Great Wall. 

Here are some of the other properties of Context. As with the Result, all the properties of Context are optional.

• registration—This is a unique identifier representing a student “enrolling” in a course or signing up for a learning event.
• instructor—This is an Agent object indicating the person (or persons) who instructed the activity (Object) of the statement.
• contextActivities—The explanation of this is a bit involved, so we’ll cover it below.
• revision—A revision number for the activity.
• platform—This is the platform used to experience the activity. For example, you could use “iPad” if the student performed the activity on an iPad.
• extensions—As noted previously, we’ll cover extensions later in this article.
• contextActivities—There are four types of contextActivities:

1. parent—Consider a course that consists of many modules. When statements are written about the modules, they can include the course identifier as the “parent” activity.
2. grouping—This is used to group activities together. For example, if you have several courses in a curriculum, you may use the “grouping” to identify the curriculum.
3. category—This is generally used to identify an xAPI profile, such as cmi5. A profile is a kind of recipe for using xAPI in a particular use case.
4. other—A catch-all for a context activity that does not fit with one of the other three.

Extensions

Activities, Results, and Context can all have Extensions. The purpose of Extensions is to provide a way to extend the data stored in an xAPI statement. Each extension must have a unique identifier and should include a data value. For example, in the cmi5 specification there is an extension for “masteryScore.” This is helpful in analyzing statements. If we see a cmi5 “Passed” statement, it is useful to know the passing score (masteryScore).

Important considerations

You should always try to use built-in properties of an xAPI statement before creating extensions. Otherwise, you may sacrifice the analytical abilities of your LRS. For example, if you created an extension for score instead of using the built-in score property of Result, your extension for score may not be included in reports.

Summary

We’ve examined the major framework of an xAPI Statement. Hopefully you’ve gained an understanding of the kinds of data you can store in an xAPI statement. This knowledge may be helpful in designing your xAPI data strategy.

September 19, 2016