Ask the Expert: How to write xAPI statements for quizzes and questions

     

Whether it’s from L&D vendors or organizations building custom e-learning courses or assessments, the xAPI statement question we’re asked most often is, “How do I design xAPI statements for quizzes and questions?”.

How to write xAPI statements for quiz questions

As you can imagine, quizzing is a type of learning experience that the xAPI specification authors had in mind when writing the specification, and it's seen many xAPI implementations. As a result, there's a well-worn path and clear expectations of how xAPI statements for quizzes should be structured. In particular, there are certain xAPI statement properties (in addition to the usual advice about implementing xAPI) that are important to include when sending statements about quiz questions. 

Context Properties

First, it’s important to ensure a learner’s response to a question can be tied to the quiz as a whole and to each attempt at the quiz. This is key because when you report on the data, you can look at a learner’s quiz attempts as a whole or at an individual quiz attempt. 

To link the question to a quiz (or assessment, test, observation etc.), include an activity representing the quiz within the context.contextActivities.parent property of the statement. This should be the same activity ID used in the object of the statement when recording interactions with the quiz as a whole (e.g., completion).

To link the question to other responses in the same attempt, use the context.registration property to record the same UUID for all statements relating to a particular attempt. For example, the context property of your statement might look like this:

 "context": {  
  "registration": "e168d6a3-46b2-4233-82e7-66b73a179727",  
  "contextActivities": {  
  "parent": [  
   {  
   "id": "http://id.tincanapi.com/activity/tincan-prototypes/golf-example",  
   "objectType": "Activity"  
   }  
  ]  
  }  
 }  

See the Context section of the xAPI specification for more details.

Interaction Activities

Be sure to use the activity definition properties specifically designed for statements about questions. The technical details are outlined in the Interaction Activities section of the xAPI specification with examples in the appendix.

Even though many of the properties are listed as “optional” in the specification, you should use them in your statements where you have relevant data. This includes listing the options for the questions as “Interaction Components,” which are lists of options, each with an ID and description. It’s generally best to use human-readable text for the IDs rather than random numbers. IDs also can include spaces and other special characters. These optional properties contain important data that users will want to see while viewing reports.

The exception to using human-readable text is when you use questions on a scale (e.g., “To what extent do you agree with…”). For these types of questions, it’s best to use a numerical ID representing the response’s position on the scale so you can perform calculations—such as the average response. For example, it’s not possible to calculate an average of “strongly agree” and “disagree”, but you can average 4 and 2. For this reason, you can use 4 as the ID for “strongly agree” and 2 as the ID for “disagree” so you can calculate the average response. (Note: Although the examples in the xAPI specification don’t follow this advice, it’s become a good practice for using xAPI in the real world.)

Here’s an example:

 "definition": {  
      "description": {  
           "en-US": "How awesome is Experience API?"  
      },  
      "type": "http://adlnet.gov/expapi/activities/cmi.interaction",  
      "interactionType": "likert",  
      "correctResponsesPattern": [  
           "3"  
      ],  
      "scale": [  
           {  
                "id": "0",   
                "description": {  
                     "en": "It's OK"  
                }  
           },  
           {  
                "id": "1",   
                "description": {  
                     "en": "It's Pretty Cool"  
                }  
           },  
           {  
                "id": "2",   
                "description": {  
                     "en": "It's Damn Cool"  
                }  
           },  
           {  
                "id": "3",   
                "description": {  
                     "en": "It's Gonna Change the World"  
                }  
           }  
      ]  
 }  

Always test your xAPI data.

Testing your data is important because, otherwise, you can end up collecting data that contains errors—which defeats all your hard work. Watershed’s activity report provides a great way to test your quiz and question data. If your report looks wrong, chances are there’s something wrong with your data. And be sure to visit our help site for a summary of these tips and some example xAPI statements.


Looking for more xAPI resources?

We've compiled some of our favorite xAPI-related guides and articles just for you! 

Check out these free xAPI resources and guides!


Andrew Downes

About The Author

As one of the authors of xAPI, Andrew Downes has years of expertise in data-driven learning design. And, with a background in instructional design and development, he’s well versed in creating learning experiences and platforms in both corporate and academic environments.