Anatomy of an xAPI Statement with Developer Examples

Most xAPI implementation failures do not look like failures at first. The payload validates. The LRS accepts it. The API call returns success. Everyone moves on. Then reporting starts, and the real problem appears: the data is technically valid but semantically weak. At that point, the issue is no longer transport. It is design.

That is the mindset shift developers need when moving into xAPI for developers work, especially when teams are also comparing xAPI vs cmi5 for launch, completion, and LMS interoperability. A statement is not just an event payload you push into a learning record store. It is also the evidence model your dashboards, rollups, audits, and learning analytics xAPI workflows will depend on later. The xAPI spec is deliberately flexible, which is powerful, but that flexibility moves responsibility onto your team. You now decide what “completed,” “attempt,” “question,” “course,” and “success” actually mean in machine-readable form. The spec gives you a structure. It does not give you good data automatically. The core statement model is defined in the xAPI data spec, where actor , verb , and object are the required foundation, but useful implementations rely heavily on fields like result , context , and timestamp as well. See the official data model here: xAPI Data Model.

This matters because many teams still approach xAPI with a SCORM-shaped instinct. They want the equivalent of “did the learner launch and complete?” xAPI can certainly represent that, but it can also represent much more. The catch is that the meaning must be modeled clearly. If you get statement anatomy wrong, the LRS becomes a storage layer for ambiguous events. If you get it right, the same statement stream becomes a reliable analytics layer. That difference matters in broader e-learning standards decisions too, especially when organizations are evaluating SCORM to xAPI migration, SCORM to cmi5, and the practical boundary between an LRS vs LMS.

🔍 The smallest valid statement is rarely the right one

At the specification level, the smallest meaningful xAPI statement only needs actor , verb , and object . That simplicity is one reason xAPI feels approachable. A learner did something to something. That is the core event. But a valid minimal statement is not the same as a useful production statement.

Consider this realistic minimal example:

Copy Code


{
"actor": {
"objectType": "Agent",
"account": {
"homePage": "https://lms.example.com",
"name": "user-12345"
}
},
"verb": {
"id": "http://adlnet.gov/expapi/verbs/launched",
"display": {
"en-US": "launched"
}
},
"object": {
"id": "https://content.example.com/courses/secure-coding/v2",
"definition": {
"name": {
"en-US": "Secure Coding"
},
"type": "http://adlnet.gov/expapi/activities/course"
},
"objectType": "Activity"
},
"timestamp": "2026-06-16T14:03:21Z"
}

This is valid and already better than many first attempts because it includes stable identity, a machine-readable verb IRI, a durable activity ID, and event time. But it still answers only a narrow question: who launched what, and when? It does not tell you whether this launch belonged to a first attempt or a retry. It does not tell you whether the course was launched directly or from inside a larger certification path. It does not tell you whether launch was followed by completion, failure, abandonment, or a network interruption.

A useful way to evaluate a statement is to ask what business questions it can answer without extra guesswork. This one supports a simple activity log. It does not support attempt analysis, completion funnels, or troubleshooting around session continuity. That gap is where many real xAPI projects stall. Teams prove they can send xAPI statements, but they have not yet designed evidence that downstream systems can trust.

Why this matters is simple. A statement accepted by the LRS proves ingestion. It does not prove that the data can support reporting, aggregation, or operational debugging. In practice, optional fields are often what turn event logs into evidence. The smallest valid statement is a good teaching tool. It is rarely the right contract for production.

🧠 How to read a statement like a developer

The fastest way to understand xAPI JSON is not to memorize the entire spec. It is to map each field to a reporting question. Read the statement in a fixed order. Start with the actor. Then inspect the verb IRI. Then inspect the object ID and definition. After that, move into result , context , and timestamp . Finally, separate authored fields from LRS-managed metadata such as stored and authority .

