By now you’ve probably learned that an xAPI statement stores better, more usable data than SCORM. When some people see the flexibility of xAPI, their first instinct is “store everything”. But that may not be the best idea if you want to have some analytics down the road. Maybe if you knew a bit more about the structure of an xAPI statement it might be easier to decide what to track. This is the first of a two part article describing the different components of an xAPI statement.
Author’s Note: This is bit of a technical article, but it is designed to show WHAT is available in an xAPI statement, not how to write xAPI statements. For xAPI geeks like myself in the audience, I am not covering every possibility with this article; it’s an introduction.
Introduction
When you turn the water on at a sink in your home, you don’t normally care much about the plumbing. You just expect water to show up at the faucet. Generally I encourage people NOT to think about xAPI and instead think of the results you want; xAPI is just plumbing. But if you are starting out on an xAPI project it is helpful to at least know what kind of data you can store. Then you can design your reporting tools and work backwards to the actual xAPI statements (hopefully handing that part off to a technical developer or programmer). This article is designed to help you determine what kind of data can be stored by xAPI.
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:
|
 |
There are other components to a statement, such as “Attachments”, that might be used in reporting, but in my opinion it is less common and beyond the scope of this article. I’ll save Attachments for a future “advanced” article on xAPI statements.
Finally, there are components that are more likely to be used 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.
Actors
| 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 LRS 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 if consistently for all your xAPI statements. If possible, adopt an agent naming method across your organization.
Verbs
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/exapi/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 Spanish speaking.
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 action was taken by the Actor. Using our sample statement again, “War and Peace” is the object in “Jon completed War and Peace”. An object can be one of the following:
|
 |
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 in part 2 of 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.
Summary
So we’ve covered the “big 3” parts of an xAPI statement (Actor, Verb and Object). In part 2 of this article we’ll cover Result and Context.
