Designing Your xAPI Data Strategy: xAPI-Statement Framework

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

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

(Author’s note: This is a bit more of a technical article and isdesigned to show what is available inan xAPI statement, not how to writexAPI statements. For xAPI geeks like myself who are reading this, I am notcovering 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 thatyou 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 mightbe used in reporting, but in my opinion these are less common, and they arebeyond 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 infiltering 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 thisarticle.

Actor

An actor can be either a person (John Doe) or a group (John Doe, KatyPerson, 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 acollection of Agents or a group can be “anonymous.” An Actor is requiredfor every statement.

Important considerations

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

Verb

The verb identifies the action of the Actor. In our sample statement of“John completed War and Peace,” theverb is “completed.” Well … sort of. xAPI actually uses a unique identifier fora verb, such as “https://adlnet.gov/expapi/verbs/completed.” Inour example, “completed” is a “display value” for a verb. There could bemultiple 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 thatyou 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 touse existing verbs. This will enable consistent reporting across systems. Forexample, ADL has a working group defining an xAPI vocabulary. There are also communities of practice thatare defining xAPI vocabularies.

Object

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

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

Activity object

Like verbs, Activities have a unique identifier. This identifier shouldnever be used for two different activities. For example, the object War and Peace should not have the sameidentifier as the object To Kill AMockingbird. Activities may also have a “definition.” The definition mayinclude:

• Description—Thisis a language-specific description of the activity. It is possible to providethe description in more than one language.
• Type—Likeverbs, you can make up your own activity types. But also like verbs, you shouldavoid creating new ones if at all possible. ADL also has some generallyaccepted activity types defined in the xAPI vocabulary.
• More information—Thisis a link to provide more information about the activity.
• Interactions—Thisis similar to the SCORM 2004 “cmi.interactions” properties. You can also makeup your own interactions that you wish to track.
• Extensions—Manydata objects in xAPI have an “extensions” area where you can add extrainformation. (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 asub-statement. Kind of strange, huh? According to the xAPI specification, “Acommon use case for Sub-Statements would be any experience that would bemisleading as its own Statement.” (This is pretty technical, so that’s all I’mgoing 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’tknow yet how well he’ll do. Later, we might see the statement “Bob passed test3with a score of 90.” Score is one of the properties of the Result object in anxAPI Statement. Let’s take a look at the other properties of a Result, all ofwhich are optional.      

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

Context

Context is another optional component of an xAPI Statement. In myopinion, however, it is one of the most valuable components of a statement. Oneof the great advantages of xAPI is that you can record information aboutactivities and the context in which they occurred. For example, in thestatement “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 differentthan the original statement. Without the Context,it looks like Christie went to China to see the Great Wall, as opposed toexperiencing 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—Thisis a unique identifier representing a student “enrolling” in a course orsigning up for a learning event.
• instructor—Thisis an Agent object indicating the person (or persons) who instructed the activity(Object) of the statement.
• contextActivities—Theexplanation of this is a bit involved, so we’ll cover it below.
• revision—Arevision number for the activity.
• platform—Thisis the platform used to experience the activity. For example, you could use“iPad” if the student performed the activity on an iPad.
• extensions—Asnoted previously, we’ll cover extensions later in this article.
• contextActivities—Thereare four types of contextActivities:

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

Extensions

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

Important considerations

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

Summary