That reading order matters because developers regularly misinterpret the wrong fields. The classic example is treating verb.display as the event meaning. It is not. The meaning is in verb.id . The display map is presentation text for humans. If one app emits http://adlnet.gov/expapi/verbs/completed and another emits https://example.com/verbs/finished , they may both show “completed” on screen, but your downstream reporting sees two different events unless you normalize them manually.

The same pattern shows up in object design. Developers often look at definition.name first because it is readable. Reports, however, usually group by object.id . If that identifier changes between environments, versions, or deploys, the report fragments even when the visible label stays the same. Human-readable text helps people inspect a statement. Stable identifiers are what make systems interoperable.

This is why the statement is both an interoperability artifact and an analytics schema. The machine-readable identifiers are the contract. The visible labels are convenience. When that distinction is missed, reporting quietly drifts into inconsistency. The problem may stay hidden until a product manager asks for a completion rate across two tools and the numbers do not match.

If you want a quick way to inspect different statement shapes, the xAPI Statement Explorer and Statements 101 are useful companion references. They help make the field structure concrete, which is important because xAPI is easy to describe abstractly but much clearer when you trace real JSON.

👤 Actor, verb, and object are the semantic backbone

The first three fields are not just required. They define the meaning of the event. If these are inconsistent, no amount of downstream transformation fully repairs the data. Start with actor . In demos, people often use mbox because it is easy. In production, account is often safer because it gives you stable identity without leaking personal email addresses. A combination like account.homePage plus account.name can survive identity provider changes better than assuming one email format will remain permanent.

From a developer perspective, actor design is really an identity strategy question. You are choosing the key that future systems will use to join statements back to users, permissions, teams, and enrollments. If your actor identifier is unstable, merges and duplicates become unavoidable. If it exposes personal data, privacy and compliance concerns follow you into every export. Choosing a durable identifier early is boring work, but it is the kind of boring work that prevents expensive cleanup later.

Next comes the verb. This is where governance matters more than syntax. The IRI is the event contract. If your team casually invents new verbs for familiar actions, analytics fragmentation begins immediately. That is why xAPI profiles matter. They constrain what a valid event should look like for a use case and prevent every application team from naming the same thing differently. ADL’s guidance on profiles and statement templates is especially useful here because it bridges the gap between “valid xAPI” and “consistent xAPI.” See xAPI Profiles and the related xAPI Profiles repository.

Then comes the object. In many learning statements, the object is an Activity, and that is usually the right default. The key design choice is the object.id . It should be durable and stable. A course version identifier such as https://content.example.com/courses/secure-coding/v2 is useful. A launch URL with temporary query parameters is not. If your ID changes every deploy, every report that groups by activity breaks into duplicates. This matters because the object ID is often the join key between raw event data and business reporting.

A practical rule helps here: if the ID would change because of runtime state, session state, or delivery mechanics, it is probably the wrong ID. Query strings, signed URLs, CDN variants, and environment-specific paths all tend to leak implementation details into analytics. xAPI works best when the object ID represents the thing itself, not the temporary way the learner reached it.

This is also where the comparison of xAPI vs cmi5 becomes useful. In plain xAPI, you design these semantic contracts yourself. In cmi5 for developers scenarios, some expectations around launch, assignable units, completion flow, and LMS communication are more constrained. That can reduce ambiguity, but it also means understanding where xAPI flexibility ends and where cmi5 package behavior, xAPI launch rules, and LMS interoperability expectations begin.

📈 Result is where many teams either gain clarity or create noise

Once the backbone is solid, result tells you how the event went. This is where the difference between “something happened” and “something measurable happened” becomes clear. Developers often misuse result because they try to pack unrelated meanings into familiar fields. The most common mistake is using result.score for progress. That seems harmless until reporting treats video watch percentage as if it were an assessment grade.

The score object is for graded outcomes. If you know a normalized grade, use scaled . If you need raw points, include raw , min , and max where relevant. But if what you really mean is “the learner watched 80% of the video,” that belongs in a profile-defined extension, not in score . This distinction matters because analytics systems often assume score fields imply performance. Once progress data is mixed with assessment outcomes, dashboards become misleading.

