Understanding xAPI Statements: Anatomy, Verbs, and Best Practices

In the world of data-driven eLearning, the Experience API (xAPI) is a powerful standard that enables deep insights into how learning happens across platforms. At the heart of xAPI lies the xAPI statement—a structured piece of data that tells the story of a learner’s interaction with content.

This article breaks down the anatomy of xAPI statements, explores common verbs, and shares best practices to help developers, instructional designers, and learning technologists implement xAPI the right way.

What is an xAPI Statement?

An xAPI statement is a JSON object that captures a learning experience. Think of it as a sentence: “Actor did Verb to Object.”

For example:

{
  "actor": {
    "name": "Jane Doe",
    "mbox": "mailto:jane@example.com"
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/completed",
    "display": { "en-US": "completed" }
  },
  "object": {
    "id": "http://example.com/elearning/course/intro-to-xapi",
    "definition": {
      "name": { "en-US": "Intro to xAPI" },
      "description": { "en-US": "A beginner course on xAPI." }
    },
    "objectType": "Activity"
  }
}

This statement means: Jane Doe completed the course “Intro to xAPI.”

Anatomy of an xAPI Statement

Let’s break down the core components of an xAPI statement:

1. Actor

Who performed the action? Usually a learner.

"actor": {
  "name": "John Smith",
  "mbox": "mailto:john@example.com"
}

• Common identifiers: mbox, mbox_sha1sum, openid, or an account object.
• Best Practice: Always use unique, consistent identifiers for users.

2. Verb

What action did the actor take?

"verb": {
  "id": "http://adlnet.gov/expapi/verbs/attempted",
  "display": { "en-US": "attempted" }
}

• The id is a URI that represents the verb.
• display is human-readable.
• Best Practice: Use standardized verbs when possible.

3. Object

What was the action performed on?

"object": {
  "id": "http://example.com/lesson1",
  "definition": {
    "name": { "en-US": "Lesson 1: Getting Started" },
    "description": { "en-US": "Introduction to basics of xAPI." }
  },
  "objectType": "Activity"
}

• The object can be a course, document, quiz, video, or even a real-world event.
• Best Practice: Use meaningful IDs that are globally unique and stable.

4. Optional Fields

• Result – Capture scores, success, completion, and more.
• Context – Provide additional data like platform, instructor, group, or parent activity.
• Timestamp – When the experience occurred.
• Authority – Who is asserting the statement (e.g., the LRS or system).
• Attachments – Additional files like certificates or recordings.

Example:

"result": {
  "score": { "scaled": 0.85 },
  "success": true,
  "completion": true
}

Common xAPI Verbs and Their Usage

Here are some of the most widely adopted verbs from the ADL xAPI Vocabulary:

Verb ID	Display	Use Case
http://adlnet.gov/expapi/verbs/launched	Launched	When a course or resource is opened
http://adlnet.gov/expapi/verbs/attempted	Attempted	When a user begins a quiz or task
http://adlnet.gov/expapi/verbs/completed	Completed	Finishing a module, activity, or course
http://adlnet.gov/expapi/verbs/passed	Passed	Scoring above the threshold in an assessment
http://adlnet.gov/expapi/verbs/failed	Failed	Not meeting minimum criteria
http://adlnet.gov/expapi/verbs/interacted	Interacted	Used for games, simulations, buttons, etc.
http://adlnet.gov/expapi/verbs/answered	Answered	Used in quiz questions and surveys

Tip: Always try to use verbs from trusted vocabularies like ADL, Rustici, or CASE Registry.

Best Practices for Writing xAPI Statements

• Follow a consistent structure across your learning ecosystem.
• Use globally unique identifiers for actors, objects, and verbs.
• Don’t overload the LRS with redundant or meaningless data.
• Avoid vague or custom verbs unless you define and document them properly.
• Leverage the context field to provide richer data for analysis.
• Use meaningful timestamps — always in ISO 8601 format (e.g., "2025-07-01T12:00:00Z").
• Test statements in tools like Postman or xapi.dev before pushing to production.
• Attach metadata where helpful, like score breakdowns or quiz attempts.
• Store all statements in a Learning Record Store (LRS) — essential for retrieval, reporting, and analysis.
• Document your implementation, especially for teams and future integration.

Final Thoughts

Understanding xAPI statements is the first step toward building smarter, data-rich eLearning ecosystems. Whether you're tracking course completions, video interactions, or real-world simulations, a well-structured xAPI statement ensures that every learning moment is measurable and meaningful.

As you scale your xAPI implementation, remember: clarity, consistency, and context are key.