Skip to content

Latest commit

 

History

History
1757 lines (1446 loc) · 103 KB

cmi5_spec.md

File metadata and controls

1757 lines (1446 loc) · 103 KB
Raw

cmi5 Specification Profile for xAPI

Table of Contents

Revision History

Contributors

License Agreement

Revision History

Versioning in the cmi5 specification is managed in the following manner:

  • Major Version – Stones (Sandstone, Quartz, etc.) – Major changes in functionality.
  • Minor Version – Editions (1st edition, 2nd edition, etc.) – Minor changes in functionality.
  • Errata – Minor corrections that do not affect functionality are not versioned. (See GitHub repository for specific revision history).

The versions of this specifcation are as follows:

Quartz - 1st Edition (June 1, 2016)

Sandstone - 1st Edition (May 15, 2015):

  • Developer release

Convert Working Draft to Markdown in GitHub (Feb 20, 2013):

  • Converted existing working draft to markdown format from Microsoft Word. All previous work from 2012 discarded.

Contributors

Name: Organization:
Ed Cohen AICC Infrastructure Subcommittee Chair
Aaron Silvers ADL
Jonathan Poltrack ADL
Andy Johnson ADL
Tom Creighton ADL
Nik Hruska ADL
Avron Barr The LETSI Foundation
Mike Rustici Rustici Software
Ben Clark Rustici Software
Megan Bowe Rustici Software
Andrew Downes Rustici Software
Brian J. Miller Rustici Software
Jacques Talvard Airbus
Bill McDonald Boeing
Ray Lowery Pratt & Whitney
Dennis Hall Learning Templates
John Kleeman Questionmark
Kris Rockwell Hybrid Learning Systems
Paul Roberts Questionmark
Christopher Reynolds Pelesys
Mingrui Zheng Pelesys
Chris Sawwa Meridian Knowledge Systems
Michael Roberts VTraining Room
Thomas Person (Formerly of Adobe)
Art Werkenthin RISC,Inc
Severin Neumann die eLearning AG
Chris Amyot ICOM Productions, Inc.
David Pesce Exputo Inc.
Henry Ryng inXsol
Chris Handorf Pearson
Jamie Burns Virtual College
Pankaj Agrawal Next Software Solutions

1.0 Overview

This specification describes interoperable runtime communication between Learning Management Systems (LMS) and Assignable Units (AU).

1.1 Scope

The scope of this specification is limited to the following:

  • Launch by an LMS of AUs.
  • Launch and runtime environment used by LMS and AUs.
  • Runtime communication data and data transport between the LMS and AUs.
  • LMS course definition as it pertains to runtime data used by AUs.
  • LMS Course Structure Import/Export.
  • Reporting requirements for the LMS.

This specification references how to use xAPI within this scope.

Other uses of xAPI are outside of this scope.

Uses of activities not explicitly defined above are outside of the scope of this specification.

1.2 Document Style Conventions

References to Statements

This document uses, as shorthand, specific vocabulary such as verbs in conjunction with the word "statement" (e.g., a "completed" statement). This shorthand refers to that statement meeting all requirements that would accompany the correct use of that concept. When using this shorthand with the word “the”, this means the cmi5 defined version of that statement with the verb’s display property. (see Section 7.1.3 Types of Statements for the definition of cmi5 defined)

For example:

the “completed” statement

Would be a cmi5 defined xAPI statement with a verb display name of ‘completed’ and a verb IRI of ‘http://adlnet.gov/expapi/verbs/completed’. Similar conventions might be used for other xAPI properties.