Another subtle but important distinction is between result.success and result.completion . They are not synonyms. A learner can complete an activity without succeeding. That is normal in assessments, compliance tasks, and branching experiences. If you collapse the two into a single boolean, you lose the ability to answer basic quality questions later. This becomes even more important when xAPI data is mapped back into LMS-style dashboards, where SCORM-era expectations often assume a cleaner completion model than reality provides.

Duration also belongs here and is often undervalued. Time-on-task can matter operationally even when scores do not. A duration on a question or assessment item can support item analysis, detect friction, and identify outliers. That is not just reporting polish. It can influence product decisions and content revision priorities.

There is also a practical modeling question behind every result field: is this value intrinsic to the event, or are you trying to summarize a larger session? For example, an answered statement can carry the score for that question. A final assessment completion statement can carry the score for the whole assessment. Problems start when a team sends one event type but silently uses it to represent several reporting layers. Clear event boundaries keep your result data understandable.

This is one of the places where cmi5 for developers differs from plain xAPI in practice. A cmi5 AU often needs clearer completion and pass logic because rules like cmi5 moveOn and cmi5 masteryScore affect learner progression in the LMS. In xAPI alone, you can model rich result data for analytics. In cmi5, the same data may also feed launch lifecycle and completion behavior. That distinction matters when teams compare xAPI vs cmi5 only at the transport level and miss the impact on reporting and business rules.

🧪 A richer assessment example shows why context matters

Assessment statements are where xAPI structure starts to pay off because they support multiple reporting layers at once. Consider this example:

Copy Code



{
  “actor”: {
    “objectType”: “Agent”,
    “account”: {
      “homePage”: “https://lms.example.com”,
      “name”: “user-12345”
    }
  },
  “verb”: {
    “id”: “http://adlnet.gov/expapi/verbs/answered”,
    “display”: {
      “en-US”: “answered”
    }
  },
  “object”: {
    “id”: “https://content.example.com/questions/sql-injection/q1”,
    “definition”: {
      “name”: {
        “en-US”: “SQL Injection Question 1”
      },
      “type”: “http://adlnet.gov/expapi/activities/question”
    },
    “objectType”: “Activity”
  },
  “result”: {
    “response”: “B”,
    “success”: true,
    “completion”: true,
    “score”: {
      “raw”: 1,
      “min”: 0,
      “max”: 1,
      “scaled”: 1.0
    },
    “duration”: “PT18S”
  },
  “context”: {
    “registration”: “550e8400-e29b-41d4-a716-446655440000”,
    “contextActivities”: {
      “parent”: [
        {
          “id”: “https://content.example.com/assessments/sql-injection-basics”
        }
      ],
      “grouping”: [
        {
          “id”: “https://content.example.com/courses/secure-coding/v2”
        }
      ]
    }
  },
  “timestamp”: “2026-06-16T14:08:10Z”
}

This statement is useful because it supports more than one question. You can ask whether user-12345 answered question q1 correctly. You can also group answers by assessment via parent , by course via grouping , and by attempt via registration . Remove those fields, and the event may still be valid, but your rollups become much harder.

It also helps to read the example field by field. The actor identifies the learner in a stable way. The verb uses the standard answered IRI, which tells downstream systems what happened without relying on local wording. The object points to a single question, not to the full quiz, which means the event is granular enough for item-level analysis. In result , response captures what the learner chose, success tells you whether it was correct, completion confirms the interaction finished, and duration shows time spent on the item. Then context reconnects that low-level event to the assessment and course it belongs to.

This is exactly why context deserves more attention than it usually gets. It is not decorative metadata. It is where hierarchy, grouping, and attempt-level linkage live. In SCORM, some of this was implied by launch and runtime boundaries. In xAPI, you often have to model it explicitly. If you do not, reporting becomes what the original draft called log archaeology, which is a good phrase because that is exactly how it feels in production.

