Back to Articles
    Teaching
    9 min read
    August 23, 2026

    How to Validate xAPI Statements Before Sending Them to an LRS

    By Milan KeldrowskiUpdated October 26, 2026

    Take a guitar practice app that sends every session to a Learning Record Store (LRS), the database that collects xAPI learning records. Its xAPI bugs usually show up as a 400 error from the LRS, and that is a bad place to find them. By then the fault could be in the statement, the encoding, the headers or the login layer, and the status code rarely says which. Meanwhile a week of students' practice minutes may be missing from the teacher's dashboard. If the app catches a broken statement before sending it, a one-line bug stays a one-line bug instead of becoming a support investigation.

    A 400 response is already too late

    Strictly, a 400 only says that something refused the request: the LRS, or a gateway or proxy in front of it. Teams that treat every 400 as an LRS problem often start looking in the wrong place. A typo in the endpoint path, a missing version header or a login layer returning the wrong code can all produce the same status.

    So check statements in the app before they reach the HTTP client, and test how the request is built separately from the LRS. You end up with evidence: good and deliberately broken test files, a validation report and a captured request. And bad learning data never reaches production. The running example here is a practice app or Moodle plugin that turns each guitar practice session into a statement: who practised, which exercise, at what tempo and for how long. The same checks help learning-platform teams and analytics owners find broken statements before network problems hide the cause. Choosing an LRS and the basics of xAPI are left to other guides.

    A statement can be valid JSON and invalid xAPI

    JSON parsing asks whether the text turns into a data structure. xAPI validation asks whether that structure is an allowed statement. A payload can pass JSON.parse() yet fail because an Agent lacks a valid identifier, a verb is relative, an Activity ID is not an IRI, or a supplied statement ID is not a UUID.

    Start with actor, verb, and object. Add the optional id, timestamp, result, and context only after this core passes. Otherwise extensions, language maps, registration values, and result scores create false leads.

    {
      "actor": {
        "objectType": "Agent",
        "mbox": "mailto:learner@example.org"
      },
      "verb": {
        "id": "http://adlnet.gov/expapi/verbs/completed"
      },
      "object": {
        "objectType": "Activity",
        "id": "https://learning.example.org/activities/module-1"
      }
    }
    

    Each identifier has a clear type. The mailbox identifies the learner and starts with mailto:. The verb and Activity IDs are absolute IRIs, which in practice means full web addresses. This example needs no statement ID, because an LRS can assign one when the statement is posted. These rules come from the xAPI specification maintained by the Advanced Distributed Learning Initiative, whose 2.0 version was published by IEEE as standard 9274.1.1-2023. Tie the validator to the version the app declares in the X-Experience-API-Version header. An LRS on version 1.0.3 and one on 2.0 can disagree about edge cases that each side thinks are obvious.

    For a practice log, the same core then grows a result and a context. Session length goes into result.duration as an ISO 8601 duration, so twelve minutes is PT12M. Whether the student held the target tempo fits result.success, a boolean. The tempo itself, say 80 bpm on a chord-change loop, has no built-in xAPI field, so it goes into an extension whose key is an absolute IRI on your own domain. Validate those parts only after the core passes, and give the extension key its own fixture: a bare key such as tempo is exactly the kind of near-miss the next section is about.

    Four short strings that break the contract

    If the valid core is the target, the quickest way to trust a validator is to watch it reject near-misses. This legal JSON should fail locally before any network request is created.

    {
      "id": "completion-17",
      "actor": {
        "objectType": "Agent",
        "mbox": "learner@example.org"
      },
      "verb": {
        "id": "completed"
      },
      "object": {
        "objectType": "Activity",
        "id": "/activities/module-1"
      }
    }
    

    completion-17 is a label, not a UUID; the mailbox lacks mailto:; completed is a label, not an absolute IRI; and /activities/module-1 is a relative browser path, not an xAPI Activity identifier on its own.

    A schema should reject missing fields, wrong JSON types, invalid shapes, and forbidden combinations, but it cannot be the only gate. Semantic rules must understand xAPI identifiers and object types: an Agent needs one valid inverse functional identifier, while an Activity needs an absolute IRI id.

    Separate the checks rather than returning one vague message:

    schema: actor, verb, and object have permitted shapes
    identifier: Agent mailbox starts with mailto:
    identifier: verb.id is an absolute IRI
    identifier: Activity.id is an absolute IRI
    identifier: statement.id, if supplied, parses as a UUID
    

    Do not treat a permissive URL check as identifier proof, because parsers may normalise input or accept forms your policy rejects. Use an IRI-aware parser or a well-tested library, then test the exact schemes and forms your product emits. Report the failing JSON path, such as verb.id, the failed rule, and the received value.

    Generate IDs with a UUID generator, retain them as strings, and validate with a UUID parser rather than a partial hand-written regular expression. Reject a missing ID only when the producer requires client-assigned IDs, since xAPI does not require one for every posted statement. Rejecting an absent optional field is a validator bug; the statement itself may be fine.

    Freeze the checks before wiring HTTP

    Turn these checks into a test suite that runs on every change. Testing without an LRS does not replace full integration tests. It simply proves, quickly, that the app built the right statement. A local suite should load fixtures, run schema and semantic checks, serialise accepted payloads, and assert that broken fixtures fail for the expected reason.

    Keep the valid fixture in source control beside a broken counterpart for each rule. One pair per rule is enough, because the point is to see regressions. If a refactor strips mailto: from an actor mapping, rejects_agent_mailbox_without_scheme catches it before a batch job is contaminated.

    The boundary is:

    1. Build a statement from product events or learning records.
    2. Validate structure, identifiers, and local business rules.
    3. Serialise only accepted statements; test headers, endpoint selection, and authorization with a stubbed HTTP server.

    The stub can assert valid JSON, a suitable Content-Type, and the xAPI version header expected by the target LRS while capturing the exact client bytes. It catches double-encoding, accidental array wrappers, wrong methods, and missing headers without exposing credentials or sending production test traffic.

    A local pass does not prove an LRS accepts every extension or profile-specific rule. It does prove the producer did not send a statement it could have rejected itself.

    Separate validation failures from request failures

    Once local checks pass, sort failures by layer. That stops you editing a valid statement to fix a network fault, or changing passwords to fix a broken body.

    Signal Likely layer First evidence to inspect
    Local fixture fails before serialisation Schema or semantic validation JSON path, identifier rule, object type
    HTTP client cannot connect or times out Network or endpoint configuration Resolved host, TLS, proxy, timeout logs
    401 or 403 response Authentication or authorization Credential scope, token expiry, auth header
    400 response after a local pass Request packaging or server-side validation Response body, headers, method, raw payload

    For a 400, compare the raw request with the known-good fixture. Check whether the client posted one statement or a batch, used the intended media type, included the X-Experience-API-Version header, or had its body rewritten by a proxy. Read the response body before retrying; the diagnostic detail varies, but a message or request identifier can narrow the search.

    A status code is a hint. A gateway can emit 400 before the LRS; an LRS can reject a structurally valid statement because a profile disallows an extension; and custom middleware can make authentication failures appear differently from 401 or 403. A captured request and a reproducible fixture are stronger evidence than status alone.

    For batch rejection, validate every member locally, then send the batch to a non-production endpoint if one is available. If it still fails, divide and retry halves until the offending statement or interaction emerges. Preserve statement order and request metadata, or the investigation can create a second defect.

    Count failures at the validator as well as the LRS

    A validator is only useful if its reports lead to fixes. Count results by rule and by the service that sent the statement. A basic pass rate is:

    Validation Pass Rate = Accepted Statements / Checked Statements

    It misleads if invalid records are dropped before counting. Pair it with the rejected-statement count, the failure category and the delay from event creation to detection. More verb.id failures after a release suggests a mapping change; more malformed UUIDs may indicate an import job using external reference IDs as statement IDs.

    Track the LRS rejection rate beside those measures:

    LRS Rejection Rate = Rejected Requests / Submitted Requests

    A falling rate does not prove the data got cleaner if the app quietly throws failures away. Here is a made-up week. A practice app with about 1,400 active students creates 10,000 session statements. The validator rejects 150, so the pass rate is 9,850 / 10,000 = 98.5%. The 9,850 good statements reach the LRS, and it rejects 12 of them: a rejection rate of 0.12%.

    Now suppose a new release makes the app drop anything that fails validation before counting it. Then a mapping bug starts producing 400 statements with a bad verb.id. The dashboard still shows 98.5% and 0.12%. Yet 4% of the week's practice sessions simply vanish from the analytics, and a teacher looking at a student's streak sees days that look skipped.

    So count statements when they are created, not when they are sent, because counting at sending hides exactly this. Raise an alert whenever created minus checked is above zero. Keep a limited, access-controlled error log with the validation path, the app version and a redacted payload. Never put raw learner identifiers or authorisation headers in ordinary logs.

    Growth exposes mismatched identifiers

    A small integration may have one way of naming learners, one set of activity addresses and one app sending data. Add a phone app for home practice, a Moodle course for lessons and a partner's tuner plugin, and each may name things slightly differently. A shared schema may accept them all, while the analytics splits one learner into several people or counts one exercise as several.

    Version the validators and test files together with the agreement between app and LRS. New extensions, changed activity addresses and new ways of naming learners all count as changes to that agreement. Keep testing old files where older apps still matter, and test broken input from every integration. A validator that only checks the happy path gives false comfort after the first partner feed.

    Keep the core xAPI checks separate from your own product rules, such as approved verbs, required context extensions or accepted activity domains. When something fails, you can then tell broken xAPI apart from valid xAPI that simply breaks your reporting rules.

    Reject malformed statements before transport

    When the next 400 arrives, skip the longer retry loop. Replay the captured payload through the fixture suite first. If a local rule fails, fix the producer at that boundary. If everything passes locally, the layer table above tells you where to look next.

    Clean syntax still does not guarantee meaningful learning data. Once the core suite is stable, give each of your own product rules a failing fixture as well, so a broken reporting rule never hides inside what looks like an xAPI error.

    Related Articles