DOCSEARCHbyAlgolia
Submit Docs

xAPI Specification (v1.0.3)

repository·master·Indexed 21 days ago

https://github.com/adlnet/xapi-spec

Documentation for the Experience API (xAPI) v1.0.3, a technical specification for describing learner experiences and activities between different learning technologies. It defines the Statement data model (Actor, Verb, Activity), the roles of Learning Record Stores (LRS), Providers (LRP), and Consumers (LRC), and the REST-based communication protocols using JSON serialization.

Tokens
29.8K
Snippets
41
Records
91
Agent score
76%

What's inside xAPI-Spec

  1. Understand the Experience API (xAPI) purpose and goals

    master

    The Experience API (xAPI) is a technical specification designed to document and communicate learning experiences. It provides a structured way to describe learning experiences and defines how these descriptions are exchanged electronically across different platforms and technologies.

    Core Goals:

    • Interoperability: Maximize the ability of services to create, gather, store, and process learning experience information.
    • Comparability: Make it easier to understand and compare learning outcomes recorded in diverse contexts.
    • Implementation Guidance: Provide a guide for developers building xAPI-conformant applications.
    • Conformance Testing: Provide criteria to test if an implementation adheres to the specification.

  2. Understand the xAPI specification structure

    master

    The xAPI specification is divided into three distinct parts to guide developers through implementation:

    1. Part One (Introduction): Provides background, high-level summaries, and guidance on how to interpret the document.
    2. Part Two (Data Model): Defines the data objects used in xAPI. The core object is the Statement, which includes properties like Actor, Verb, Object, Result, and Context. This part ensures consistent data structures across services.
    3. Part Three (Transfer Methods): Defines how information is communicated between services (e.g., Learning Record Stores (LRS), Learning Record Providers, and Learning Record Consumers). It follows REST architecture principles using HTTP requests and responses and defines security methods for trusted exchange.

  3. Understand the xAPI Specification structure

    master

    The xAPI (Experience API) is an interoperability specification for describing communication about learner activity and experiences between technologies. The specification is organized into three primary parts:

    • Part One: About the Experience API - High-level overview and concepts.
    • Part Two: Experience API Data - Details regarding the data structures used.
    • Part Three: Data Processing, Validation, and Security - Details regarding communication, security, and how data should be processed and validated.

  4. Understand Statement immutability and exceptions

    master

    Statements in xAPI are intended to be permanent and immutable. They cannot be changed once issued; the only way to invalidate a Statement is to void it.

    Immutability Exceptions

    The following are NOT considered changes to the Statement itself and do not violate immutability:

    • LRS-assigned properties: Properties like id, authority, stored, timestamp, and version assigned during processing.
    • Referenced Content: Changes to the content of an Activity Definition or the display property of a Verb referenced by a Statement do not change the Statement itself.
    • Timestamp Serialization: The timestamp and stored properties can be returned in different timezones as long as the point in time remains the same.
    • Unordered Lists: The order of Agents in a Group is not considered an ordered list; an LRS may return them in any order.
    • Attachments: Attachments are not part of the Statement and may be omitted by an LRS during retrieval.
    • Case Sensitivity: Changes in case for case-insensitive properties (e.g., the domain part of an email) do not affect immutability.

    Important Note on Result Duration

    Result Duration is treated as a string for comparison purposes. Because of the complexity of converting between time units and timezones, it is not considered an exception to immutability.

  5. Format Language Maps using RFC 5646

    master

    A language map is a dictionary used to provide text in multiple languages. The key is an RFC 5646 Language Tag and the value is a plain text string in that language.

    Best Practices:

    • Completeness: Populate the map as fully as possible for all known languages for a given string.
    • Tag Selection: Use the shortest valid language code. Use ISO 639 (e.g., es) for basic languages and ISO 3166-1 (e.g., es-MX) for specific regions. If the region is unknown, do not guess; use the top-level tag (e.g., en instead of en-US).
    • Chinese Languages: Because of high linguistic diversity, the zh code is often insufficient.
    • Content Type: Strings are plain text. Formatting like HTML or Markdown will be displayed as literal code unless the owner of an extension IRI explicitly states otherwise.

  6. Use Profiles and Vocabularies for specialized use cases

    master

    While xAPI defines the structure of Statements, it is flexible regarding content (e.g., any URI can be used as a verb). To prevent fragmentation and ensure interoperability, Communities of Practice (CoPs) should define:

    • Vocabularies: Unique identifiers and metadata for Verbs, Activity types, and contextual relationships.
    • Profiles: A set of rules and vocabularies implemented alongside xAPI for a specific use case (e.g., the cmi5 profile).

    Best Practice: When implementing a profile, it is recommended to use a unique category within a Statement's contextActivities to identify Statements that implement that specific profile.

  7. Understand the xAPI Data Flow and Components

    master

    xAPI operates through a network of specialized roles to track learning experiences:

    • Learning Record Provider (LRP): A trusted entity that tracks experiences on behalf of a learner. It is responsible for creating Learning Records and managing the relationship between the experience and the learner (e.g., launching content or managing digital rights).
    • Learning Record Store (LRS): The central repository that receives, stores, and makes Learning Records available to authorized clients.
    • Learning Record Consumer (LRC): A type of client that accesses and utilizes Learning Records from an LRS.
    • Client: Any entity that accesses the LRS.

  8. Use IRIs and UUIDs as identifiers

    master

    The specification utilizes two primary types of identifiers:

    1. IRIs (Internationalized Resource Identifiers): Used for unique, potentially resolvable identifiers. IRIs are preferred over URIs because they support characters outside the ASCII set, allowing for greater flexibility.
    2. UUIDs (Universally Unique Identifiers): 128-bit globally unique values. Unlike IRIs, they are not expected to be resolvable. UUIDs MUST be in the standard string form, and it is recommended to use variant 2 in RFC 4122.

  9. Identify the correct xAPI specification version

    master

    Note that this repository contains an older version of the specification (v1.0.3).

    • Current Version: xAPI 2.0 (IEEE standard).
    • Legacy Version: v1.0.3 (found in this repository).

    Ensure you are using the correct version for your implementation requirements.

  10. Types of Statement Objects

    master

    The object of an xAPI Statement can take several forms depending on the objectType:

    • Activity: An object with a definition (name, description, type).
    • Agent: An individual actor (name, mbox, openid, etc.).
    • Group: A collection of members (name, account, member list).
    • Statement: A reference to another statement (using objectType: "StatementRef").
    • SubStatement: A statement that contains another statement as its object.
    // Object is Activity
{
    "id": "http://www.example.co.uk/exampleactivity",
    "definition": {
        "name": { "en-US": "example activity" },
        "type": "http://www.example.co.uk/types/exampleactivitytype"
    },
    "objectType": "Activity"
}

