Statement Design
The main data structure used by xAPI to describe tracked experiences is called a statement. This structure is defined explicitly in the xAPI specification and explained for developers on the Statements 101 page. As a learning designer, you don’t need to know statements to the same level of detail as a developer, but you do need to understand the basics so that you can communicate with your developer effectively. You also need to know a process you can go through to design what data you want to track for each of your experiences.
Note that this tutorial assumes you’re creating a solution from scratch. If you’re using existing products that include xAPI tracking, those products will have already considered statement design so you may not need to.
What data do you need?
Your first step in designing statements is to figure out what data about the learning experiences you’re designing you’ll need to capture. This needs to be a detailed list of every piece of data you’ll capture about each learning experience. At this stage, don’t worry so much about how you will get the data or even if getting that data is possible; work out what you’ll need in an ideal world.
The following questions will help you to compile that list:
- What different experiences is your solution made of? Consider this at both a high level and a more granular level.
- What data do you need in order to generate reports required by your stakeholders?
- What data do you need in order to answer questions posed by your learning analytics?
- How will the learning experience adapt to the learner? What data do you need from other experiences to support this?
- What data do you need to inform the design of future similar experiences?
- What data do you currently collect and why? Do you still need that data?
How will you capture that data?
Once you’ve determined what data you want to collect, you need to plan out how you will get that data and figure out what’s feasible within your budget. There are a few different approaches to collect data about experiences and the most appropriate approach will vary for different experiences and different contexts:
- Embed xAPI tracking directly into the experience. This is normally the best approach for e-learning content and can be the best approach for tracking job performance via business systems you control.
- Use a connector application to pull data out of an existing system and translate it into a xAPI format. This is often the approach used for tracking software that you are not able to customize.
- Track an event related to the experience rather than the experience itself. For example you might track that somebody followed a link to a website rather than tracking the website itself.
- Enable the learner to self-report the experience, perhaps using a bookmarklet for websites or a mobile app for real world experiences. This is often the best approach for self-directed learning.
- Enable somebody else to report on the learner’s experiences and achievements, such as a manager, coach, colleague or customer. This is most appropriate when assessing real-world performance.
However you are tracking, there will be cost implications, and that cost will influence how you track. In some cases you may decide to go without a piece of data due to costs associated with obtaining it. Work with your technical team to figure out what is and isn’t feasible.
How will you structure the data?
Having determined what data to capture and how to capture it, you can now think about how that data will be structured as xAPI statements. Your developer will dive into the details of statements, but as a learning designer, you need to understand the high level basics. The table below outlines the structure of a xAPI statements and the considerations you need to think about as a designer.
| Element | Explanation | Considerations |
| Actor | An identity of the person who did the thing. People often have multiple identities e.g. personal and work email, Twitter etc. Only one is assigned to the experience. | Who is the person that the experience is about? See Who Did It? Is the actor a single person or a group? Which identity is most appropriate to use in this context? Are there any privacy issues? Will you need to associate multiple identifiers used to track different experiences? |
| Verb | The action being done by the actor. | Work with your developer to choose the most appropriate verb identifier. Will statements be displayed in multiple languages? If so, will verb translations be stored within statements or hosted elsewhere? |
| Object | The thing the actor is acting on. This is normally an activity, but can also be a person, group or even another statement. |
What information do you need to capture about the activity itself? How will you create the activity id and ensure it’s unique? See Get the activity ID right |
| Result | The outcome of the experience e.g. success, completion, score etc. | What does ‘result’ look like in the context of the experience you are tracking? Does it fit with the concept of pass/fail and complete/incomplete or do you need to track different data points using extensions? |
| Context | The context of the experience, e.g. the larger learning activity this formed a part of, any other related activities, the instructor or team, the platform and language used in the experience. | What information about the context of the experience needs to be captured? How does the concept of ‘attempts’ work in your learning solution? This may be represented within the context. |
| Authority | The person or group that asserts that the thing happened. The authority is set by the Learning Record Store based on the security credentials used. |
Authority allows you to mark the source of the data so you can make use of data from more and less reliable sources. Consider how the authority of data will be represented in reporting and analytics. |
| Timestamp | When the experience happened; not necessarily when the data was stored. | Will you need to store tracking data offline to be sent later? |
| Attachments | Files attached can be attached to the statement e.g. evidence of a learning activity. | Attachments can be useful, but consider data storage and performance implications. |
The table above gives you a very high level view of xAPI statements. To go further, read the Statements 101 or Statements deep dive resources for developers.
Recipes
Recipes are a way of structuring statements for a particular type of activity, such as watching a video, attending an event or completing a course. It’s really important that you follow recipes when designing your statements. Recipes are particularly important for developers working with xAPI, and designers need to have an understanding too. Read more about recipes here.