The deeper design choice is granularity. If you only send a final quiz score, you can answer pass-fail questions but not item analysis questions. If you send only item-level answers without higher-level context, you get detail but lose structure. The best implementations decide deliberately which events belong at which level and then connect them with context rather than forcing one statement to do every job.

That design discipline becomes even more important when you are building an xAPI data strategy that has to support analytics, migration from older standards, and future cmi5 conformance. Granular xAPI statements are useful on their own, but they become much more valuable when your event model can also support learning analytics xAPI use cases, LRS reporting, and the structured expectations of an assignable unit cmi5 package.

🕒 Timestamp, stored, and registration are not interchangeable

Three fields cause recurring confusion because they all seem related to time or session state: timestamp , stored , and context.registration . They solve different problems. timestamp is when the experience happened. stored is when the LRS persisted the statement. registration is the key that ties related statements together into the same attempt, session, or broader experience.

This distinction matters most when events are queued, batched, or sent from unstable networks. In browser-only happy paths, developers sometimes omit timestamp and never notice. Then mobile or offline use appears, statements arrive later, and chronology breaks. The LRS can fill in a timestamp if it is missing, but that fallback reflects ingestion time, not learner event time. At that point, reconstructing sequence becomes guesswork.

registration deserves the mental label “attempt key,” but with caution. The spec allows it to represent more than one narrow attempt. It can tie together a broader learning experience across multiple activities and is also useful with state management patterns such as bookmarking. That broader meaning is important because developers often hard-code a one-quiz-one-registration assumption, then later struggle when the reporting model needs to span a lesson, simulation, and assessment as a single experience.

A concrete example makes the difference clearer. Suppose a learner starts an assessment at 10:00, answers two questions while offline on a tablet, and the device syncs at 10:25. The correct timestamp values should still reflect 10:00 to 10:05 activity time. The LRS may record stored as 10:25. The same registration value should appear across all statements so your reports know they belong to one attempt. If you confuse these roles, your timeline, duration analysis, and attempt counts all drift out of alignment.

When your system eventually needs to answer, “What happened in this learner’s second attempt?” or “Which events belong to the same xAPI launch session?” this field becomes foundational. If you skipped it early, there is rarely a clean repair later. The same principle carries into cmi5 for developers work, where launch state and session continuity are more standardized even though the underlying xAPI statements still need careful modeling.

🗂️ Context activities are how you preserve structure

One of the most underused parts of xAPI is context.contextActivities . This is where you preserve hierarchy and grouping around an event. The spec constrains these relationships to keys like parent , grouping , category , and other . Used well, they let a low-level event still carry enough structure to support meaningful rollups.

Imagine a learner watching a video segment inside a lesson, inside a certification course. If the statement only identifies the video object, then every higher-level report has to infer context externally. If the statement includes a parent lesson and a grouping course, the event becomes immediately more useful. You are not just storing a click. You are storing where that click belongs in the learning architecture.

There is also a practical implementation detail here: LRSs return context activity values as arrays. Some systems may accept a single object on write, but you should model and test them as arrays yourself. That reduces surprises when you compare submitted JSON with stored JSON during debugging. It sounds small, but these mismatches are the kind of thing that waste hours because the statement is “basically the same” while your test assertions still fail.

Each context activity key answers a slightly different question. parent usually tells you the immediate container. A question belongs to an assessment. A page belongs to a lesson. grouping usually points to the broader collection that helps reports aggregate events at a higher level, such as a course or pathway. category is often used to indicate that a statement follows a particular profile or conceptual grouping. other exists for relationships that matter but do not fit the earlier buckets cleanly. Choosing carefully here matters because these keys shape how future teams interpret the relationship, not just how the current app emits it.

This matters beyond reporting. Strong context modeling is one of the ways xAPI remains understandable in mixed ecosystems, where events may come from multiple tools, content services, or external platforms. Without preserved structure, cross-system aggregation quickly becomes brittle. It also affects downstream decisions about LMS interoperability, LRS vs LMS responsibilities, and whether your architecture can support both open xAPI statements and more structured cmi5 package delivery.