// Object is Agent
{
    "name": "Andrew Downes",
    "mbox": "mailto:andrew@example.co.uk",
    "objectType": "Agent"
}

// Object is Group
{
    "name": "Example Group",
    "objectType": "Group",
    "member": [
        { "name": "Andrew Downes", "objectType": "Agent" }
    ]
}

// Object is Statement (SubStatement)
{
    "objectType": "SubStatement",
    "actor" : { "objectType": "Agent", "mbox":"mailto:agent@example.com" },
    "verb" : { "id":"http://example.com/confirmed" },
    "object": { "objectType":"StatementRef", "id" :"9e13cefd-53d3-4eac-b5ed-2cf6693903bb" }
}

  11. Signed Statements and JWS Headers

    master

    Signed Statements provide non-repudiation by including a digital signature. A signed statement typically includes an attachments array where the usageType is set to http://adlnet.gov/expapi/attachments/signature. The signature is often provided as a JWS (JSON Web Signature) which includes a header containing the algorithm (e.g., RS256) and the certificate chain (x5c).

    {
    "version": "1.0.0",
    "id": "33cff416-e331-4c9d-969e-5373a1756120",
    "actor": { "name": "Example Learner", "objectType": "Agent" },
    "verb": { "id": "http://adlnet.gov/expapi/verbs/experienced" },
    "object": { "id": "https://www.youtube.com/watch?v=xh4kIiH3Sm8", "objectType": "Activity" },
    "timestamp": "2013-04-01T12:00:00Z",
    "attachments": [
        {
            "usageType": "http://adlnet.gov/expapi/attachments/signature",
            "display": { "en-US": "Signature" },
            "contentType": "application/octet-stream"
        }
    ]
}

  12. Configure the authority property

    master

    The authority property identifies who or what asserted that the Statement is true (the authenticating user or system).

    Requirements:

    • Type: authority MUST be an Agent, except in 3-legged OAuth where it MUST be a Group containing two Agents (the application and the user).
    • LRS Responsibility: The LRS MUST ensure all stored Statements have an authority. The LRS SHOULD overwrite the authority based on the credentials used to send the Statement.
    • Direct Connection: If a user connects via HTTP Basic Authentication, the LRS MUST include the user as an Agent as the entire authority or as part of a Group.