Style Conventions
This document uses the following style conventions:

  • Back Ticks ( ` ) – (rendered as "inline code depending on document rendering”) for all literal names of verbs and properties.
  • Double Quotes ( " ) for shorthand – the “completed” statement (as described in above).
  • Literal syntax case – for referring to verbs and properties the case will show as they appear in xAPI statements.
  • Section Titles with verbs/properties – may use either Capitalized or Literal syntax.

Style Usage examples

  • Back Ticks ( ` ) example. The ‘score’ property:
    for score when….

  • Double Quotes ( " ) example. The ‘completed‘ statement:
    the "completed" statement MUST

  • Literal syntax case example. The actor object with an object type of agent:
    The actor object with an objectType of Agent

  • Section Titles with verb example. See Section 9.3.1 Launched:
    9.3.1 Launched

  • Section Titles with properties example. See Section 9.5.4 Duration:
    9.5.4 Duration

2.0 References

The following referenced documents are indispensable for the application of this specification.

3.0 Definitions

For purposes of this specification, the following terms and definitions apply:

  • Administrator: The administrative user who manages the LMS and related systems. This user performs tasks such as learner enrollment, course structure definition, and report management.

  • Activity: In this specification it is representative of an AU or the Object of a statement with objectType of “Activity”. Thus the granularity can be anything from a single AU course down to a specific interaction.

  • Assignable Unit (AU): A learning content presentation launched from an LMS. The AU is the unit of tracking and management. The AU collects data on the learner and sends it to the LMS.

  • Block: A grouping of AU's and other Blocks (nesting).

  • Course: A collection of assignable units, in a logical grouping, of learning content. A course is typically an internal data structure. Courses are often assigned to learners and tracked by the LMS.

  • Course Structure: A list of assignable units and launch parameters, with an implied sequence, representing a course.

  • Experience API (xAPI): A runtime data communication specification for learning content (AU) to send and receive data to a Learning Record Store (LRS). xAPI is used to define the data transport and the data model.

  • Internationalized Resource Identifier (IRI): A unique identifier according to RFC 3987. The IRI might be an IRL. IRLs SHOULD be defined within a domain controlled by the person creating the IRL. Note that IRI’s in this spec MUST be fully qualified and not IRI References.

  • Internationalized Resource Locator (IRL): According to xAPI, an IRL is an IRI that, when translated into a URI (according to the IRI to URI rules), is a URL.

  • Learner: The end user viewing/using the learning content (AUs).

  • Learning Management System (LMS): A computer system that could include the capabilities to register learners, launch learning presentations, analyze and report learner performance, and track learners' progress. LMS launching, reporting, and tracking roles are the focus of the cmi5 specification. The LMS is integrated with an LRS. In the remainder of this document the term “LMS” refers to an integrated entity of LMS and LRS.

  • Learning Records Store (LRS): As defined in xAPI.

  • Registration: An enrollment instance of a learner in a course. (a registration ID uniquely identifies this). The registration ID persists throughout the course progress to completion and during review of a completed course. A new registration is created for new enrollment instances (such as recurrent courses or re-taking courses).

  • Publisher ID: A unique identifier for each AU and Block, and for the course instance in the Course Structure that is the identifier provided by the publisher to identify the course elements. The purpose of this ID is to identify the course elements not the publisher itself.

  • Session: A period of time marked by the launch of an AU until its termination (or abandonment).

3.1 Abbreviations and Acronyms

ADL: Advanced Distributed Learning
AICC: Aviation Industry Computer-Based Training Committee
API: Application Programming Interface
CMI: Computer Managed Instruction
JSON: JavaScript Object Notation
IRI: Internationalized Resource Identifier
IRL: Internationalized Resource Locator
LMS: Learning Management System
LRS: Learning Record Store
PII: Personally Identifiable Information
URI: Uniform Resource Identifier
URL: Uniform Resource Locator
URN: Uniform Resource Name
xAPI: Experience API
XML: Extensible Markup Language
XSD: XML Schema Definition

4.0 Conformance

Conformance to this specification is defined in this section.

In this specification:

  • "MUST" is to be interpreted as a requirement on an implementation.
  • "MUST NOT" is to be interpreted as a prohibition.
  • "SHOULD" is to be interpreted as a recommendation for implementation.
  • "SHOULD NOT" is to be interpreted as the converse of "SHOULD".
  • "MAY" is to be interpreted as a course of action that is permissible within the limits of the specification.

Uses of xAPI outside of the scope of this specification do not affect conformance with this specification.

4.1 Assignable Unit (AU)

See Section 7.0 AU Requirements. An Assignable Unit MUST conform to all requirements as specified in xAPI (see References).

4.2 Learning Management Systems (LMS)

See Section 6.0 LMS Requirements. The LMS MUST conform to all LRS requirements as specified in xAPI (see References).

The LMS MUST have an account which is able to retrieve all Resource data (from the Statement API, etc, including attachments and extensions) about another distinct user across multiple sessions for that user.

4.3 Optional JSON Values

If JSON properties are indicated as optional, you MAY leave such properties out of the JSON structure being described.

4.4 Courses

A course MUST be bundled with course structure data that conform to all requirements listed in Section 13.0 Course Structure Data Requirements and Section 14.0 Course Package.

Course structure data MUST NOT implement any features or functionality (optional or mandatory) described in this specification in a non-conforming manner.

5.0 Conceptual Model: Informative

Synopsis of the cmi5 model:

  • An LMS imports a course structure which contains at least one AU. Optionally, the course structure can include one or more blocks, which consist of 1 or more AUs or nested blocks.
  • An LMS administrative user assigns a course to a learner.
  • A learner authenticates with an LMS or a related system.
  • A learner launches an AU from the LMS or an associated launching system, using an interface.
  • The LMS writes launch data to the integrated LRS.
  • The AU sends a message to the LMS requesting launch parameters and previous state information.
  • Once the AU is fully initialized for learner viewing, it issues an "initialized" statement.
  • The learner views the AU content and performs the learning. During this time, the AU MAY request data from, and store data to, the LMS.
  • The learner exits the AU.
  • The AU reports the final tracking data to the LMS and issues a "terminated" statement.
  • Administrative users create and view reports of the tracking data recorded by the AUs for individual learners.

Responsibilities of the Assignable Unit:

  • Parse the parameters from the launching environment to determine where the LMS location is and initiate communication with the LMS.
  • Send an "initialized" statement indicating the AU is ready for learner viewing.
  • Acting as a client, send and receive messages using the defined transport mechanism(s) and associated commands as prescribed in this specification.
  • Format all data according to the defined data types and vocabularies that are defined in this specification.
  • Send a "terminated" statement prior to terminating the AU's execution.

Responsibilities of the LMS:

  • Create and maintain course structures.
  • Acting as a server, receive and reply to messages using the defined transport mechanism(s) and associated commands as prescribed in this specification.
  • Format all data according to the defined data types and vocabularies that are defined in this specification.
  • Launch the specified AU contained in the courses within the defined environment(s).

6.0 LMS Requirements

The LMS MUST:

  • Implement an LRS as defined in xAPI.
  • Implement additional State API requirements to initialize the AU state as defined in Section 10.0 xAPI State Data Model.
  • Implement the runtime launch interface as defined in Section 8.0 Content Launch Mechanisms.
  • Implement additional xAPI Statement API requirements as defined in Section 9.0 xAPI Statement Data Model .
  • Implement additional xAPI Agent Profile API requirements as defined in Section 11.0 xAPI Agent Profile Data Model.
  • Implement course handling as defined in Section 6.1 Course Handling Requirements.

6.1 Course Handling Requirements

  • The LMS SHOULD implement a means to create, edit, and maintain course structures.
  • The LMS MUST implement the import of the Course Structure defined in Section 13.0 Course Structure Data Requirements and the Course Package defined in Section 14.0 Course Package.
  • The LMS SHOULD implement the export of the course data structure defined in Section 13.0 Course Structure Data Requirements and the Course Package defined in Section 14.0 Course Package.
  • The LMS SHOULD provide a user interface to the LMS administrative users to create and edit course structures internally.
  • The LMS MUST support course structures containing more than 1000 AUs.
  • The LMS MUST support course structures conforming to the XSD schema defined in Section 14.0 Course Package.

6.2 LMS State API Requirements

The LMS MUST implement the State API Requirements as defined in Section 10.0 xAPI State Data Model.

6.3 LMS Statement API Requirements

The LMS MUST NOT provide permissions/credentials which allow the AU to issue voiding Statements.

The LMS SHOULD reject statements that conflict with the Statement API requirements as defined in Section 9.0 xAPI Statement Data Model.

The LMS MUST Void statements that are NOT rejected AND conflict with the Statement API requirements as defined in Section 9.0 xAPI Statement Data Model.

7.0 AU Requirements

An AU MUST:

  • Implement the runtime launch interface as defined in Section 8.0 Content Launch Mechanisms.
  • Implement runtime communication as defined in xAPI.
  • Implement State API requirements in this specification as defined in Section 10.0 xAPI State Data Model.
  • Implement Profile API requirements in this specification as defined in Section 11.0 xAPI Agent Profile Data Model.
  • Implement Statement API requirements as defined in Section 7.1 AU Statement API Requirements.

7.1 AU Statement API Requirements

7.1.1 First Statement API Call

The AU MUST issue a statement to the LRS after being launched, initialized, and ready for learner interaction using the "initialized" verb as described in Section 9.3.2 Initialized.

7.1.2 Last Statement Call

The AU MUST issue a "terminated" statement to the LRS as described in Section 9.3.8 Terminated as the last statement in a session.

Once the AU has determined that the session will end (e.g. by user action, timeout or some other means) the AU SHOULD issue a "terminated" statement.

7.1.3 Types of Statements

The statements issued within an AU session could fall within the following categories:

  • cmi5 defined - Statements using cmi5 defined verbs, category ID as defined in Section 9.6.2.1 cmi5 Category Activity, and context template.
  • cmi5 allowed - Statements using any verb and cmi5 context template (but NOT including cmi5 category ID as defined in Section 9.6.2.1 cmi5 Category Activity).
  • cmi5 not-allowed - Any statements not conforming with the cmi5 specification.

"cmi5 allowed" statements posted by the AU MUST occur between cmi5 statements using the "initialized" verb and the "terminated" verb. "cmi5 allowed" statements are not considered in "cmi5 defined" session management and satisfaction rules.

8.0 Content Launch Mechanisms

8.1 Launch Method

The AU MUST be launched by the LMS using one of the following methods, depending on the launchMethod in the Course Structure (Section 13.1.4 AU Meta Data, URL):

When the value of launchMethod is "OwnWindow", the LMS MUST use one of the following:

  • Spawning a new browser window for the AU.
  • Re-directing the existing browser window to the AU.

When the value of launchMethod is "AnyWindow", the LMS MUST choose the window context of the AU. All browser window options are acceptable - Frameset, New window, browser redirect, etc.

Regardless of the launchMethod the AU MUST be launched by the LMS with a URL having query string launch parameters as defined in this section. The launch parameters MUST be name/value pairs in a query string appended to the URL that launches the AU.

If the AU's URL requires a query string for other purposes, then the names MUST NOT collide with named parameters defined below.

The AU MUST have the ability to process the query string launch parameters in any order.

Each value for the associated names MUST be URL-encoded.

The format of the launching URL is as follows:

<URL to AU>
?endpoint=<URL to LMS Listener>
&fetch=<Fetch URL for the Authorization Token>
&actor=<Actor>
&registration=<Registration ID>
&activityId=<AU activity ID>

Example:

http://www.example.com/LA1/Start.html
?endpoint=http://lrs.example.com/lrslistener/
&fetch=http://lms.example.com/tokenGen.htm?k=2390289x0
&actor={"objectType": "Agent","account": 
{"homePage": "http://www.example.com","name": "1625378"}}
&registration=760e3480-ba55-4991-94b0-01820dbd23a2
&activityId=http://www.example.com/LA1/001/intro

(For readability the above example is not URL encoded.)

The values for the URL launch parameters are described below:

8.1.1 endpoint

Description:A URL to the LMS listener location for xAPI requests to be sent to.
LMS Usage:The LMS MUST place the endpoint in the query string.
AU Usage:The AU MUST get the endpoint value from the query string. The AU MUST use the endpoint value as the Base Endpoint for xAPI requests.
Data type:String (URL-encoded)
Value space:A URL-encoded URL
Sample value:https://example.com/my-cmi5-listener/

8.1.2 fetch

Description:The fetch URL is used by the AU to obtain an authorization token created and managed by the LMS. The authorization token is used by the AU being launched.
LMS Usage:The LMS MUST place the fetch in the Launch URL for use as defined in section 8.2.
AU Usage:The AU MUST get the fetch value from the query string for use as defined in section 8.2.
Data type:String (URL-encoded)
Value space:A URL-encoded URL
Sample value:http://lms.example.com/tokenGen.htm?k=2390289x0

8.1.3 actor

Description:A JSON object of objectType of Agent (as defined in xAPI) that identifies the learner launching the AU so the AU will be able to include it in xAPI requests.
LMS Usage:The LMS MUST populate the actor parameter in the query string based on the authenticated learner's identity conforming to Section 9.2 Actor. The LMS SHOULD create this parameter with an object that is specific to the LMS instance that does NOT include sensitive PII of the learner.
AU Usage:The AU MUST get the actor value from the query string. The AU MUST use the actor value in xAPI requests that require an actor property or that require an agent parameter.
Data type:String (URL-encoded)
Value space:A JSON object (as defined in Section 9.2 Actor)
Sample value:{"objectType": "Agent","account": {"homePage": "http://www.example.com","name": "1625378"}}

8.1.4 registration

Description:A Registration ID corresponding to the learner's enrollment for the AU being launched.
LMS Usage:The LMS MUST place the value for registration in the query string based on the authenticated learner's corresponding enrollment for the Course that the AU being launched is a member of.
AU Usage:The AU MUST get the registration value from the query string. The AU MUST use this registration value in xAPI requests that require aregistration.
Data type:String (URL-encoded)
Value space:UUID (as defined in xAPI)
Sample value:

8.1.5 activityId

Description:The Activity ID of the AU being launched.
LMS Usage:The LMS MUST generate a unique activityId for the AU. The LMS MUST place its value in the query string. The activityId generated MUST NOT match the AU's ID (publisher ID) from the course structure (See Section 13.1.4 - AU Metadata). The LMS MUST use the same generated activityId on all subsequent launches (for the same AU) within the same registration. The LMS SHOULD use the same generated activityId (for the same AU) for all registrations.
AU Usage:The AU MUST get the activityId value from the query string. The AU MUST use the activityId value as the ID property of the Object in all "cmi5 defined" statements.
Data type:String (URL-encoded)
Value space:IRI
Sample value:

8.2 Authorization Token Fetch URL

8.2.1 Overview

The LMS MUST include the fetch name/value pair in the launch URL. The AU MUST make an HTTP POST to the fetch URL to retrieve an authorization token. Note than an HTTP GET is not allowed in order to prevent caching of the request.

The fetch URL response MUST include an HTTP status code of "200" for a valid request (including one that generates error as described in Section 8.2.3 Errors). The response MUST have a Content-Type of "application/json". The response body MUST be a JSON structure. The structure MUST be an object with the property auth-token in the first successful response. An example JSON structure is shown below:

{
  "auth-token": "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
}

The AU MUST place the auth-token in the HTTP header, as defined in RFC 1945 - 11.1 Basic Authentication Scheme, in all subsequent xAPI communications with the LMS. The authorization token returned by the fetch URL MUST be limited to the duration of the session.

The AU SHOULD NOT attempt to retrieve the authorization token more than once. The fetch URL is a "one-time use" URL and subsequent uses SHOULD generate an error (see Section 8.2.3 Errors).

8.2.2 Definition: auth-token

auth-token
Description:An authorization token used in all xAPI communications with the LMS.
LMS Usage:The LMS MUST place the value for auth-token in a JSON structure, as shown in Section 8.2.1 Overview, in its response to a fetch URL request.
AU Usage:The AU MUST get the auth-token value using an HTTP POST to the fetch URL. The AU MUST then place the authorization token in the Authorization headers of all HTTP requests made to the endpoint using xAPI.
Data type:String (URL-encoded)
Value space:Defined by the LMS
Sample value:QWxhZGRpbjpvcGVuIHNlc2FtZQ==

8.2.3 Errors

8.2.3.1 Duplicate call to fetch URL

The fetch URL is a "one-time use" URL and MUST NOT return an authorization token more than once. Subsequent requests made to the fetch URL during the session SHOULD generate an error. An example JSON structure is shown below:

{
  "error-code": "1",
  "error-text": "The authorization token has already been returned."
}

8.2.3.2 Error Values

The following error-code values are allowed.

CodeMeaning
1Already in Use or Expired - Token has been used before or the AU session has expired
2General Security Error - All other security issues including invalid tokens
3General Application Error - Application or environment failures

The values for error-text are defined by the LMS.


8.3 Other Launch Environments

Other launch environments are not currently implemented in this specification. cmi5 implementations for LMS's and AU's in these other environments will use the same REST communication interface as specified in xAPI. xAPI does not specify launch mechanisms.

9.0 xAPI Statement Data Model

9.1 Statement ID

The AU MUST assign a statement id property in UUID format (as defined in xAPI) for all statements it issues.

9.2 Actor

The actor property MUST be defined by the LMS. Theactor property for all cmi5 defined statements MUST be of objectType agent. The Actor property MUST contain an account property as defined in xAPI.

9.3 Verbs

The following xAPI verbs are defined in this specification.

Note that cmi5 allowed statements are NOT subject to the usage rules in this section.

All statements in this section refer to cmi5 defined statements unless otherwise noted.

AUs MUST use the below verbs that are indicated as mandatory in other sections of this specification.

For all requirements listed below including language involving order, the order is determined by the value of the timestamp property.

AU Verb Ordering Rules within an AU session are as follows:

  • Verbs MUST NOT be duplicated (in cmi5 defined statements).
  • More than one of the set of {passed,failed} verbs MUST NOT be used (in cmi5 defined statements).
  • The initialized verb MUST be the first statement (cmi5 allowed or defined).
  • The terminated verb MUST be the last statement (cmi5 allowed or defined).

AU Verb Ordering Rules within a registration (per AU) are as follows:

  • Exactly zero or one "completed" cmi5 defined statement MUST be used per registration.
  • Exactly zero or one "passed" cmi5 defined statement MUST be used per registration.
  • A "failed" statement MUST NOT follow a "passed" statement (in cmi5 defined statements) per registration.

AUs MAY use additional verbs not listed in this specification.

The LMS MUST record and provide reporting for all "cmi5 defined" and "cmi5 allowed" statements that are not being rejected regardless of the verbs used in statements sent by AUs.

LMS verb ordering rules are as follows:

  • LMS MAY issue multiple "satisfied" statements (in a session).
  • LMS SHOULD NOT issue multiple "satisfied" statements per object (Block or Course) (in a registration).
  • LMS MUST NOT issue more than one "abandoned" statement for a session.
  • LMS MUST NOT issue more than one "waived" statement per session and MUST not issue more than one "waived" statement per registration per AU.

9.3.1 Launched

Verblaunched
IDhttp://adlnet.gov/expapi/verbs/launched
DescriptionThis verb indicates that the AU was launched by the LMS.
AU ObligationsNone
LMS ObligationsThe LMS MUST use this verb in a statement recorded in the LRS before launching an AU. (See Statement API, Section 10.0 xAPI State Data Model) The LMS MUST NOT issue multiple "launched" statements for the same AU within a given AU session.
UsageA "launched" statement is used to indicate that the LMS has launched the AU.

9.3.2 Initialized

Verbinitialized
IDhttp://adlnet.gov/expapi/verbs/initialized
DescriptionAn "initialized" statement is used by the AU to indicate that it has been fully initialized. The "initialized" statement MUST follow, within a reasonable period of time, the "launched" statement created by the LMS.
AU ObligationsThe AU MUST use initialized in the first statement (of any kind) in the AU session. The AU MUST NOT issue multiple "initialized" statements with for the same AU within a given AU session.
LMS ObligationsNone
UsageAn "initialized" statement is used by the AU to indicate that it has been fully initialized.

9.3.3 Completed

Verbcompleted
IDhttp://adlnet.gov/expapi/verbs/completed
DescriptionThe verb indicates the learner viewed or did all of the relevant activities in an AU presentation.
AU ObligationsThe AU MUST send a "completed" statement when the learner has experienced all relevant material in an AU. The AU MUST NOT issue multiple "completed" statements for the same AU within a given course registration for a given learner.
LMS ObligationsThe LMS MUST use "completed" statements based on the "moveOn" criteria for the AU as provided in the LMS Launch Data. (See Section 10.0 xAPI State Data Model – moveOn).
UsageThe criterion for progress towards completion is determined by the course designer. The use of this verb indicates progress of 100%.

9.3.4 Passed

Verbpassed
IDhttp://adlnet.gov/expapi/verbs/passed
DescriptionThe learner attempted and succeeded in a judged activity in the AU.
AU ObligationsThe AU MUST send a statement containing the "passed" verb when the learner has attempted and passed the AU. If the "passed" statement contains a "scaled" score, the scaled value MUST be equal to or greater than the masteryScore indicated in the LMS Launch Data. (See Section 10.0 xAPI State Data Model – masteryScore). The AU MUST NOT issue multiple "passed" statements for the same AU within a given course registration for a given learner.
LMS ObligationsThe LMS MUST use "passed" statements based on the "moveOn" criteria for the AU as provided in the LMS Launch Data. (See Section 10.0 xAPI State Data Model – moveOn).
UsageThe criterion for passed is determined by the course designer.

9.3.5 Failed

VerbFailed
IDhttp://adlnet.gov/expapi/verbs/failed
DescriptionThe learner attempted and failed in a judged activity in the AU.
AU ObligationsThe AU MUST send a statement containing the "Failed" verb when the learner has attempted and failed the AU. If the "Failed" statement contains a (scaled) score, the (scaled) score MUST be less than the "masteryScore" indicated in the LMS.LaunchData document. (See Section 10.0 xAPI State Data Model – masteryScore).
LMS ObligationsNone.
UsageThe criterion for "Failed" is determined by the course designer.

9.3.6 Abandoned

VerbAbandoned
IDhttps://w3id.org/xapi/adl/verbs/abandoned
DescriptionThe verb "Abandoned" indicates that the AU session was abnormally terminated by a learner's action (or due to a system failure).
AU ObligationsNone
LMS ObligationsIf an LMS launches an AU with the same registration as an active session, the previous session with that registration MUST be abandoned. The LMS MUST record an "Abandoned" statement on behalf of the AU indicating an abnormal session termination. The LMS MUST NOT allow any statements to be recorded for a session after recording an "Abandoned" statement.
UsageSee LMS obligations.

9.3.7 Waived

VerbWaived
IDhttps://w3id.org/xapi/adl/verbs/waived
DescriptionThe verb "Waived" indicates that the LMS has determined that the AU requirements were met by means other than the moveOn criteria being met.
AU ObligationsNone
LMS ObligationsThe LMS MUST use this verb in a statement recorded in the LRS when it determines that the AU MAY be waived. A statement containing a "Waived" verb MUST include a "reason" in the extension property of the Statement Result. (See Section 9.5.5.2 reason) The LMS MUST generate a unique session ID for the statement containing a "Waived" verb and MUST NOT issue any other statements (except for statements with the "Satisfied" verb) using that session ID. The LMS MUST NOT issue multiple statements with "Waived" for the same AU within a course registration.
UsageA "Waived" statement is used by the LMS to indicate that the AU can be skipped by the learner.

9.3.8 Terminated

VerbTerminated
IDhttp://adlnet.gov/expapi/verbs/terminated
DescriptionThe verb "Terminated" indicates that the AU was terminated by the Learner and that the AU will not be sending any more statements for the launch session.
AU ObligationsThe AU MUST send a statement containing the "Terminated" verb. This statement MUST be the last statement (of any kind) sent by the AU in a session.
LMS ObligationsThe LMS MUST use the "Terminated" statement to determine that the AU session has ended. Upon receiving a "Terminated" statement, the LMS MUST wait a specified period of time (defined by the LMS implementation) after which it MUST reject statements (of any kind) for the AU session.
UsageSee obligations.

9.3.9 Satisfied

VerbSatisfied
IDhttps://w3id.org/xapi/adl/verbs/satisfied
DescriptionThe verb "Satisfied" indicates that the LMS has determined that the Learner has met the moveOn criteria of all AU's in a block or has met the moveOn criteria for all AU's in the course.
AU ObligationsNone
LMS Obligations The LMS MUST consider that an AU that was previously issued a “Waived” statement by the LMS to have met the moveOn criteria for that AU. The LMS MUST use the "Satisfied" statement when the learner has met the moveOn criteria of all AU's in a block. In this statement the LMS MUST use the block object per Section 9.4 Object . The LMS MUST use the same block object for all Satisfied statements that refer to that block.

The LMS MUST also use the "Satisfied" statement when the learner has met the moveOn criteria for all AU's in a course. In this statement the LMS MUST use the course object per Section 9.4 Object. The LMS MUST use the same course object for all Satisfied statements that refer to that course.

The LMS MUST use the session ID from the AU launch for all "Satisfied" statements triggered as a result of an AU launch session.

The LMS MUST generate a unique session ID for all "Satisfied" statements triggered outside of an AU launch session.

The LMS SHOULD NOT issue multiple statements with "Satisfied" for the same Block or Course within a course registration for a given learner.
UsageSee LMS obligations.

9.4 Object

An Object MUST be present, as specified in this section, in all "cmi5 defined" statements.

Except for statements with the satisfied verb, the Object in a cmi5 defined statement represents the AU. When the Object is the AU, the value of the Object's id property for a given AU MUST match the activityId defined in the launch URL.

In "satisfied" statements, the Object represents a Block or Course. (see 9.3.9 - Satisfied)

The LMS MUST generate a unique ID for each block object. The generated block ID MUST NOT match the publisher’s ID from the course structure. The LMS block object MUST use https://w3id.org/xapi/cmi5/activitytype/block as the value of the objectType property in the Object's Definition.

The LMS MUST generate a unique ID for each course object. The generated course ID MUST NOT match the publisher’s ID from the course structure. The LMS course object MUST use https://w3id.org/xapi/cmi5/activitytype/course as the value of the objectType property in the Object's Definition.

9.5 Result

A Result MAY be present in a statement depending on the cmi5 verb used.

9.5.1 Score

A score MAY be reported. If a score is reported by an AU, the verb MUST be consistent with "masteryScore" (if defined for the AU in the LMS.LaunchData document).

The score property of the result object MAY be set in the following cmi5 defined statements:

  • passed
  • failed

cmi5 defined statements, other than passed or failed, MUST NOT include the score property.

The following are properties of the score object per xAPI:

  • scaled
    A decimal value between 0 and 1 (inclusive).
  • raw
    An integer value between the min and max properties (inclusive) of the score object. The AU MUST provide the min and max values for score object when the raw value is provided.
  • min
    An integer value indicating the minimum value for the score in the raw property.
  • max
    An integer value indicating the maximum value for the score in the raw property.

9.5.2 Success

The success property of the result MUST be set to true for the following cmi5 defined statements:

  • passed
  • waived

The success property of the result MUST be set to false for the following cmi5 defined statements:

  • failed

cmi5 defined statements, other than passed, waived or failed, MUST NOT include the success property.

9.5.3 Completion

The completion property of the result MUST be set to true for the following cmi5 defined statements:

  • completed
  • waived

cmi5 defined statements, other than completed or waived, MUST NOT include the completion property.

9.5.4 Duration

The duration property is an ISO 8601 formatted time value required in certain statements as defined in this section. Other cmi5 defined statements MAY include the duration property.

9.5.4.1 AU statements that include duration

Terminated Statement

The AU MUST include the duration property in "terminated" statements. The AU SHOULD calculate the duration for "terminated" statements as the time difference between the "initialized" statement and the "terminated" statement. The AU MAY use other methods to calculate the duration based on criteria determined by the AU.

Completed Statement

The AU MUST include the duration property in "completed" statements. The AU SHOULD calculate the duration as the time spent by the learner to achieve completion status.

Passed Statement

The AU MUST include the duration property in "passed" statements. The AU SHOULD calculate the duration as the time spent by the learner to attempt and succeed in a judged activity of the AU.

Failed Statement

The AU MUST include the duration property in "failed" statements. The AU SHOULD calculate the duration as the time spent by the learner to attempt and fail in a judged activity of the AU.

9.5.4.2 LMS statements that include duration

Abandoned Statement

The duration property MUST be included in "abandoned" statements. The LMS SHOULD use LMS specific methods (if available) to determine the duration if it has more accurate means of session time calculation than time stamp differences between statements. In the absence of such methods, the duration property MUST be set as the total session time, calculated as the time between the "launched" statement and the last statement (of any kind) issued by the AU.

9.5.5 Extensions

9.5.5.1 progress

ID:https://w3id.org/xapi/cmi5/result/extensions/progress
Description:An integer value between 0 and 100 (inclusive) indicating the completion of the AU as a percentage.
LMS Usage:None
AU Usage:The AU MAY set this value in statements to indicate level of completion. The AU SHOULD NOT set a progress value in a "completed" statement or if it has previously issued a "completed" statement for the AU in the current registration.
AU Obligation:Optional
LMS Obligation:None
Data type:Integer
Value space:0 to 100 (inclusive)

9.5.5.2 reason

ID:https://w3id.org/xapi/cmi5/result/extensions/reason
Description:Indicates the reason why an AU was waived (marked complete by an alternative means).
LMS Usage:The LMS MUST set this value in statements it makes with the "waived" verb. The value SHOULD be one of the following:
  • Tested Out – An Assessment was completed by the student to waive the AU.
  • Equivalent AU - The student successfully completed an equivalent AU (in the same course) to waive the AU.
  • Equivalent Outside Activity – The student successfully completed an equivalent activity outside of the course to waive the AU.
  • Administrative – The LMS administrative user marked the AU complete.
AU Usage:The AU MAY retrieve this value from the LRS and use it to change presentation behavior based on the reason.
AU Obligation:Optional
LMS Obligation:This is a required extension for LMS statements that include the "waived" verb.
Data type:String
Value space:Any string value
Sample value:Tested Out

9.6 Context

All cmi5 defined statements MUST contain a context that includes all properties as defined in this section. Either the LMS or the AU MAY provide additional properties.

9.6.1 registration

The value for the registration property used in the context object MUST be the value provided by the LMS. The LMS MUST generate this value and pass it to the AU via the launch URL. The LMS MUST evaluate moveOn criteria in the course structure at the time of registration. For example, AUs with moveOn criteria of NotApplicable in the course structure would be evaluated and could generate "satisfied" statements at this time.

9.6.2 contextActivities

The purpose of this property is to facilitate searches of the LRS by the LMS or other reporting systems. The contextActivities property contains list(s) of activity objects whose IDs can be used as a statement list filter. All cmi5 defined statements MUST include all properties and values defined in the contextActivities of the contextTemplate (see Section 10.0 xAPI State Data Model).

9.6.2.1 cmi5 Category Activity

An activity object with an id of https://w3id.org/xapi/cmi5/context/categories/cmi5 in the category list of the contextActivities object MUST be used in cmi5 defined statements as described in Section 7.1.3 Types of Statements.

9.6.2.2 moveOn Category Activity

cmi5 defined statements with a result object (Section 9.5 Result) that include either success or completion properties MUST have an activity object with an id of https://w3id.org/xapi/cmi5/context/categories/moveon in the category list of the contextActivities object. Other statements MUST NOT include this activity.

9.6.2.3 Publisher ID Grouping Activity

Used to identify statements about the course, block, or AU using the publisher ID from the course structure.

The LMS MUST include an activity object with an ID property whose value is the unaltered value of the AU's ID attribute from the course structure (See Section 13.1.4 AU Metadata – ID) in the grouping list of contextActivities in the contextTemplate object as described in the State API (See Section 10.0 xAPI State Data Model) prior to launching an AU.

The LMS MUST include the publisher ID activity in the grouping list of the contextActivities object for all cmi5 defined and cmi5 allowed statements it makes directly in the LRS.

9.6.3 Extensions

The following are extensions specified for cmi5. Statements MAY include extensions not specified here.

9.6.3.1 session ID

ID:https://w3id.org/xapi/cmi5/context/extensions/sessionid
Description:A unique identifier for a single AU launch session based on actor and course registration.
LMS Usage:The value for session ID MUST be generated by the LMS. The LMS MUST record the session ID in the State API (See Section 10.0 xAPI State Data Model) prior to launching an AU. The LMS MUST provide the session ID in the context as an extension for all cmi5 defined and cmi5 allowed statements it makes directly in the LRS.
AU Usage:An AU MUST include the session ID provided by the LMS in the context as an extension for all cmi5 defined and cmi5 allowed statements it makes directly in the LRS.
AU Obligation:Required
LMS Obligation:Required
Data type:String (URL-encoded)
Value space:string value
Sample value:

9.6.3.2 masteryScore

ID:https://w3id.org/xapi/cmi5/context/extensions/masteryscore
Description:masteryScore as provided in the LMS.LaunchData document for the AU and is used to determine the pass/fail result based on score.
LMS Usage:The LMS MUST add masteryScore to the context of a "launched" statement when it is provided in the LMS.LaunchData document.
AU Usage:An AU MUST include the masteryScore value provided by the LMS in the context as an extension for "passed" or "failed" statements it makes based on the masteryScore.
AU Obligation:Required, when present and evaluated
LMS Obligation:Required, when in launch data
Data type:decimal
Value space:Decimal value between 0 and 1 (inclusive) with up to 4 decimal places of precision
Sample value:0.92

9.6.3.3 launchMode

ID:https://w3id.org/xapi/cmi5/context/extensions/launchmode
Description:Indicates the launchMode that was used by the LMS to launch an AU.
LMS Usage:The LMS MUST add this extension to the context of a "launched" statement with the value from launchMode in the LMS.LaunchData document.
AU Usage:Not Applicable
AU Obligation:None
LMS Obligation:Required
Data type:string
Value space:Per launchMode vocabulary defined in Section 10.0 xAPI State Data Model
Sample value:"Normal"

9.6.3.4 launchURL

ID:https://w3id.org/xapi/cmi5/context/extensions/launchurl
Description:The URL used by the LMS to launch the AU.
LMS Usage:The LMS MUST put a fully qualified URL equivalent to the one that the LMS used to launch the AU without the name/value pairs included as defined in Section 8.1 Launch Method in the context extensions of the "launched" statement.
AU Usage:Not Applicable
AU Obligation:None
LMS Obligation:Required
Data type:string
Value space:URL
Sample value:http://www.example.com/LA1/Start.html

9.6.3.5 publisherId

This section is no longer applicable. See Section 9.6.2.3 Publisher ID Grouping Activity.

9.6.3.6 moveOn

ID:https://w3id.org/xapi/cmi5/context/extensions/moveon
Description:The moveOn value as provided in the LMS.LaunchData document for the AU.
LMS Usage:The LMS MUST add moveOn to the context of a "launched" statement.
AU Usage:Not Applicable
AU Obligation:None
LMS Obligation:Required
Data type:string
Value space:Per moveOn vocabulary defined in Section 10.0 xAPI State Data Model
Sample value:"Passed"

9.6.3.7 launchParameters

ID:https://w3id.org/xapi/cmi5/context/extensions/launchparameters
Description:launchParameters as provided in the LMS.LaunchData document for the AU.
LMS Usage:The LMS MUST add launchParameters to the context of a "launched" statement when it is provided in the LMS.LaunchData document.
AU Usage:Not Applicable
AU Obligation:None
LMS Obligation:Required, when present in the LMS.LaunchData document
Data type:String
Value space:Any string value

9.7 Timestamp

All statements MUST include a timestamp property per the xAPI specification to ensure statement ordering requirements are met. All timestamps MUST be recorded in UTC time. Timestamps are not required to be unique in statements within a session. The time recorded SHOULD indicate when the condition actually occurred.

10.0 xAPI State Data Model

10.1 Overview

Prior to launching an AU, the LMS MUST create or update a document in the State API record in the LRS. This MUST be a JSON document, as defined in this section.

State API PUT Properties:

  • activityId: Activity id for the AU. This MUST match the activity id used by the LMS at AU launch time.
  • agent: Agent representing the LMS learner being enrolled. This MUST match the actor property used by the LMS at AU launch time.
  • registration: Registration ID representing the LMS learner enrollment in the course. This MUST match the registration used by the LMS at AU launch time.
  • stateId: LMS.LaunchData

The properties for the LMS.LaunchData document are described below.

10.2 Document Properties

10.2.1 contextTemplate

Description:contextTemplate for the AU being launched.
LMS Required:Yes
AU Required:Yes
LMS Usage:The LMS MUST include a contextTemplate object and MUST include the following values:
  • The value for session id placed in an extensions object with the ID as defined in Section 9.6.3.1 session ID.
  • The publisher ID Activity as defined in Section 9.6.2.3 Publisher ID Grouping Activity in the contextActivities.grouping list.
The LMS MAY place additional values in the contextTemplate.
AU Usage:The AU MUST get the contextTemplate value from the LMS.LaunchData State document. The AU MUST NOT modify or delete the LMS.LaunchData State document. The AU MUST use the contextTemplate as a template for the context property in all xAPI statements it sends to the LMS. While the AU MAY include additional values in the context object of such statements, it MUST NOT overwrite any values provided in the contextTemplate. NOTE: this will include the session ID specified by the LMS.
Data Type:JSON context object as defined in xAPI.

10.2.2 launchMode

Description:The launch mode determined by the LMS. There are three possible values:
  • Normal
    Indicates to the AU that satisfaction-related data MUST be recorded in the LMS using xAPI statements.
  • Browse
    Indicates to the AU that satisfaction-related data MUST NOT be recorded in the LMS using xAPI statements. When Browse mode is used, the AU SHOULD provide a user experience that allows the user to "look around" without judgement.
  • Review
    Indicates to the AU that satisfaction-related data MUST NOT be recorded in the LMS using xAPI statements. When Review mode is used, the AU SHOULD provide a user experience that allows the user to "revisit/review" already completed material.
LMS Required:Yes
AU Required:Yes
LMS Usage:The LMS MUST include a value for launchMode.
AU Usage:The AU MUST conform to the following based on the value of launchMode
  • Normal
    The AU MUST send "Initialized" and "Terminated" verb statements. The AU MAY send other cmi5 defined statements per the requirements defined in Section 9.3 Verbs.
  • Browse
    The AU MUST send "Initialized" and "Terminated" verb statements. The AU MUST NOT send other cmi5 defined statements.
  • Review
    The AU MUST send "Initialized" and "Terminated" verb statements. The AU MUST NOT send other cmi5 defined statements.
Data Type:String
Value Space:"Normal", "Browse", or "Review"
Sample Value:"Normal"

10.2.3 launchParameters

Description:The launchParameters defined in the cmi5 Course Structure.
LMS Required:The LMS MUST include the launchParameters in the LMS.LaunchData State document if the launchParameters were defined by the course designer in the Course Structure.
AU Required:No
LMS Usage:The launchParameters value written in the LMS.LaunchData State document MAY be different than the one in the course structure (e.g. based on content vendor options that might be used by the LMS admin users).
AU Usage:The AU SHOULD get the launchParameters value from the LMS.LaunchData State document if the launch parameters were defined in the Course Structure.
Data Type:String
Value Space:Any string value

10.2.4 masteryScore

Description:The masteryScore from the cmi5 Course Structure.
LMS Required:The LMS MUST include a masteryScore in the LMS.LaunchData State document if the masteryScore was defined by the course designer in the Course Structure.
AU Required:If the masteryScore is provided.
LMS Usage:The masteryScore value written in the LMS.LaunchData State document MAY be different than the one in the course structure (e.g. based on administrative rules defined by the LMS).
AU Usage:If the AU issues "passed" or "failed" statements they MUST be based on the masteryScore if provided. (See Sections 9.3.4 Passed and 9.3.5 Failed)
Data Type:decimal
Value Space:Decimal value between 0 and 1 (inclusive) with up to 4 decimal places of precision.
Sample Value:0.75

10.2.5 moveOn

Description:The moveOn value from the cmi5 Course Structure.
LMS Required:Yes
AU Required:No
LMS Usage:The LMS MUST provide a moveOn value in the State API document. The moveOn value written in the State API Document MAY be different than the one in the course structure (e.g. based on administrative rules defined by the LMS).
AU Usage:The AU MAY get the moveOn value from the LMS.LaunchData state document and MAY use the value to modify its behavior.
Data Type:string
Value Space:moveOn values as defined in the Course Structure (Section 13.1.4 AU Metadata)
Sample Value:"Passed"

10.2.6 returnURL

Description:Used by the LMS when launching the AU if the LMS requires the AU (in a web-browser environment) to redirect the learner when he or she exits the AU.
LMS Required:No
AU Required:If the returnURL is provided.
LMS Usage:The LMS MAY include the returnURL when the learner SHOULD be redirected to the returnURL on exiting the AU.
AU Usage:The AU MUST attempt to get the returnURL value from the LMS.LaunchData state document. The AU MUST redirect the current browser window or frame to the returnURL when the AU is terminated if the returnURL is provided.
Data Type:String (Not URL encoded)
Value Space:Any URL.
Sample Value:http://www.example.com/lms/mod/xapilaunch/view.php?id=12

10.2.7 entitlementKey

Description:The entitlementKey object is used by the AU to determine if the launching LMS is entitled to use the AU.
LMS Required:Yes
AU Required:No
LMS Usage:The LMS MUST add an entitlementKey object to the LMS.LaunchData state document if an entitlementKey is present in the Course Structure for the AU. The entitlementKey consists of 2 properties, courseStructure and alternate. See items below for LMS usage requirements.
AU Usage:The AU SHOULD use this data in combination with other data provided from the LMS to determine entitlement.
Data Type:JSON Object
Value Space:The value for entitlementKey properties are defined by the AU provider.
Sample Value:{"courseStructure": "xyz-123-9999", "alternate": "abc-456-1111"}

10.2.7.1 courseStructure

Description:The courseStructure property contains the value for entitlementKey from the Course Structure. The courseStructure values MAY be used by the AU to determine if the launching LMS is entitled to use the AU.
LMS Required:Yes
AU Required:No
LMS Usage:The LMS MUST obtain this from the Course Structure.
AU Usage:The AU SHOULD use this data in combination with other data provided from the LMS to determine entitlement.
Data Type:string
Value Space:The value is defined by the AU provider.
Sample Value:"xyz-123-9999"

10.2.7.2 alternate

Description:The alternate property is data from some other source as agreed upon between the LMS and the AU. The alternate property values MAY be used by the AU to determine if the launching LMS is entitled to use the AU.
LMS Required:No
AU Required:No
LMS Usage:The LMS MUST obtain the value for the alternate property from a source as agreed upon with the AU.
AU Usage:The AU SHOULD use this data in combination with other data provided from the LMS to determine entitlement.
Data Type:string
Value Space:The value is defined by the AU provider.
Sample Value:"xyz-123-9999"

11.0 xAPI Agent Profile Data Model

In cmi5, Learner Preferences are scoped to the Agent representing the enrolled LMS learner. The agent used in xAPI Agent Profile requests MUST match the actor property generated by the LMS at AU launch time. Both the LMS and the AU MAY write changes to Learner Preferences in the xAPI Agent Profile. The LMS/LRS MAY choose to ignore or override Learner Preference changes requested by the AU by returning a "403 Forbidden" response as defined in xAPI. The AU MUST NOT treat the 403 response as an error condition.

The AU MUST retrieve the Learner Preferences document from the Agent Profile on startup.

When reading or writing to the Agent Profile, the document name MUST be "cmi5LearnerPreferences". The document content MUST be a JSON object with the languagePreference and audioPreference properties as described in Section 11.1 languagePreference and 11.2 audioPreference respectively. For example:

{
  "languagePreference": "<values for languages>",
  "audioPreference": "<on or off>"
}

11.1 languagePreference

The languagePreference MUST be a comma-separated list of RFC 5646 Language Tags. In the list, languages MUST be specified in order of user preference. In the example below, the user's first preference for language is en-US. The user's second preference for language is fr-FR and the third preference is fr-BE.

{
  "languagePreference": "en-US,fr-FR,fr-BE",
  ...
}

The AU SHOULD display in the language preference order of the user as in the example above (as supported).

11.2 audioPreference

The audioPreference value indicates whether the audio SHOULD be "on" or "off". The AU MUST turn the audio on or off at startup based on this value. If no value is provided in the Agent Profile for audioPreference the AU MAY use its own default value.

Example:

{
  "audioPreference": "on",
  ...
}

12.0 xAPI Activity Profile Data Model

The AU MAY use the Activity Profile API according to xAPI.

13.0 Course Structure Data Requirements

13.1 Course Structure Data Model

All leading/trailing whitespace MUST be removed by the LMS on import of the course structure for all of the data elements defined in this section.

The following Data Types are used in the cmi5 course structure data model, see the CourseStructure.xsd (Section 14.0 Course Package) for specific format:

  • decimal – XSD definition: xs:decimal
  • IRI – XSD definition: xs:anyURI
  • string – XSD definition: xs:string
  • langstring – XSD definition : <xs:element name="langstring" maxOccurs="unbounded" minOccurs="1"/>
  • objectiveReference – XSD definition : <xs:element name="objectives" type="referencesObjectivesType" minOccurs="0"/>

13.1.1 Course Level Metadata

The following metadata attributes and elements are at the course level and describe the course instance as a whole.

id

Required: Yes
Data type: IRI

Description:
A globally unique IRI to identify the course.

Value space:
Values are defined by the course designer.
Sample value:
<course id="http://www.example.com/identifiers/course/005430bf-b3ba-45e6-b47b-d629603d83d2" >…</course>

title

Required: Yes
Data type: langstring

Description:
A descriptive title that identifies the course.

Value space:
Values are defined by the course designer.

Sample value:
<title>
  <langstring lang="en-US">This is a course title</langstring>
  <langstring lang="es-MX">Se trata de un título del curso</langstring>
</title>

description

Required: Yes
Data type: langstring

Description:
A detailed description of the course.

Value space:
Values are defined by the course designer.

Sample value:
<description>
  <langstring lang="en-US">This is a course description</langstring>
  <langstring lang="es-MX">Esta es una descripción del curso</langstring>
</description>

13.1.2 Block Metadata

The data in this section are used for the block structures which group AUs. A Block consists of one or more AUs. Blocks can also contain references to objectives and other Blocks.

id

Required: Yes
Data type: IRI

Description: A globally unique IRI to identify the Block. This ID MUST be unique within the course structure.

Value space: Values defined by course designer.

Sample value:
<block id="http://www.example.com/identifiers/aublock/005430bf-b3ba-45e6-b47b-d629603d83d8" > … </block>

title

Required: Yes
Data type: langstring

Description:
A descriptive title for the Block of AUs.
Value space:
Values are defined by the course designer.
Sample value:
<title>
  <langstring lang="en-US">This is the block title</langstring>
  <langstring lang="es-MX">Este es el título del bloque</langstring>
</title>

description

Required: Yes
Data type: langstring

Description:
A detailed verbal description of what the Block contains.
Value space:
Values are defined by the course designer.
Sample value:
<description>
   <langstring lang="en-US">This is the block description</langstring>
   <langstring lang="es-MX">Esta es la descripción de los bloques</langstring>
</description>

objectives

Required: No
Data type: objectiveReference

Description:
A listing of objectives referenced by this block.
Value space:
Values are defined by the course designer.
Sample value:
<objectives>
   <objective idref="http://www.example.com/identifiers/objective/005430bf-b3ba-45e6-b47b-d629603d83d2" />
</objectives>

13.1.3 Objective Metadata

The data in this section are used by the Objectives. Objectives can be associated with a Block or with individual AUs.

id

Required: Yes
Data type: IRI

Description:
A globally unique IRI to identify the learning objective. This ID MUST be unique within the course structure.

Value space:
Values are defined by the course designer.

Sample value:
<objective id="http://www.example.com/identifiers/objective/005430bf-b3ba-45e6-b47b-d629603d83d2" >…</objective>

title

Required: Yes
Data type: langstring

Description:
A descriptive title for the learning objective

Value space:
Values are defined by the course designer.

Sample value:
<title>
   <langstring lang="en-US">This is the objective title</langstring>
   <langstring lang="es-MX">Este es el título del objetivo</langstring>
</title>

description

Required: Yes
Data type: langstring

Description:
A detailed verbal description of the learning objective.

Value space:
Values are defined by the course designer.

Sample value:
<description>
   <langstring lang="en-US">This is the objective description</langstring>
   <langstring lang="es-MX">Esta es la descripción objetiva</langstring>
</description>

13.1.4 AU Metadata

The data in this section are used by the LMS to locate the AU and provide launch data. AUs might also contain objectives.

id

Required: Yes
Data type: IRI

Description: A globally unique IRI to identify the AU. This ID MUST be unique within the course structure.

Value space: Values are defined by the AU publisher.

Sample value:
<au id="http://www.example.com/identifiers/activity/005430bf-b3ba-45e6-b47b-d629603d83d2" > … </au>

launchMethod

Required: No
Data type: string
Default Value: "AnyWindow"

Description: Used by the LMS when launching the AU (in a web-browser environment) to determine whether the AU requires its own window, or whether the LMS can choose the window context for the AU.

Usage:

  • A value of "OwnWindow" will require the LMS to launch the AU either in a new browser window, or the LMS MAY redirect the current window to the AU.
  • A value of "AnyWindow" indicates that the AU does not care about the window context. All browser window options are acceptable, such as in a Frameset, in a New Window, a browser redirect, etc.

Value space: "OwnWindow", "AnyWindow"

Sample value:
<au id="…" launchMethod="OwnWindow"> … </au>

masteryScore

Required: No
Data type: decimal

Description: A score used by the LMS to determine passing or failure of judged activity in the AU (if the AU has scoring).

Usage:

  • The masteryScore is passed to the AU at runtime by the LMS (See Section 10.0 xAPI State Data Model).
  • If the AU has scoring, it will use the masteryScore to determine pass/fail.
  • The masteryScore is a scaled, decimal value between 0 and 1 (inclusive) with up to 4 decimal places of precision.

Value space: Decimal number.

Sample value:
<au id="…" masteryScore="0.85"> … </au>

moveOn

Required: No
Data type: string
Default Value: "NotApplicable"

Description: Used by the LMS to determine if an AU has been sufficiently satisfied for the purposes of determining overall course satisfaction or determining if prerequisites were met for other activities.

moveOn Values are as follows:

  • moveOn Value = "Passed" : If the LMS receives a statement with the verb "Passed", then the LMS will consider the AU satisfied.
  • moveOn Value = "Completed" : If the LMS receives a statement with the verb "Completed", then the LMS will consider the AU satisfied.
  • moveOn Value = "CompletedAndPassed" : If the LMS receives statements with the verbs "Completed" and "Passed", then the LMS will consider the AU satisfied.
  • moveOn Value = "CompletedOrPassed" : If the LMS receives a statement with either of the verbs "Completed" or "Passed", then the LMS will consider the AU satisfied.
  • moveOn Value = "NotApplicable": The LMS will consider the AU satisfied.

Usage:

If all member AUs in a block are satisfied, then the block is considered satisfied for prerequisites and sequencing.
If all member AUs and Blocks are satisfied, then the course is considered satisfied for prerequisites or credit in relation to other courses or curricula.

Value space: "Passed", "Completed", "CompletedAndPassed", "CompletedOrPassed", "NotApplicable"

Sample value:
<au id="…" moveOn="Passed"> … </au>

activityType

Required: No
Data type: IRI

Description: Used by the LMS to determine the activity type of the AU before a first start to indicate this type to the user.

Sample value:
<au id="…" activityType="http://adlnet.gov/expapi/activities/media"> … </au>

title

Required: Yes
Data type: langstring

Description: A descriptive title for the AU.

Value space: Values are defined by the course designer.

Sample value:
<title>
  <langstring lang="en-US">This is an activity title.</langstring>
  <langstring lang="es-MX">Este es un título de la actividad.</langstring>
</title>

description

Required: Yes
Data type: langstring

Description:
A detailed description of the subject matter and learning activities covered by the AU.

Value space: Values are defined by the course designer.

Sample value:
<description>
   <langstring lang="en-US">This is the AU description</langstring>
   <langstring lang="es-MX">Esta es la descripción de la AU</langstring>
</description>

objectives

Required: No
Data type: objectiveReference

Description:
A listing of objectives referenced by this AU.

Value space: Values are defined by the course designer.

Sample value:
<objectives>
   <objective idref="http://www.example.com/identifiers/objective/005430bf-b3ba-45e6-b47b-d629603d83d2" />
</objectives>

url

Required: Yes
Data type: string

Description:

  • A relative or fully qualified URL that references the launch point of the AU.
  • To accommodate "non-browser" applications, an application specific protocol MAY be used in the url:
    <application>://<URL to content>
  • Regardless of the value of <scheme>, the remaining portion of the URL MUST conform to RFC1738 - Uniform Resource Locators (URL).
  • If the url includes a query string, the values from that query string MUST be merged with the cmi5 parameters at launch time (see Section 8.1 Launch Method).

Value space: Values are determined by the course designer.

Sample value:
<url>
http://www.example.com/courseX.html
</url>

launchParameters

Required: No
Data type: string

Description:
Static launch parameters defined by the course designer.

Value space:
Values are defined by the course designer.

Sample value:
<launchParameters>
Start=1,QuizMode=1,FastForward=On
</launchParameters>

entitlementKey

Required: No
Data type: string

Description:
Data used by the AU to determine if the launching LMS is entitled to use the AU. The AU SHOULD use this data in combination with other data provided from the LMS to determine entitlement.

Value space: Values are defined by the AU content provider.

Sample value:
<entitlementKey>
xyz-123-9999
</entitlementKey>

13.1.5 Vendor Specific Metadata (Extensions)

Course Designers MAY place their own namespaced elements into the course structure and thus define an extension for the source structure specification. For that they MUST provide a XML Schema Definition and SHOULD provide a human readable specification describing these vendor specific extensions. These extensions MUST keep the course structure XML valid. An importing LMS MAY ignore these elements. Therefore the extension SHOULD be created in such a manner that a course is still useable if the LMS does not support the additional elements.

To achieve a larger distribution of their extension course designers SHOULD choose a free or open source license for their specification and make it publicly available.

14.0 Course Package

Conceptually, a course package is a collection of all of the components (AUs) of the course. While previous standards often equated this with the gathering of all resources into a single archive (often a .ZIP file), cmi5 does not have this restriction; all files can be "packaged", even by reference.

Technically, a course package is an XML file format with a course structure. It can be standalone or contained in a ZIP file. A course package, when located in a ZIP file, MUST be named "cmi5.xml". The course package MUST conform to https://w3id.org/xapi/profiles/cmi5/v1/CourseStructure.xsd. Available locally in v1/CourseStructure.xsd.

An LMS MUST provide functionality such that a targeted course package is processed, resulting in a Course Structure import (See Section 3.0 Course Structure Data Requirements ). An LMS MUST support Course Packages in at least these three file formats:

  • Standalone XML file
  • 32-bit Zip Format
  • 64-bit Zip Format

An LMS MAY support alternate course package formats.

14.1 Course Packages in ZIP Format

The two ZIP file formats MUST follow the specification defined at https://www.pkware.com/support/zip-app-note. When the ZIP file is used to package a course, it MUST contain the course structure XML file at its root directory and it MAY contain media associated with the course AUs.

  • Any entry point for an AU included in a ZIP course package SHOULD be referenced by a relative URL in the Course Structure XML.
  • Any entry point for an AU not included in a ZIP course package MUST be referenced by a fully qualified URL in the Course Structure XML.
  • A ZIP course package MAY contain a mix of fully qualified and relative URLs, provided the rules above are followed.

14.2 Course Structure XML Without a ZIP File Package

When a course structure XML file is provided without a ZIP file package, all URL references MUST be fully qualified.

15.0 Course Structure Examples

Using the domain of geology the following two examples demonstrate how simple and complex a course designer can structure a course. The titles and descriptions are fetched or translated from the Earth Sciences Portal at Wikipedia (https://en.wikipedia.org/wiki/Portal:Earth_sciences).

15.1 Simple

Simple single AU course structure is available in v1/examples/simple-cmi5.xml.

15.2 Complex

Complex course structure with multiple objectives, multiple blocks with nesting, multiple AU blocks, etc. is available in v1/examples/complex-cmi5.xml.

15.3 Extension

An extended simple course structure example is available in v1/examples/extended-cmi5.xml which uses vendor specific metadata following the XML Schema Definition defined in v1/examples/extended-cmi5.xsd.

License Agreement

Copyright © 2012-2021 Advanced Distributed Learning (ADL) Initiative, U.S. Department of Defense, All rights reserved

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.