LRS and CLR Record Mapping

Status: in-progress

Intent

Map internal person-centric learning history into:

• LRS-compatible xAPI statement stores
• CLR-compatible learner record exports

Record Philosophy

The platform keeps a durable internal record model and produces standards-aligned projections.

Projection design goals:

• Preserve provenance and temporal ordering
• Preserve portability of learner-relevant achievements
• Minimize irreversible information loss during transformation

System Boundaries

• Raw xAPI statements are stored in the dedicated LRS service and remain the system of record for standards-facing telemetry.
• Emergent application databases store projected read models, assignment state, evidence links, and export metadata.
• CLR exports are derived from the application record plus explicit provenance links back to raw statements where appropriate.
• Frontends query projections and platform APIs, not raw xAPI tables.
• The standards-facing LRS surface is not considered complete until the relevant upstream ADL conformance batteries are green in a disposable environment.

LRS Mapping Surface

Primary internal sources:

• Course-material launches and H5P progress
• Activity events around learning unit progression
• Assessment attempt lifecycle and scoring outcomes
• Qualification grant and revocation events

Projection requirements:

• Stable person actor mapping
• Context references to offering/container
• Result payload consistency with internal score semantics
• Durable linkage from projected progress rows back to accepted source statement ids

Raw Versus Projected Data Classes

Data class	Raw LRS	Platform projection	CLR export
Accepted xAPI statement payload	Yes	No	By reference only
Canonical agent/activity views	Yes	No	No
H5P material progress summary	No	Yes	Yes
Assessment attempt lifecycle	Optional by mapping	Yes	Yes
Competency evidence link	By reference	Yes	Yes
Qualification grant lifecycle	Optional by mapping	Yes	Yes
Attachment binary	Yes	No	By explicit export policy

CLR Mapping Surface

Primary internal sources:

• Person profile and identity references
• Qualification definitions and awards
• Achievement evidence pointers
• Full attempt-level outcomes and feedback history
• Competency evidence and competency-state history

CLR projection should clearly separate:

• Achievement claims
• Evidence references
• Issuer and validity metadata
• Standards provenance, especially when an achievement is backed by xAPI statements rather than direct transactional rows

H5P-Specific Record Policy

• H5P playback writes raw telemetry into the LRS.
• Emergent derives learner-facing progress from accepted statements into material progress projections.
• Teacher previews and admin validation sessions must not produce learner progress projections.
• When H5P evidence contributes to competency or qualification decisions, the projection must retain the source statement id and registration lineage.

Portability Guarantees

Portable record classes should include:

• Full person-linked assessment attempt history
• Full person-linked feedback history
• Person-linked progress evidence
• Person-linked competency evidence and state history
• Qualification grants with provenance
• Source statement references for records whose provenance is primarily xAPI-driven

Non-portable or conditionally portable classes should be documented explicitly when excluded.

Export/Import Architecture

• Export jobs produce versioned payload bundles with checksums
• Import jobs preserve source provenance and reconciliation logs
• Conflicts must be recorded, not silently overwritten
• Export jobs must distinguish embedded projection data from externally resolvable xAPI provenance references

Initial Projection Rules

• Raw statement retention lives in the LRS service, not in sync-facing application tables.
• Application projections should denormalize only the fields needed for learner UX, teacher visibility, evidence linking, and portable exports.
• A projection update must be replay-safe by source statement id.
• When later statements supersede earlier interpretation, the projection may change while the raw statement stream remains immutable.

Implementation Anchors

• Projection contracts and validation: packages/domain
• Export/import staging and audit tables: packages/db
• Export/import orchestration services: apps/api

Conformance and Reuse Policy

• Run the upstream ADL LRS Conformance Test Suite throughout development, not just at release time.
• Use subset runs to gate PR-sized LRS protocol slices and require full-suite success before declaring the LRS validated.
• The upstream suite is MIT licensed, so reusable fixtures, request builders, and assertion helpers may be adapted into repository TypeScript where that lowers spec risk.

Remaining Decisions

1. CLR profile granularity for the initial export bundle Resolved (clr-export-v1.md decision 1): one platform-transcript CLR per learner, bundling every granted award across all orgs, signed by the platform-default issuer; per-issuer subset CLRs deferred.
2. Whether xAPI statement excerpts should ever be embedded directly instead of linked by provenance id Resolved (ADR-0015): reference only, never embedded — signed credentials are un-erasable, so PII must not be frozen into them (ADR-0014).
3. Redaction policy for institution-private fields during portable exports Resolved for v1 (clr-export-v1.md decision 6): redaction by construction — the CLR exposes only the OB-projected achievement surface (claims, alignment, provenance references); no institution-private field enters the bundle. A configurable policy waits for a named private field a consumer needs conditionally included.