Best Practices for xAPI Extensions
Activity, Context, and Result Extensions in xAPI Statements
Do you need to know when and how to best use Activity, Context or Result Extensions in your xAPI Statements? This is a common challenge and a frequently asked question we receive from both content developers and LRS data wranglers.
What are xAPI Extensions? In a nutshell, they let you add custom learning experience data to your xAPI statements, giving richer context beyond the core data model. You can read more about them in the
xAPI 2.0 IEEE Standard.
Here are some key things to know about xAPI Extensions:
- Extensions are user-defined (represented as JSON data)
- The Key (or property name) of an Extension must be an IRI
- The Value of Extensions can be any string value or JSON Object
- You can only use them in specific parts of an xAPI Statement:
- Activity (
object.definition.extensions) - Result (
result.extensions) - Context (
context.extensions)
Activity Extensions
What is an Activity Extension? The Activity Object Definition part of an xAPI Statement contains metadata about the Object. When used as part of the Activity Object Definition, the Extensions Object provides a way to extend xAPI Statements to include additional information about the activity (object).
For example, you may want to specify the type of assessment object (e.g., pretest, post-test, survey, quiz, etc.) used in an xAPI Statement to more easily query the data and build meaningful charts and dashboards showing a comparison of the pretest and post-test results. In the example below, the designer defined an “assessment-type” Activity Extension for the object. They set the property name for the extension to http://id.tincanapi.com/extension/assessment-type and set the value of the extension to post-test. Since they don't expect the value of this extension to ever change for this specific assessment object, then this is an ideal way to use an Activity Extension in an xAPI Statement.
Best Practice
Do not store dynamic values in Activity Extensions since you can expect that these values are static and don't change. The Veracity LRS does not add Activity Extensions to its canon for this reason.
Example
"object": {
"id": "https://example.com/activities/assessments/17923a7d-afee-22aa-c4ee-3333acac400",
"definition": {
"name": {"en": "IT Fundamentals Test"},
"description": {"en": "Assesses the learner’s knowledge of basic IT concepts and terminology."},
"type": "http://adlnet.gov/expapi/activities/assessment",
"extensions": {
"http://id.tincanapi.com/extension/assessment-type": "post-test"}}}
Context Extensions
What is a Context Extension? The Context part of an xAPI Statement contains additional information related to a learning experience or event. When used as part of the Context, the Extensions Object provides a way to extend xAPI Statements to include additional information about the broader learning experience or interaction that the Statement represents.
For example, the
xAPI Video Profile offers a “volume” Context Extension for representing the volume loudness in a video, or other media. This value changes (a floating-point value between 0 and 1) in each xAPI Statement since the student can change the volume when they play a video.
Best Practice
Do not store static values in Context Extensions since you can expect these values to change. The Veracity LRS does not add Context Extensions to its canon for this reason.
Example
"object": {
"objectType": "Activity",
"id": "https://www.youtube.com/watch?v=DoN0XDeSthg",
"definition": {
"name": {"en-US": "Video"},
"description": {"en-US": "An Introduction to xAPI Video"},
"type": "https://w3id.org/xapi/video/activity-type/video"}},
"context": {
"registration": "39be826d-9ff6-57f9-b429-99cb0c389267",
"contextActivities": {
"category": [{
"id": "https://w3id.org/xapi/video"}]},
"extensions": {
"https://w3id.org/xapi/video/extensions/volume": 0.5}}
Result Extensions
What is a Result Extension? The Result part of an xAPI Statement has additional information about some outcome (not necessarily a learning outcome). Imagine you want to track other types of results beyond what you typically associate with learning (e.g., completion, scores, pass/fail, etc.). You can also use Result Extensions to store this additional data.
For example, the
xAPI Video Profile offers a “time”
Result Extension for storing the specific time position in a video when the student interacted, paused, played, or terminated a video. This value changes in each xAPI Statement.
Best Practice
Do not store static values in Result Extensions since you can expect these to change based on interaction with the object. The Veracity LRS does not add Result Extensions to its canon for this reason.
Example
"object": {
"objectType": "Activity",
"id": "https://www.youtube.com/watch?v=DoN0XDeSthg",
"definition": {
"name": {"en-US": "Video"},
"description": {"en-US": "An Introduction to xAPI Video"},
"type": "https://w3id.org/xapi/video/activity-type/video"}},
"result": {
"extensions": {
"https://w3id.org/xapi/video/extensions/time": 0.144}}
Looking for more examples on using xAPI Extensions? Need to build reports, charts, or other dashboard visualizations over your custom data using xAPI Extensions? Check out these related video resources on YouTube:
- Using xAPI Extensions
- Building Reports with xAPI Extensions
- Building Graphs with xAPI Extensions
- xAPI Extensions: The Missing Key to the Extra Data You Need