⚠️ The common mistakes are semantic, not just syntactic

Developers often expect xAPI debugging to be about authentication, endpoints, or transport. Those issues happen, but many ingestion failures come from malformed data. The spec is strict about nulls outside extensions, wrong primitive types, invalid IRIs, wrong key casing, and unsupported top-level properties. When statements are hand-built in frontend code, these issues are common.

Still, the more expensive mistakes are usually semantic. Using a launch URL as object.id makes activity identity unstable. Using string values like "true" instead of boolean values like true causes rejections. Using stored as event time corrupts chronology. Reusing the same display word with different verb IRIs fragments analytics. Encoding progress inside score pollutes outcome reporting. None of these are abstract purity concerns. Each one eventually becomes a broken chart, a failed aggregation, or an audit dispute.

A developer-friendly way to think about these errors is that syntax bugs are visible early, while semantic bugs accumulate interest. A malformed statement gets rejected now. An ambiguous statement gets accepted now and becomes expensive later. The first kind is annoying. The second kind quietly damages trust in the data platform because different stakeholders start getting different answers from the same event stream.

If you are modernizing from SCORM-era assumptions, this is where the architectural shift becomes visible. In SCORM, a lot of semantics were baked into the runtime model. In xAPI, the event model is flexible, but your team must actively design the vocabulary and the shape of each statement. ADL’s overview of xAPI, cmi5, and profiles helps connect that broader architectural picture to implementation choices: Overview and Application of xAPI, cmi5, and xAPI Profiles.

This is also why conformance matters. Validation is not just about whether JSON is accepted by an endpoint. It is about whether your implementation behaves predictably across tools and platforms. Teams working through xAPI conformance testing often discover design issues that basic happy-path ingestion never reveals. The same is true for cmi5 conformance, where launch, package structure, and completion behavior need to align with the standard instead of only working inside one vendor stack.

🧭 From valid statements to reliable analytics

The real maturity step with xAPI is moving from ad hoc statements to governed statement shapes. That is where profiles and statement templates become practical rather than theoretical. A template can define what an “answered assessment item” statement must contain, which verb IRI is allowed, which activity type is expected, whether registration is required, and what extensions are valid. This creates a bridge between developer freedom and reporting consistency.

Why this matters is not just standards compliance. It changes team coordination. Product, engineering, data, and learning teams can align on what evidence they need before code ships. Instead of discovering six months later that one application logs “finished” while another logs “completed,” you define the contract up front. The statement becomes a stable interface, not an improvised payload.

That is also the best way to think about xAPI statement anatomy. Each field answers a question. actor answers who. verb.id answers what happened. object.id answers to what. result answers how it went. context.registration answers in which attempt or session. contextActivities.grouping answers in which course or pathway. timestamp answers when it happened. If those answers are inconsistent, your data is not really analytics-ready. It is just searchable.

The deeper lesson is slightly uncomfortable but useful: the LRS is rarely where xAPI quality is won. The decisive work happens earlier, when your team decides what counts as evidence and how that evidence should be shaped. Once you see that clearly, statement design stops feeling like JSON plumbing and starts looking like system architecture.

For teams comparing xAPI vs cmi5, that is the practical takeaway. xAPI gives you a flexible event model for rich evidence and learning analytics. cmi5 adds a defined packaging and launch contract for LMS-delivered content, including rules around the cmi5 package, assignable unit cmi5 structure, cmi5 moveOn behavior, and cmi5 masteryScore handling. Neither standard removes the need for careful data design. They simply solve different layers of the problem. Understanding that distinction is what makes SCORM to xAPI migration or SCORM to cmi5 decisions more strategic and less reactive.

If you want to test these choices in practice, tools such as ADL CATAPULT can help you inspect and validate xAPI statements during implementation. That kind of feedback loop matters because good statement design is easier to build early than to repair after years of inconsistent production data.

🔢 #3 of 15 | xAPI: The Data Era of Learning Standards