DRAFT - IEEE Standard for Learning Technology— JavaScript Object Notation (JSON) Data Model Format and Representational State Transfer (RESTful) Web Service for Learner Experience Data Tracking and Access

Notice

This page contains material that may be included-in or referenced by an unapproved draft of a proposed IEEE Standard. All material in this repository is subject to change. The material in this repository is presented “as is” and with all faults. Use of the material is at the sole risk of the user. IEEE specifically disclaims all warranties and representations with respect to all material contained in this repository and shall not be liable, under any theory, for any use of the material. Unapproved drafts of proposed IEEE standards must not be utilized for any conformance/compliance purposes.

1. Overview

The Experience API (xAPI) is a standard that describes an interoperable means to document and communicate information about learning experiences. It specifies a structure to describe learning experiences and defines how these descriptions can be exchanged electronically.

In assessing candidates’ suitability for positions or their capability for performing various tasks, there is a need to consider a wide range of formal and informal learning experiences, both on and offline. That information, more often than not, is scattered across a wide variety of sources.

Out of this decentralized environment, the Advanced Distributed Learning (ADL) Initiative created the original xAPI community and specification. The working group effort was moved to the IEEE in 2019.

xAPI assumes that:

• There is a need to be able to analyze information about learning experiences and their outcomes distributed across a wide variety of sources, platforms and technologies.
• Developing a commonly-accepted framework for gathering, storing and exchanging this information represents the best way of achieving this.

The goals of the xAPI are:

• To make it easier to understand and compare learning experiences and their outcomes recorded across a wide variety of contexts, platforms and technologies.
• To maximize interoperability of services which create, gather, store and process information about learning experiences.
• To provide a guide to those who want to build applications that conform to and implement this specification.
• To provide criteria against which conformance to this specification can be tested.

The xAPI Base Standard is an IEEE Open Source Project hosted on the IEEE Open Source Platform (it is licensed under the terms of the Apache 2.0 License and copyright the IEEE XAPI Authors see xAPI About for licensing and copyright information as well as additional information on contributing to this open source project). You can find this document and other open source resources related to the xAPI Base Standard at https://xapi.ieee-saopen.org.

Additional xAPI Base Standard resources are available as described below:

• xAPI Base Standard documentation
• xAPI Base Standard markdown
• xAPI Examples

1.1 Scope

This Standard describes a JavaScript Object Notation (JSON) data model format and a Representational State Transfer (RESTful) Web Service Application Programming Interface (API) for communication between Activities experienced by an individual, group, or other entity and a Learning Record Store (LRS). The LRS is a system that exposes the xAPI RESTful Web Service API for the purpose of tracking and accessing experiential data, especially in learning and human performance.

1.2 Purpose

The purpose of this Standard is to provide an interoperable means to store and retrieve learning experience data as required by modern, data-intensive learning technologies.

1.3 Word usage

The word shall indicates mandatory requirements strictly to be followed in order to conform to the standard and from which no deviation is permitted (shall equals is required to).

The word should indicates that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required (should equals is recommended that).

The word may is used to indicate a course of action permissible within the limits of the standard (may equals is permitted to).

The word can is used for statements of possibility and capability, whether material, physical, or causal (can equals is able to).

2. Normative references

The following referenced documents are indispensable for the application of this document (i.e., they shall be understood and used, so each referenced document is cited in text and its relationship to this document is explained). For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments or corrigenda) applies.

¹ IEEE Std 754^TM-2008, IEEE Standard for Floating-Point Arithmetic

² IETF RFC 2046:1996, Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types

³ IETF RFC 2616:1999, Hypertext Transfer Protocol – HTTP/1.1

⁴ FIPS PUB 180-2:2002, Secure Hash Signature Standard (SHA2)

⁵ IETF RFC 3629:2003, UTF-8, a transformation format of ISO 10646

⁶ IETF RFC 3987:2005, Internationalized Resource Identifiers (IRIs)

⁷ IETF RFC 4122:2005, A Universally Unique IDentifier (UUID) URN Namespace (IRIs)

⁸ IETF RFC 5646:2009, Tags for Identifying Languages

⁹ IETF RFC 7231:2014, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

¹⁰ IETF RFC 7515:2015, JSON Web Signature (JWS)

¹¹ IETF RFC 8259:2017, The JavaScript Object Notation (JSON) Data Interchange Format

¹² ISO 639-1, Code for the Representation of Names of Languages—Part 1: Alpha-2 code

¹³ ISO 639-2, Codes for the Representation of Names of Languages—Part 2: Alpha-3 code

¹⁴ ISO 3166-1, Codes for the Representation of Names of Countries and Their Subdivisions—Part 1: Country Codes

¹⁵ ISO 8601-1:2004, Date and time — Representations for information interchange — Part 1: Basic rules

¹⁶ SemVer, Semantic Versioning 1.0.0, https://semver.org/spec/v1.0.0.html

3. Definitions, acronyms, and abbreviations

3.1. Definitions

For the purposes of this document, the following terms and definitions apply. The IEEE Standards Dictionary Online should be consulted for terms not defined in this clause.

Activity: A type of Object making up the “this” in “I did this”; it is something with which an Actor interacted. It can be a unit of instruction, experience, or performance that is to be tracked in meaningful combination with a Verb. Interpretation of Activity is broad, meaning that Activities can even be tangible objects such as a chair (real or virtual). In the Statement “Anna tried a cake recipe”, the recipe constitutes the Activity in terms of the xAPI Statement. Other examples of Activities include a book, an e-learning course, a hike, or a meeting.

Activity Provider (AP): Now referred to as a Learning Record Provider. This change differentiates that the activity itself is not always the responsibility of software, rather just the tracking portion is.

Actor: An individual or group representation tracked using Statements performing an action within an Activity. Is the “I” in “I did this”.

Application Programming Interface (API): A set of rules and standards created to allow access into a software application or tool.

Authentication: The concept of verifying identity. Authentication allows interactions between two “trusted” parties.

Authorization: The affordance of permissions based on role; the process of making one party “trusted” by another.

Client: Refers to any entity that might interact through requests. Some examples could be a Learning Record Provider, a Learning Record Consumer, a Learning Record Store (LRS), or a Learning Management System (LMS).

Community of Practice (CoP): A group of practitioners connected by a common cause, role or purpose, which operates in a common modality. CoPs are focused on implementing xAPI within a specific knowledge domain or use case. CoPs or independent developers, can create domain-specific vocabularies, profiles, and recipes. These practices usually involve work around defining use cases and curating the various vocabulary terms, synonyms, and other related metadata that might be preferred within a CoP. They can also reuse existing vocabularies, profiles, and recipes already published by other CoPs or participants of the xAPI community.

Document Profile Resource: A construct where information about the learner or activity is kept, typically in name/document pairs that have meaning to an instructional system component. Not to be confused with Profile.

Endpoint: An entry point in a service-oriented-architecture. xAPI mirrors this approach with Document Profile Resources by defining the IRI from which communication takes place as an endpoint.

Experience API (xAPI): The collection of rules articulated in this document which determines how learning experiences are defined, formatted, and exchanged so that independent software programs can exchange and make use of this information.

Immutable: Adjective used to describe things which cannot be changed. With some exceptions, Statements in the xAPI are immutable. This helps to ensure that when Statements are shared between LRSs, multiple copies of the Statement remain the same.

Internationalized Resource Identifier (IRI): A unique identifier which could be an IRL. Used to identify an object such as a verb, activity or activity type. Unlike URIs, IRIs can contain some characters outside of the ASCII character set in order to support international languages. IRIs always include a scheme. This is not a requirement of this standard, but part of the definition of IRIs, per RFC 3987. What are sometimes called “relative IRIs” are not IRIs.

Internationalized Resource Locator (IRL): In the context of this document, an IRL is an IRI that when translated into a URI (per the IRI to URI rules), is a URL.

Inverse Functional Identifier (IFI): An identifier which is unique to a particular persona or Group.

Learning Experience: An event associated with learning. It is highly diverse as far as what it can be. Examples include reading a book, taking an online course, going on a field trip, engaging in self-directed research, or receiving a certificate for a completed course.

Learning Management System (LMS): A software package used to administer one or more courses to one or more learners. An LMS is typically a web-based system that allows learners to authenticate themselves, register for courses, complete courses and take assessments (Learning Systems Architecture Lab definition). An LMS in this document is used as an example of how a user is identified as “trusted” within a system and able to access its Learning Experiences.

Learning Record: An account of a learning experience that is formatted according to the rules of xAPI. A Learning Record takes on many forms, including Statements, documents, and their parts. This definition is intended to be all-inclusive.

Learning Record Consumer (LRC): An xAPI Client that accesses data from Learning Record Store(s) with the intent of processing the data, including interpretation, analysis, translation, dissemination, and aggregation.

Learning Record Provider (LRP): An xAPI Client that sends data to Learning Record Store(s). Often, the Learning Record Provider creates Learning Records while monitoring a learner as a part of a Learning Experience.

Learning Record Store (LRS): A server (i.e. system capable of receiving and processing web requests) that is responsible for receiving, storing, and providing access to Learning Records.

Metadata Consumer: A person, organization, software program or other thing that seeks to determine the meaning represented by an IRI used within this specification and/or retrieves metadata about an IRI. An LRS might or might not be a metadata consumer.

Metadata Provider: A person, organization, software program or other thing that coins IRIs to be used within this specification and/or hosts metadata about an IRI.

Persona: A set of one or more representations which defines an Actor uniquely. Conceptually, this is like having a “home email” and a “work email”. Both are the same person, but have different data, associations, etc.

Profile: A specific set of rules and documentation for implementing xAPI in a particular context. A profile provides a way to talk about vocabulary concepts, statement templates, and patterns for xAPI data. Not to be confused with Document Profile Resource.

Registration: An instance of an Actor experiencing a particular Activity.

Representational State Transfer (REST): An architecture for designing networked web services. It relies on HTTP methods and uses current web best practices.

Service: A software component responsible for one or more aspects of the distributed learning process.

Statement: A data structure showing evidence for any sort of experience or event which is to be tracked in xAPI as a Learning Record. A set of several Statements, each representing an event in time, might be used to track complete details about a learning experience.

Verb: Is the action being done by the Actor within the Activity within a Statement. A Verb represents the “did” in “I did this”.

3.2 Acronyms and abbreviations

AP - Activity Provider

API - Application Programming Interface

CoP - Community of Practice

IRI - Internationalized Resource Identifier

IRL - Internationalized Resource Locator

IFI - Inverse Functional Identifier

LRC - Learning Record Consumer

LRP - Learning Record Provider

LRS - Learning Record Store

REST - Representational State Transfer

xAPI - Experience API

4. Learning Record Stores (LRSs)

Tracking in this standard is accomplished through HTTP Requests from the Learning Record Provider (LRP) to the Learning Record Store (LRS) (a server system with requirements defined in this document). Section 4 details all requirements for the Learning Record Store. Accessing data in this standard is also accomplished through HTTP Requests from a Learning Record Consumer (LRC).

4.1 LRS Communication

The primary function of the LRS within the xAPI is to store and retrieve Statements. Validation of Statements in the Experience API is focused solely on syntax, not semantics. Enforcing the rules that help ensure valid meaning among Verb definitions, Activity types, and extensions is the not the responsibility of the LRS, it should only enforce rules regarding structure.

The following table summarizes the Resources with which HTTP methods can interact. Implementation details for each resource can be found in Section 5.1.6 LRS Resources. The LRS is interacted with via RESTful HTTP methods to the resources outlined in this section.

The LRS shall enforce requirements as found in the tables in this section, by rejecting any request with appropriate error code where invalid. Other Resources and undefined requests are out of scope of this document. It is suggested that an LRS should not reject those requests for the sole purpose of their absence from this document (but may certainly do so for security/unsupported reasons)

4.1.1 Headers

The LRS shall implement and validate, per other requirements in this document, the following request headers:

• Accept
• Accept-Encoding
• Accept-Language
• Authorization
• Content-Type
• Content-Length
• Content-Transfer-Encoding
• If-Match
• If-None-Match
• X-Experience-API-Version

The following response headers are expected to be used by the LRS. Again, not all of these apply to every type of request and/or situation:

• Content-Type
• Content-Length
• Last-Modified
• ETag
• Status
• X-Experience-API-Version
• X-Experience-API-Consistent-Through

The lists above are not intended to be exhaustive of LRS requirements. Implementation details can be found throughout this document.

4.1.2 Encoding

All strings shall be encoded and interpreted as UTF-8 (RFC 3629).

4.1.3 Content Types

Requests and responses within this specification normally use an application/json content type. Exceptions to this are:

• Documents can have any content type.
• Statement requests that can sometimes include Attachments use the multipart/mixed content type.

Application/JSON

• When receiving a PUT or POST with a document type of application/json, an LRS shall accept batches of Statements which contain no Attachment Objects.
• When receiving a PUT or POST with a document type of application/json, an LRS shall accept batches of Statements which contain only Attachment Objects with a populated fileUrl.

Multipart/Mixed

The multipart/mixed content type is used for requests that could include Attachments. This does not mean that all “multipart/mixed” requests necessarily do include Attachments.

Procedure For The Exchange Of Attachments

• A Statement request including zero or more Attachments is construed in accordance with requirements in this document.

• The Statement is sent using a Content-Type of multipart/mixed. Any Attachments are placed at the end of such transmissions.

• The LRS decides whether to accept or reject the Statement based on the information in the first section. The Statement is sent using a Content-Type of multipart/mixed. Any Attachments are placed at the end of such transmissions.

• If it accepts the request, it can match the raw data of an Attachment(s) with the Attachment header by comparing the SHA-2 (FIPS PUB 180-2) of the raw data to the SHA-2 declared in the header. It shall not do so any other way.

Requirements for Attachment Statement Batches

A request transmitting a Statement batch, Statement results, or single Statement that includes Attachments shall satisfy one of the following criteria:

• It shall be of type application/json and include a fileUrl for every Attachment EXCEPT for Statement results when the “attachments” filter is false.
• It shall conform to the definition of “multipart/mixed” in RFC 2046 and:
  • The first part of the multipart document shall contain the Statements themselves, with type application/json.
  • Each additional part contains the raw data for an Attachment and forms a logical part of the Statement. This capability is available when issuing PUT or POST requests against the Statement Resource.
  • shall include an X-Experience-API-Hash parameter in each part's header after the first (Statements) part.
  • shall include a Content-Transfer-Encoding parameter with a value of binary in each part's header after the first (Statements) part.
  • should only include one copy of an Attachment's data when the same Attachment is used in multiple Statements that are sent together.
  • should include a Content-Type parameter in each part's header. For the first part (containing the Statement) this shall be application/json.
  • Where parameters have a corresponding property within the attachment Object (and both the parameter and property are specified for a given Attachment, the value of these parameters and properties shall match.

LRS Requirements

• An LRS shall include Attachments in the Transmission Format described above when issued a Request.
• When receiving a PUT or POST with a document type of multipart/mixed, an LRS shall accept batches of Statements that contain Attachments in the Transmission Format described above.
• When receiving a PUT or POST with a document type of multipart/mixed, an LRS shall reject batches of Statements having Attachments that neither contain a fileUrl nor match a received Attachment part based on their hash.
• When receiving a PUT or POST with a document type of multipart/mixed, an LRS should assume a Content-Transfer-Encoding of binary for Attachment parts.
• When receiving a PUT or POST with a document type of multipart/mixed, an LRS shall accept batches of Statements which contain no Attachment Objects.
• When receiving a PUT or POST with a document type of multipart/mixed, an LRS shall accept batches of Statements which contain only Attachment Objects with a populated fileUrl.

Note: There is no requirement that Statement batches using the “mime/multipart” format contain Attachments.

The File URL is intended to provide a location from which the Attachment can be received. There are, however, no requirements for the owner of the Attachment to make the Attachment data available at the location indefinitely or to make the Attachment publicly available without security restrictions. When determining Attachment hosting arrangements, those creating Statements using the “fileUrl” property are encouraged to consider the needs of end recipient(s) of the Statement, especially if the Attachment content is not included with the Statement.

The period of time an Attachment is made available for, and the security restrictions applied to hosted attachments, are out of scope of this specification.

4.1.4 Concurrency

Concurrency control makes certain that a PUT, POST or DELETE does not perform operations based on old data.

xAPI uses HTTP 1.1 entity tags (ETags) to implement optimistic concurrency control in the following resources, where PUT, POST or DELETE are allowed to overwrite or remove existing data:

• State Resource
• Agent Profile Resource
• Activity Profile Resource

LRS Requirements

• An LRS responding to a GET request shall add an ETag HTTP header to the response.
• An LRS responding to a PUT, POST, or DELETE request shall handle the “If-Match” header as described in RFC2616, HTTP 1.1 in order to detect modifications made after the document was last fetched.

If the header precondition in either of the request cases above fails, the LRS:

• shall return HTTP status 412 Precondition Failed.
• shall not make a modification to the resource.

If a PUT request is received without either header for a resource that already exists, the LRS:

• shall return HTTP status 409 Conflict.
• shall return a response explaining that the Learning Record Provider should
  • check the current state of the resource.
  • set the “If-Match” header with the current ETag to resolve the conflict.
• shall not make a modification to the resource.

4.1.5 Error Codes

The list below covers many error conditions that could be returned from various methods in the API.

• 400 Bad Request - Indicates an error condition caused by an invalid or missing argument. The term “invalid arguments” includes malformed JSON (RFC 8259) or invalid Object structures.
• 401 Unauthorized - Indicates that authentication is required, or in the case authentication has been posted in the request, that the given credentials have been refused.
• 403 Forbidden - Indicates that the request is unauthorized for the given credentials. Note this is different than refusing the credentials given. In this case, the credentials have been validated, but the authenticated system is not allowed to perform the given action.
• 404 Not Found - Indicates the requested resource was not found. May be returned by any method that returns a uniquely identified resource, for instance, any State, Agent Profile, or Activity Profile Resource request targeting a specific document, or the method to retrieve a single Statement.
• 409 Conflict - Indicates an error condition due to a conflict with the current state of a resource, in the case of State Resource, Agent Profile Resource or Activity Profile Resource requests, or in the Statement Resource PUT or POST calls.
• 412 Precondition Failed - Indicates an error condition due to a failure of a precondition posted with the request, in the case of State or Agent Profile or Activity Profile API requests.
• 413 Request Entity Too Large - Indicates that the LRS has rejected the Statement or document because its size (or the size of an Attachment included in the request) is larger than the maximum allowed by the LRS.
• 429 Too Many Requests - Indicates that the LRS has rejected the request because it has received too many requests from the system or set of credentials in a given amount of time.
• 500 Internal Server Error - Indicates a general error condition, typically an unexpected exception in processing on the server.

Requirements

• An LRS shall return the error code most appropriate to the error condition from the list above.
• An LRS should return a message in the response explaining the cause of the error.
• An LRS should use content negotiation as described in RFC 7231 to decide the format of the error.
• An LRS should allow for plain text, HTML, and JSON (RFC 8259) responses for errors (using content negotiation).
• The LRS shall reject with 400 Bad Request status any requests that use any parameters which the LRS does not recognize in their intended context in this specification. ( Note: LRSs may recognize and act on parameters not in this specification).
• The LRS shall reject with 400 Bad Request status any requests that use any parameters matching parameters described in this specification in all but case.
• The LRS shall reject a batch of statements if any Statement within that batch is rejected.
• The LRS shall reject with 403 Forbidden status any request rejected by the LRS where the credentials associated with the request do not have permission to make that request.
• The LRS shall reject with 413 Request Entity Too Large status any request rejected by the LRS where the size of the Attachment, Statement or document is larger than the maximum allowed by the LRS.
• The LRS may choose any Attachment, Statement and document size limits and may vary this limit on any basis, e.g., per authority.
• The LRS shall reject with 429 Too Many Requests status any request rejected by the LRS where the request is rejected due to too many requests being received by a particular system or set of credentials in a given amount of time.
• The LRS may choose any rate limit and may vary this limit on any basis, e.g., per authority.

4.1.6 Resources

Each LRS Resource is described in the following sections. Each Resource has requirements for each of the HTTP methods that may be made to it. Each section includes the expected contents of the body of the request, the request parameters, and the expected returns. If an HTTP method is not described, it is out of scope of this document.

LRSs leverage both Statements and documents as data structures. The LRS shall support all of the resources described in this section.

• The LRS may support additional resources not described in this specification.
• Past, current and future versions of this specification do not define resource locations (endpoints) with path segments starting with extensions/. LRSs supporting additional resources not defined in this specification should define their resource locations with path segments starting with extensions/.
• A Learning Record Provider may send documents to any of the Document Resources for Activities and Agents that the LRS does not have prior knowledge of.
• The LRS shall not reject documents on the basis of not having prior knowledge of the Activity and/or Agent.

The LRS shall reject Requests where parameters are:

• missing any required properties.
• with any null values (except inside extensions).
• where the wrong data type is used (see tables), for example:
  • with strings where numbers are required, even if those strings contain numbers, or
  • with strings where booleans are required, even if those strings contain booleans.
• with any non-format-following key or value, including the empty string, where a string with a particular format (such as mailto IRI, UUID, or IRI) is required.
• where the case of a key does not match the case specified in this specification.
• where the case of a value restricted to enumerated values does not match an enumerated value given in this specification exactly.
• where a key or value is not allowed by this specification.
• containing IRL or IRI values without a scheme.

Note: In all of the examples in this specification, http://example.com/xAPI/ is the example base resource location (endpoint) of the LRS. All other IRI syntax after this represents the particular resource used.

Note that the following table shows generic properties, not a JSON Object as many other tables in this specification do. The id is stored in the IRL, “updated” is HTTP header information, and “contents” is the HTTP document itself (as opposed to an Object).

4.1.6.1 Statement Resource (/statements)

Statements are the key data structure of xAPI. This resource facilitates their storage and retrieval.

Example resource location/endpoint: http://example.com/xAPI/statements

PUT Request:

Summary: Stores a single Statement with the given id.

Body: The Statement object to be stored.

Returns: 204 No Content

• The LRS may respond before Statements that have been stored are available for retrieval.
• An LRS shall not make any modifications to its state based on receiving a Statement with a statementId that it already has a Statement for. Whether it responds with 409 Conflict or 204 No Content, it shall not modify the Statement or any other Object.
• If the LRS receives a Statement with an id it already has a Statement for, it should verify the received Statement matches the existing one and should return 409 Conflict if they do not match.

POST Request:

Summary: Stores a Statement, or a set of Statements.

Body: An array of Statements or a single Statement to be stored.

Returns: 200 OK, Array of Statement id(s) (UUID) in the same order as the corresponding stored Statements.

• The LRS may respond before Statements that have been stored are available for retrieval.
• An LRS shall not make any modifications to its state based on receiving a Statement with an id that it already has a Statement for. Whether it responds with 409 Conflict or 204 No Content, it shall not modify the Statement or any other Object.
• If the LRS receives a Statement with an id it already has a Statement for, it should verify the received Statement matches the existing one and should return 409 Conflict if they do not match.
• If the LRS receives a batch of Statements containing two or more Statements with the same id, it shall reject the batch and return 400 Bad Request.

GET Request:

Summary: Fetches a single Statement or multiple Statements. If the statementId or voidedStatementId parameter is specified a single Statement is returned. Otherwise, a StatementResult Object, a list of Statements in reverse chronological order based on “stored” time, subject to permissions and maximum list length. If additional results are available, an IRL to retrieve them is included in the StatementResult Object.

Body: None.

Returns: 200 OK, Statement or Statement Result

Note: The values of Boolean parameters are represented as true or false as in JSON.

• The LRS shall reject with a 400 Bad Request error any requests to this resource which contain both statementId and voidedStatementId parameters.
• The LRS shall reject with a 400 Bad Request error any requests to this resource which contain statementId or voidedStatementId parameters, and also contain any other parameter besides “attachments” or “format”.
• The LRS may apply additional query filter criteria based on permissions associated with the credentials used.
• In the event that no Statements are found matching the query filter criteria, the LRS shall still return 200 OK and a StatementResult Object. In this case, the “statements” property shall contain an empty array.
• The LRS shall include the header “X-Experience-API-Consistent-Through”, in ISO 8601 combined date and time format, on all responses to Statements Resource requests, with a value of the timestamp for which all Statements that have a “stored” property before that time are known with reasonable certainty to be available for retrieval. This time should take into account any temporary condition, such as excessive load, which might cause a delay in Statements becoming available for retrieval. It is expected that this is a recent timestamp, even if there are no recently received Statements.
• If the “attachment” property of a GET Statement is used and is set to true, the LRS shall use the multipart response format and include all Attachments as described in this document.
• If the “attachment” property of a GET statement is used and is set to false, the LRS shall not include Attachment raw data and shall report application/json.
• The LRS shall include, in the “Last-Modified” header, the most recent (maximum) “stored” property of any of the returned statement(s).
• When queried for Statements with a Format of exact, the LRS shall return the “display” property exactly as included (or omitted) within the Statement.

Filter Conditions for StatementRefs

This section outlines rules by which Statements targeting other Statements can sometimes be considered to meet the filter conditions of a query even if they do not match the original query's filter parameters. These rules do not apply when retrieving a single Statement using “statementId” or “voidedStatementId” query parameters.

‘Targeting Statements’ means that one Statement (the targeting Statement) includes the Statement id of another Statement (the targeted Statement) as a Statement Reference as the Object of the Statement.

For filter parameters which are not time or sequence based (that is, other than “since”, “until”, or “limit”), Statements which target another Statement (by using a StatementRef as the Object of the Statement) meet the filter condition if the targeted Statement meets the filter condition.

The time and sequence-based parameters shall still be applied to the Statement making the StatementRef in this manner. This rule applies recursively, so that “Statement a” is a match when a targets b which targets c and the filter conditions described above match for “Statement c”.

For example, consider the Statement ‘Ben passed explosives training’, and a follow up Statement: “Andrew confirmed <StatementRef to original Statement>”. The follow up Statement does not mention ‘Ben’ or ‘explosives training’, but when fetching Statements with an Actor filter of ‘Ben’ or an Activity filter of ‘explosives training’, both Statements match and are returned so long as they fall into the time or sequence being fetched.

Note: StatementRefs used as a value of the “Statement” property within Context do not affect how Statements are filtered.

Language Filtering Requirements for Canonical Format Statements

• Activity Objects contain Language Map Objects within their “name”, “description” and various interaction components. The LRS shall return only one language in each of these maps.
• The LRS may maintain canonical versions of language maps against any IRI identifying an object containing language maps. This includes the language map stored in the Verb's “display” property and potentially some language maps used within extensions.
• The LRS may maintain a canonical version of any language map and return this when canonical format is used to retrieve Statements. The LRS shall return only one language within each language map for which it returns a canonical map.
• In order to choose the most relevant language, the LRS shall apply the “Accept-Language” header as described in RFC 2616 (HTTP 1.1), except that this logic shall be applied to each language map individually to select which language entry to include, rather than to the resource (list of Statements) as a whole.

Voided Statements

• The LRS shall not return any Statement which has been voided, unless that Statement has been requested by voidedStatementId. The previously described process is no exception to this requirement. The process of retrieving voiding Statements is to request each individually by voidedStatementId.
• The LRS shall still return any Statements targeting the voided Statement, following the process and conditions previously described. This includes the voiding Statement, which cannot be voided.

4.1.6.2 State Resource (/activities/state)

A place to store information about the state of an activity in a generic form called a document. The intent of this resource is to store/retrieve a specific agent's data within a specific activity, potentially tied to a registration. The semantics of the LRS response are driven by the presence of a “stateId” parameter. If it is included, the GET and DELETE methods act upon a single defined state document identified by “stateId”. Otherwise, GET returns the available ids, and DELETE deletes all state in the context given through the other parameters. This resource has concurrency controls associated with it.

Example resource location/endpoint: http://example.com/xAPI/activities/state

PUT Request:

Summary: Stores a single document with the given id.

Body: The document object to be stored.

Returns: 204 No Content

POST Request:

Summary: Updates/stores a single document with the given id.

Body: The document object to be stored/updated.

Returns: 204 No Content

When an LRS receives a POST request with content type application/json for an existing document also of content type application/json, it shall merge the posted document with the existing document. In this context, merge is defined as:

• de-serialize the Objects represented by each document.
• for each property directly defined on the Object being posted, set the corresponding property on the existing Object equal to the value from the posted Object.
• store any valid json serialization of the existing Object as the document referenced in the request.

Note that only top-level properties are merged, even if a top-level property is an Object. The entire contents of each original property are replaced with the entire contents of each new property.

• If the document being posted or any existing document does not have a Content-Type of application/json, or if either document cannot be parsed as a JSON Object, the LRS shall respond with HTTP status code 400 Bad Request, and shall not update the target document as a result of the request.
• If the merge is successful, the LRS shall respond with HTTP status code 204 No Content.

(Single Document) GET Request

Summary: Fetches a single document with the given id.

Body: None.

Returns: 200, The State Document

• The LRS shall include a “Last-Modified” header indicating when the document was last modified.

(Single Document) DELETE Request:

Summary: Deletes a single document with the given id.

Body: None.

Returns: 204 No Content

(Multiple Document) GET Request:

Summary: Fetches State ids of all state data for this context (Activity + Agent [+ registration if specified]). If “since” parameter is specified, this is limited to entries that have been stored or updated since the specified timestamp (exclusive).

Body: None.

Returns: 200, Array of State ids

(Multiple Document) DELETE Request:

Summary: Deletes all state data for this context (Activity + Agent [+ registration if specified]).

Body: None.

Returns: 204 No Content

4.1.6.3 Agents Resource (/agents)

The Agents Resource provides a method to retrieve a special Object with combined information about an Agent derived from an outside service, such as a directory service. This object is called a “Person Object”. The Person Object is very similar to an Agent Object, but instead of each attribute having a single value, each attribute has an array value, and it is legal to include multiple identifying properties. This is different from the FOAF concept of person, person is being used here to indicate a person-centric view of the LRS Agent data, but Agents just refer to one persona (a person in one context).

Example resource location/endpoint: http://example.com/xAPI/agents

GET Request

Summary: Return a Person Object for a specified Agent.

Body: None.

Returns: 200 OK, Person Object

Person Object Details

• If an LRS does not have any additional information about an Agent to return, the LRS shall still return a Person Object when queried, but that Person Object only includes the information associated with the requested Agent.

• All array properties shall be populated with members with the same definition as the similarly named property from Agent Objects.

4.1.6.4 Activities Resource (/activities)

The Activities Resource provides a method to retrieve a full description of an Activity from the LRS.

Example resource location/endpoint: http://example.com/xAPI/activities

GET Request:

Summary: Fetches the complete Activity Object specified.

Body: None.

Returns: 200 OK, Content

• If an LRS does not have a canonical definition of the Activity to return, the LRS shall still return an Activity Object when queried.

4.1.6.5 Agent Profile Resource (/agents/profile)

A place to store information about an Agent in a generic form called a document. This information is not tied to an activity or registration. The semantics of the LRS response are driven by the presence of a “profileId” parameter. If it is included, the GET method acts upon a single defined profile document identified by “profileId”. Otherwise, GET returns the available ids given through the other parameter. This resource has concurrency controls associated with it.

Example resource location/endpoint: http://example.com/xAPI/agents/profile

PUT Request:

Summary: Stores a single document with the given id.

Body: The document to be stored.

Returns: 204 No Content

POST Request:

Summary: Stores/updates a single document with the given id.

Body: The document to be stored/updated.

Returns: 204 No Content

When an LRS receives a POST request with content type application/json for an existing document also of content type application/json, it shall merge the posted document with the existing document. In this context, merge is defined as:

• de-serialize the Objects represented by each document.
• for each property directly defined on the Object being posted, set the corresponding property on the existing Object equal to the value from the posted Object.
• store any valid json serialization of the existing Object as the document referenced in the request.

Note that only top-level properties are merged, even if a top-level property is an Object. The entire contents of each original property are replaced with the entire contents of each new property.

• If the document being posted or any existing document does not have a Content-Type of application/json, or if either document cannot be parsed as a JSON Object, the LRS shall respond with HTTP status code 400 Bad Request, and shall not update the target document as a result of the request.
• If the merge is successful, the LRS shall respond with HTTP status code 204 No Content.

DELETE Request:

Summary: Deletes a single document with the given id.

Body: None.

Returns: 204 No Content

(Single Document) GET Request:

Summary: Fetches a single document with the given id.

Body: None.

Returns: 200 OK, the Profile document

• The LRS shall include a “Last-Modified” header indicating when the document was last modified.

(Multiple Document) GET Request:

Summary: Fetches Profile ids of all Profile documents for an Agent. If “since” parameter is specified, this is limited to entries that have been stored or updated since the specified Timestamp (exclusive).

Body: None.

Returns: 200 OK, Array of profileIds.

4.1.6.6 Activity Profile Resource (/activities/profile)

A place to store information about an Activity in a generic form called a document. This information is not tied to an Actor or registration. The semantics of the LRS response are driven by the presence of a “profileId” parameter. If it is included, the GET method acts upon a single defined profile document identified by “ProfileId”. Otherwise, GET returns the available ids given through the other parameter. This resource has concurrency controls associated with it.

Example resource location/endpoint: http://example.com/xAPI/activities/profile

PUT Request:

Summary: Stores a single document with the given id.

Body: The document to be stored.

Returns: 204 No Content

POST Request:

Summary: Stores/updates a single document with the given id.

Body: The document to be stored/updated.

Returns: 204 No Content

When an LRS receives a POST request with content type application/json for an existing document also of content type application/json, it shall merge the posted document with the existing document. In this context, merge is defined as:

• de-serialize the Objects represented by each document.
• for each property directly defined on the Object being posted, set the corresponding property on the existing Object equal to the value from the posted Object.
• store any valid json serialization of the existing Object as the document referenced in the request.

Note that only top-level properties are merged, even if a top-level property is an Object. The entire contents of each original property are replaced with the entire contents of each new property.

• If the document being posted or any existing document does not have a Content-Type of application/json, or if either document cannot be parsed as a JSON Object, the LRS shall respond with HTTP status code 400 Bad Request, and shall not update the target document as a result of the request.
• If the merge is successful, the LRS shall respond with HTTP status code 204 No Content.

DELETE Request:

Summary: Deletes a single document with the given id.

Body: None.

Returns: 204 No Content

(Single Document) GET Request:

Summary: Fetches a single document with the given id.

Body: None.

Returns: 200 OK, the Profile document

• The LRS shall include a “Last-Modified” header indicating when the document was last modified.

(Multiple Document) GET Request:

Summary: Fetches Profile ids of all Profile documents for an Activity. If “since” parameter is specified, this is limited to entries that have been stored or updated since the specified Timestamp (exclusive).

Body: None.

Returns: 200 OK, Array of profileIds.

4.1.6.7 About Resource (/about)

Returns JSON Object containing information about this LRS, including supported extensions and xAPI version(s).

Example resource location/endpoint: http://example.com/xAPI/about

GET Request:

Body: None.

Returns: 200 OK, JSON object containing basic metadata about this LRS

• An LRS shall return the JSON document described above, with a “version” property that includes the latest minor and patch version the LRS conforms to, for each major version.
• An LRS shall not reject requests based to this resource on their version header as would otherwise be required by Versioning.

4.1.7 Versioning

Using Semantic Versioning allows LRPs and LRSs to remain interoperable as the specification changes.

Details

xAPI is versioned according to Semantic Versioning 1.0.0. Every request from an LRP (or other systems that may interact with an LRS) and every response from the LRS includes an HTTP header with the name X-Experience-API-Version and the version as the value. For example, X-Experience-API-Version : 2.0.0 for version 2.0.0;

Note: For patch versions of the specification later than 2.0.0, the “X-Experience-API-Version” header does not match the statement version property which is always 2.0.0 for all 2.0.x versions of the spec. The “X-Experience-API-Version” header enables the LRS and client system to determine the exact patch version of the specification being followed. While no communication incompatibility should arise among 2.0.x versions, there are sometimes clarifications of previously intended behavior.

LRS Requirements

• The LRS shall include the “X-Experience-API-Version” header in every response.
• The LRS shall set this header to the latest patch version.
• The LRS shall accept requests with a version header of 2.0 as if the version header was 2.0.0.
• The LRS shall reject requests with version header prior to version 2.0.0 unless such requests are routed to a fully conformant implementation of a prior version specified in the header.
• The LRS shall reject requests with a version header of 2.1.0 or greater.
• The LRS shall make these rejects by responding with a 400 Bad Request error including a short description of the problem.

4.1.8 Authentication

Rationale

In order to support the varying security requirements of different environments, a specific authentication mechanism is not defined.

Requirements

• The LRS shall handle making, or delegating, decisions on the validity of Statements, and determining what operations might be performed based on the credentials used (or lack thereof).

4.1.9 Security

Security is beyond the scope of this document and left to the individual LRS provider as an implementation detail. Implementors are encouraged to follow industry best practices, e.g., The HTTPS-Only Standard from the office of the White House CIO.

It is possible that security concerns may arise in the implementation of this specification, and implementers might choose to break a conformance requirement for the sake of security. In these cases, implementers are encouraged to consider both the security and interoperability implications of their implementation decisions. In any case, the LRS still needs to be configurable such that it is able to pass conformance tests.

4.2 LRS Data Requirements

The LRS is responsible for handling various data formats described in Section 1.1. This includes following acceptance criteria for those data formats. The most common data format in xAPI is the Statement.

The required field in each of these tables dictates the LRS responsibility in validating data. Required indicates the LRS needs this property and rejects Statements that do not have them. Recommended indicates that the LRS should be given this property. Optional indicates that the field may be used as is and the LRS takes no default responsibility if it is not provided. Not Recommended indicates that the LRS should not receive this property and instead the LRS should populate the value.

Statement Immutability:

While the methods to PUT/POST and GET Statements are specific, the storage mechanism is not. JSON has flexibility in form, which means that a reconstruction may not be exact, ordering being a very common example. This document defines only certain aspects of Statements to be immutable. For all intents and purposes, if immutability required fields are equal, then the Statements are equal.

• The LRS shall store, retrieve, and compare Statements in a way that preserves immutability requirements, which includes the following properties with exceptions in parentheses
  • Actor (except the ordering of group members)
  • Verb (except for display)
  • Object
  • Duration (see section on Duration for further requirements)
• The LRS shall specifically not consider any of the following for equivalence, nor is it responsible for preservation as described above for the following properties/cases:
  • Case (upper vs. lower)
  • Id
  • Order of any Group Members
  • Authority
  • Stored
  • Timestamp
  • Version
  • Any attachments
  • Any referenced Activity Definitions

4.2.1 Table Guidelines

Tables in this document represent requirements that shall be followed. It is the responsibility of an LRS to reject requests that contain data that does not follow requirements in these tables. The following requirements are expected to be followed for each table in this section. Note: The “description” portion of table has requirements, in particular for controlled vocabulary, enumerations, etc.

• The LRS shall reject any Statement that does not conform to the “Type” field.
• An LRS shall reject a Statement with additional properties other than extensions in the locations where extensions are allowed
• An LRS shall reject a Statement with invalid IRIs
• An LRS shall reject a Statement that uses a property more than once
• The LRS shall reject Statements:

  • missing any required properties

  • with any null values (except inside extensions).

  • where the wrong data type is used (see tables), for example:

    • with strings where numbers are required, even if those strings contain numbers, or
    • with strings where booleans are required, even if those strings contain booleans.

  • with any non-format-following key or value, including the empty string, where a string with a particular format (such as mailto IRI, UUID, or IRI) is required.

  • where the case of a key does not match the case specified in this specification.

  • where the case of a value restricted to enumerated values does not match an enumerated value given in this specification exactly.

  • where a key or value is not allowed by this specification.

  • containing IRL or IRI values without a scheme.

4.2.2 Statement

Each Statement in xAPI has the following JSON structure and requirements. Note that requirements for properties with type “Object” are included in subsequent tables.

4.2.2.1 Actor

Actors can take on the form of either Groups or Agents. Groups can be identified, and if they are not, are considered to be anonymous groups. Specific requirements are found in the tables below.

Actor as Agent Table: The table below lists the properties of Agent Objects.

Actor as Anonymous Group Table: The table below lists all properties of an Anonymous Group.

Actor as Identified Group Table: The table below lists all properties of an Identified Group.

Account Table: The table below lists all properties of Account Objects.

4.2.2.2 Verb

Verbs appear in Statements as Objects consisting of an IRI and a set of display names corresponding to multiple languages or dialects which provide human-readable meanings of the Verb. The table below lists all properties of the Verb Object.

4.2.2.3 Object

Objects in xAPI vary widely in use and are classified in that use by the objectType property. Each of the following sections provides additional requirements that stem from the use of objectType.

The LRS shall treat any Object without an objectType as though the value was “Activity”.

Object As Activity Table: The following table lists the Object properties of an Activity.

Activity Definition (referenced in Object as Activity) Table: All properties are optional, but if implemented, some properties in sub-properties are required.

Interaction Activities (referenced in Activity Definition) Table: If implemented, the Interaction Activities Object follows this table:

Interaction Types (referenced in Interaction Activities Table): The interactionType is controlled vocabulary. Based on the term used, the data formatting and purpose changes according to the following table.

The Correct Responses Pattern contains an array of response patterns. A learner's response is considered correct if it matches any of the response patterns in that array. Where a response pattern is a delimited list, the learner's response is only considered correct if all of the items in that list match the learner's response.

Characterstring Parameters

Some of the values within the responses described above can be prepended with certain additional parameters. These parameters are represented by the format {parameter=value}. See the long-fill-in example within the Examples section.

Characterstring parameters are not validated by the LRS. Systems interpreting Statement data can use their best judgement in interpreting (or ignoring) invalid characterstring parameters and values.

The following parameters are valid at the start of the string representing the list of items for the listed interaction types:

The following parameters are valid at the start of each item in the list for the listed interaction types:

Interaction Components, Expanded (part of the Interaction Activities Table): Depending on interactionType, Interaction Activities can take additional properties, each containing a list of interaction components. These additional properties are called “interaction component lists”. The following table shows the supported interaction component list(s) for an Interaction Activity with the given interactionType.

Regardless of interactionType, each Component List has the following additional properties:

Object As Actor Table: The table below lists all properties of a Actor Object.

Object As Statement Table: The table below lists all properties of a Statement Reference Object.

Object As Sub-Statement Table: The table below lists all properties of a Sub-Statement Object.

4.2.2.4 Result

Represents a measured outcome related to the Statement in which it is included.

Result Table: The table below lists all properties of the Result Object.

Score Table: Represents the outcome of a graded Activity achieved by an Agent. The table below lists all properties of the Score Object.

4.2.2.5 Context

Property to add contextual information to a Statement. It can store information such as the instructor for an experience, if this experience happened as part of a team-based Activity, or how an experience fits into some broader activity.

Context Table: The table below lists all properties of the Context Object.

Note: With the addition of context agents and context groups, it is recommended not to use instructor or team. They are supported in this document for backward compatibility purposes.

Context Agents and Groups Details:

A single Statement may require the inclusion of many contextually relevant Agent(s) and/or Group(s) in order to properly describe an experience. When this is the case, the relationship between the Agent(s) and/or Group(s) and the Statement itself needs to be represented in a structured manner. The context properties contextAgents and contextGroups serve as this structure.

• Inclusion of contextAgents within a Statement establishes that a relationship exists between said Statement and one or more Agent(s)
• Inclusion of contextGroups within a Statement establishes that a relationship exists between said Statement and one or more Group(s)
• Zero or more Activity Types are used to categorize each Statement specific relationship
• Each Statement specific relationship corresponds to an individual contextAgents or contextGroups Object

The relationship established by each contextAgents and contextGroups Object is limited in scope to the Statement in which the Object is found. In general, an Agent many have permanent characteristics, characteristics which are consistent across experiences, but these kinds of Agent specific properties should be captured in an Agent Profile

All Objects found within the contextAgents and/or contextGroups array(s) are independent of one another.

Context Agents Table: Each contextAgent Object found within a contextAgents array has the following properties.

• Any and All valid Agent Objects can be used as the agent within a contextAgent Object.
• An Agent Object does not need to be found within any other Statement property in order to be included as the agent property within a contextAgent Object.
• Any and All valid Activity Type IRIs can be included within the relevantTypes array of a contextAgent Object.
• An Activity Type IRI does not need to be found within any other Statement property in order to be included within the relevantTypes property of a contextAgent Object

Context Group Table: Each contextGroup Object found within a contextGroups array has the following properties.

• Any and All valid Group Objects can be used as the group within a contextGroup Object
• A Group Object does not need to be found within any other Statement property in order to be included as the group property within a contextGroup Object.
• Any and All valid Activity Type IRIs can be included within the relevantTypes array of a contextAgent Object.
• An Activity Type IRI does not need to be found within any other Statement property in order to be included within the relevantTypes property of a contextAgent Object

4.2.2.6 Attachments

In some cases an Attachment is logically an important part of a Learning Record. It could be an essay, a video, etc. Another example of such an Attachment is (the image of) a certificate that was granted as a result of an experience.

Attachments Table: The table below lists all properties of the Attachments Object.

4.2.3 Metadata

Metadata is additional information about a resource. It enables decision making, search, and discoverability. In xAPI, metadata can be utilized essentially in two ways.

First, metadata is used in the definition property of an Activity Object (the Object when the objectType is Activity). In this case, the metadata is part of the Statement. Other fields, including extensions, can be used as metadata in a similar regard. Including metadata in a Statement allows metadata about the IRI to be expressed without the necessity of resolving it.

Second, metadata may be hosted. In this case, additional information about an identifier can be provided within a Statement and can be hosted at the location pointed to by the identifier IRI. Hosting metadata at the IRI location allows the owner of the IRI to define the canonical metadata for that IRI. This is the main purpose for which IRIs are used in xAPI.

All hosted metadata, including the format, is optional. However, it is recommended that the Activity Definition Object metadata is followed for hosted Activity identifiers.

For the structure of metadata about all other identifiers, see the format below:

Hosted metadata consists of a document containing a JSON object as described above. If this hosted metadata is provided, it is the canonical source of information about the identifier it describes.

4.2.3.1 LRS Recommendations

The following recommendations are made for any LRS that implements resolvable metadata into its data model for querying purposes.

• If an Activity IRI is a URL, an LRS should attempt to GET that URL, and include in HTTP headers: Accept: application/json, */*. This should be done as soon as practical after the LRS first encounters the Activity id.
• Upon loading JSON which is a valid Activity Definition from a URL used as an Activity id, an LRS should incorporate the loaded definition into its canonical definition for that Activity, while preserving names or definitions not included in the loaded definition.
• Upon loading any document from which the LRS can parse an Activity Definition from a URL used as an Activity id, an LRS may consider this definition when determining its canonical representation of that Activity's definition.

4.2.4 LRS Processing of Data

An LRS functions as a gatekeeper for xAPI Data. Statements, in particular, are highly structured and have many requirements. Statements are expected to be unique and to be immutable. In this regard they are unchangeable and should not be deleted. This section outlines requirements that focus on storage and retrieval of Statements, including the rejection cases for Statements.

4.2.4.1 LRS Rejection Cases

It is useful to note that an LRS can reject Statements for many reasons not specified in this document and does not have to perpetually keep data beyond normal processes. This specification is not intended to usurp security, authority, or data management processes.

The following requirements have to do with rejection/acceptance in such cases:

• The LRS should reject entire batches of Statements if sent from an unauthorized source
• An LRS _may__not_ reject a Statement solely based on the order of properties
• The LRS shall not reject a Statement that uses the voided verb if it cannot find the id of the Object of that Statement (nor does the LRS have to try to find it)
• An LRS should not reject a Statement based on size of individual properties
• An LRS may reject a Statement if the overall size is too large, contains information not permissible to the environment, or is thought to be malicious
• An LRS may choose to not validate IRIs/UUIDs; An LRS is responsible for data format, not values
• An LRS shall not reject a timestamp for having a greater value than the current time, within an acceptable margin of error (intentionally not specified in this document)

4.2.4.2 Specific Statement Data Requirements for an LRS

The following requirements apply to specific parts of a component. These requirements involve rejection, creation, conformance to standards, and overwriting of data.

• The LRS shall not return a different serialization of any properties except those as described in Section 4.2.
• The LRS shall create an “id” property if an accepted Statement does not have one.
• The LRS shall reject Statements if the Actor object contains more than one Inverse Functional Identifier
• The LRS shall reject Statements which use an Agent of type “Group” within the member property of a Group.
• The LRS shall process and store numbers with at least the precision of IEEE 754 32-bit floating point numbers
• The LRS shall reject a Statement that uses an Interaction Activity without a valid interactionType
• An LRS, upon consuming a valid interactionType, may validate the remaining properties as specified for Interaction Activities and may return 400 Bad Request if the remaining properties are not valid for the Interaction Activity.
• An interaction component's id value should not have whitespace.
• The LRS shall reject a Statement with an Object with ObjectType SubStatement that has within it an Object with ObjectType SubStatement.
• The LRS shall set the “timestamp” property to the value of the “stored” property if not provided.
• The “stored” property shall be set by the LRS; An LRS should validate and then shall overwrite any value currently in the “stored” property of a Statement it receives.
• The LRS shall ensure that all Statements stored have an authority
• The LRS should overwrite the authority on all Statements it stores, based on the credentials used to send those Statements.
• When the LRS overwrites the authority, the LRS shall apply a deterministic process to map the credentials used to store a statement to an authority
• The LRS may leave the submitted authority unchanged but should do so only where a strong trust relationship has been established, and with extreme caution.
• The LRS shall return every value in the contextActivities Object as an array, even if it arrived as a single Activity Object.
• The LRS shall return single Activity Objects as an array of length one containing the same Activity.
• An LRS should not reject a Statement that is otherwise valid except the version (property within Statement).

4.2.4.3 Data Response Recommendations

The following optional recommendations are determined best practices to some of the fringe components of xAPI. This section can be used to detail processes that come up in exceptional cases.

Upon receiving a Statement with an Activity Definition that differs from the one stored, an LRS should decide whether it considers the Learning Record Provider to have the authority to change the definition and should update the stored Activity Definition accordingly if that decision is positive.

An LRS may make small corrections to its canonical definition for the Activity when receiving a new definition e.g. spelling error.

An LRS should not make significant changes to its canonical definition for the Activity based on an updated definition e.g. changes to correct responses.

Statements returned by an LRS shall retain the version they are accepted with. If they lack a version, the version shall be set to 2.0.0.

An LRS may include all necessary information within the “more” property IRL to continue the query to avoid the need to store IRLs and associated query data.

An LRS should not generate extremely long IRLs within the “more” property.

An LRS may re-run the query at the point in time that the IRL retrieved from the “more” property is accessed such that the batch retrieved includes Statements which would have been included in that batch if present in the LRS at the time the original query was run and excludes Statements from that batch which have since been voided.

Alternatively, an LRS may cache a list of Statements to be returned at the “more” property such that the batch of Statements returned matches those Statements that would have been returned when the original query was run.

An LRS may remove voided Statements from the cached list of Statements if using this method.

4.2.5 Statement Voiding

Not all Statements are perpetually valid once they have been issued. Mistakes or other factors could dictate that a previously made Statement is marked as invalid. This is called “voiding a Statement” and the reserved Verb “http://adlnet.gov/expapi/verbs/voided” is used for this purpose. Any Statement that voids another cannot itself be voided.

The LRS shall reject Statements with the verb http://adlnet.gov/expapi/verbs/voided when:

• The objectType property is not “StatementRef”
• Has no “id” for the Object (e.g. no target for voiding)

An LRS shall consider a Statement it contains voided if and only if the Statement is not itself a voiding Statement and the LRS also contains a voiding Statement referring to the first Statement

Upon receiving a Statement that voids another, the LRS may roll back any changes to Activity or Agent definitions which were introduced by the Statement that was just voided.

4.2.6 Statement Signing

A Statement can include a digital signature to provide strong and durable evidence of the authenticity and integrity of the Statement.

Signed Statements include a JSON web signature (JWS) as an Attachment. This allows the original serialization of the Statement to be included along with the signature. For interoperability, the “RSA + SHA” series of JWS algorithms have been selected, and for discoverability of the signer X.509 certificates should be used.

Statement Signing Process:

• A Signed Statement shall include a JSON web signature (JWS) as defined in RFC 7515, as an Attachment with a usageType of “http://adlnet.gov/expapi/attachments/signature” and a contentType of application/octet-stream.
• JWS Compact Serialization shall be used to create the JSON web signature. Use of JWS JSON Serialization is strongly discouraged, is unlikely to be interoperable with other systems, and will be forbidden in a future version of this specification.
• The JWS signature shall have a payload of a valid JSON serialization of the complete Statement before the signature was added.
• The JWS signature shall use an algorithm of “RS256”, “RS384”, or “RS512”.
• The JWS signature should have been created based on the private key associated with an X.509 certificate.
• If X.509 was used to sign, the JWS header should include the “x5c” property containing the associated certificate chain.

Additional Requirements

• The LRS shall reject requests to store Statements that contain malformed signatures, with 400 Bad Request.
• The LRS should include a message in the response of a rejected statement.
• In order to verify signatures are well formed, the LRS shall do the following:
  • Decode the JWS signature and load the signed serialization of the Statement from the JWS signature payload.
  • Validate that the original Statement is logically equivalent to the received Statement.
  • If the JWS header includes an X.509 certificate, validate the signature against that certificate as defined in JWS.
  • Validate that the signature requirements outlined above have been met.

4.2.7 Additional Requirements for Data Types

The following section provides guidance and requirements for data types found in this document. Many tables contain specific data types that have requirements found in this section.

IRIs:

Internationalized Resource Identifiers, or IRIs, are unique identifiers which could also be resolvable. Because resolving is not a requirement, IRIs/URIs are used instead of IRLs/URLs. In order to allow the greatest flexibility in the characters used in an identifier, IRIs are used instead of URIs as IRIs can contain some characters outside of the ASCII character set.

The LRS has responsibilities in regard to each IRI as outlined below.

• When storing or comparing IRIs, LRSs shall handle them only by using one or more of the approaches described in 5.3.1 (Simple String Comparison) and 5.3.2 (Syntax-Based Normalization) of RFC 3987

Extensions:

Extensions are available as part of Activity Definitions, as part of a Statement's “context” property, or as part of a Statement's “result” property. In each case, extensions are intended to provide a natural way to extend those properties for some specialized use. The contents of these extensions might be something valuable to just one application, or it might be a convention used by an entire Community of Practice.

Extensions are defined by a map and logically relate to the part of the Statement where they are present. The values of an extension can be any JSON value or data structure. Extensions in the “context” property provide context to the core experience, while those in the “result” property provide elements related to some outcome. Within Activities, extensions provide additional information that helps define an Activity within some custom application or Community of Practice. The meaning and structure of extension values under an IRI key are defined by the person who controls the IRI.

• The LRS shall reject any Statement where a key of an extensions map is not an IRI.
• An LRS shall not reject a Statement based on the values of the extensions map.

Language Maps:

A language map is a dictionary where the key is an RFC 5646 Language Tag, and the value is a string in the language specified in the tag. This map should be populated as fully as possible based on the knowledge of the string in question in different languages.

The shortest valid language code for each language string is generally preferred. The ISO 639 language code plus an ISO 3166-1 country code allows for the designation of basic languages (e.g., es for Spanish) and regions (e.g., es-MX, the dialect of Spanish spoken in Mexico). If only the ISO 639 language code is known for certain, do not guess at the possible ISO 3166-1 country code. For example, if only the primary language is known (e.g., English) then use the top-level language tag en, rather than en-US. If the specific regional variation is known, then use the full language code.

Note: For Chinese languages, the significant linguistic diversity represented by “zh” means that the ISO 639 language code is generally insufficient.

The content of strings within a language map is plain text. It is expected that any formatting code such as HTML tags or markdown is not rendered but displayed as code when this string is displayed to an end user. An important exception to this is if language map Object is used in an extension and the owner of that extension IRI explicitly states that a particular form of code is to be rendered.

• An LRS shall reject a Statement with invalid RFC 5646 language tags (Keys of language maps shall be sent with valid RFC 5646 language tags, for similar reasons
• The LRS shall at least validate that the sequence of token lengths for language map keys matches the RFC 5646 standard

UUIDs:

Universally Unique Identifiers, or UUIDs, are 128-bit values that are globally unique. Unlike IRIs, there is no expectation of resolvability as UUIDs take on a completely different format.

• UUIDs shall be in the standard string form.
• UUIDS should use variant 2 in RFC 4122.

Timestamps:

• An LRS shall convert Timestamps to UTC rather than rejecting Statements that send Timestamps not in UTC form
• An LRS may truncated or round a Timestamp to a precision of at least 3 decimal digits for seconds.

Duration:

• The LRS shall reject a Statement if the duration is not expressed using the format for Duration in ISO 8601:2004(E) section 4.4.3.2.
• An LRS shall reject Statements with the alternative format (in conformity with the format used for time points and described in ISO 8601:2004(E) section 4.4.3.3). This requirement exists in case of conflicting ISO requirements.
• On receiving a Duration with more than 0.01 second precision, the LRS shall not reject the request but may truncate the “duration” property to 0.01 second precision.
• When making a comparison (e.g. as a part of the statement signing process) of Statements in regard to a Duration, any precision beyond 0.01 second precision shall not be included in the comparison.

Documents:

Note that the following table shows generic properties, not a JSON Object as many other tables in this specification do. The id is stored in the IRL, “updated” is HTTP header information, and “contents” is the HTTP document itself (as opposed to an Object).

5. Content - Learning Record Providers (LRPs) and Learning Record Consumers (LRCs)

5.1 LRP and LRC Communication

LRPs and LRCs interact with an LRS via RESTful HTTP methods to the resources outlined in this section. The primary function of LRPs and LRCs within the xAPI is to create valid Requests to the LRS. All tables in this section are redundant with those listed in Section 4.1 LRS Communication, but are listed here as context such that LRPs can understand what the LRS supports. This section does include LRP requirements that are not seen in Section 4.1.

The following table summarizes the Resources with which HTTP methods can interact. Details for what an LRP can expect can be found within Section 4.1.6 Resources.

5.1.1 Headers

The LRP is allowed to use the following headers as described in this document.

• Accept
• Accept-Encoding
• Accept-Language
• Authorization
• Content-Type
• Content-Length
• Content-Transfer-Encoding
• If-Match
• If-None-Match
• X-Experience-API-Version

5.1.2 Encoding

All strings shall be encoded and interpreted as UTF-8 (RFC 3629).

5.1.3 Content Types

Requests and responses within this specification normally use an application/json content type. Exceptions to this are:

• Documents can have any content type.
• Statement requests that can sometimes include Attachments use the multipart/mixed content type.

Application/JSON

The application/json content type is used for all requests that do not otherwise specify a content type.

Multipart/Mixed

The multipart/mixed content type is used for requests that could include Attachments. This does not mean that all “multipart/mixed” requests necessarily do include Attachments.

Procedure For The Exchange Of Attachments

• A Statement request including zero or more Attachments is construed in accordance with requirements in this document.
• The Statement is sent using a Content-Type of multipart/mixed. Any Attachments are placed at the end of such transmissions.
• The LRS decides whether to accept or reject the Statement based on the information in the first part.
• If it accepts the request, it can match the raw data of an Attachment(s) with the Attachment header by comparing the SHA-2 (FIPS PUB 180-2) of the raw data to the SHA-2 declared in the header. It shall not do so any other way.

Requirements for Attachment Statement Batches

A request transmitting a Statement batch, Statement results, or single Statement that includes Attachments shall satisfy one of the following criteria:

• It shall be of type application/json and include a fileUrl for every Attachment EXCEPT for Statement results when the “attachments” filter is false.
• It shall conform to the definition of “multipart/mixed” in RFC 2046 and:
  • The first part of the multipart document shall contain the Statements themselves, with type application/json.
  • Each additional part contains the raw data for an Attachment and forms a logical part of the Statement. This capability shall be available when issuing PUT or POST requests against the Statement Resource.
  • shall include an X-Experience-API-Hash parameter in each part's header after the first (Statements) part.
  • shall include a Content-Transfer-Encoding parameter with a value of binary in each part's header after the first (Statements) part.
  • should only include one copy of an Attachment's data when the same Attachment is used in multiple Statements that are sent together.
  • should include a Content-Type parameter in each part's header. For the first part (containing the Statement) this shall be application/json.
  • Where parameters have a corresponding property within the attachment Object and both the parameter and property are specified for a given Attachment, the value of these parameters and properties shall match.

Learning Record Provider Requirements

• A Learning Record Provider may send Statements with Attachments as described above.
• A Learning Record Provider may send multiple Statements where some or all have Attachments if using POST.
• A Learning Record Provider may send batches of type application/json where every attachment Object has a fileUrl, ignoring all requirements based on the “multipart/mixed” format.
• A Learning Record Provider should use SHA-256, SHA-384, or SHA-512 (FIPS PUB 180-2) to populate the “sha2” property.

File URL

The File URL is intended to provide a location from which the Attachment can be received. There are, however, no requirements for the owner of the Attachment to make the Attachment data available at the location indefinitely or to make the Attachment publicly available without security restrictions. When determining Attachment hosting arrangements, those creating Statements using the “fileUrl” property are encouraged to consider the needs of end recipient(s) of the Statement, especially if the Attachment content is not included with the Statement.

The period of time an Attachment is made available for, and the security restrictions applied to hosted attachments, are out of scope of this specification.

5.1.4 Concurrency

Concurrency control makes certain that a PUT, POST or DELETE does not perform operations based on old data.

Details

xAPI uses HTTP 1.1 entity tags (ETags) to implement optimistic concurrency control in the following resources, where PUT, POST or DELETE are allowed to overwrite or remove existing data:

• State Resource
• Agent Profile Resource
• Activity Profile Resource

Requirements

• As LRP making a PUT request to the State Resource, Agent Profile Resource or Activity Profile Resource shall include the “If-Match” header or the If-None-Match header.
• An LRP making a POST request to the State Resource, Agent Profile Resource or Activity Profile Resource shall include the “If-Match” header or the If-None-Match header.
• An LRP making a DELETE request to the State Resource, Agent Profile Resource or Activity Profile Resource shall include the “If-Match” header.
• An LRP shall use the ETag value provided by the LRS rather than calculating it themselves.

5.1.5 Error Codes

The list below covers many error conditions that could be returned from various methods in the API.

• 400 Bad Request - Indicates an error condition caused by an invalid or missing argument. The term “invalid arguments” includes malformed JSON (RFC 8259) or invalid Object structures.
• 401 Unauthorized - Indicates that authentication is required, or in the case authentication has been posted in the request, that the given credentials have been refused.
• 403 Forbidden - Indicates that the request is unauthorized for the given credentials. Note this is different than refusing the credentials given. In this case, the credentials have been validated, but the authenticated system is not allowed to perform the given action.
• 404 Not Found - Indicates the requested resource was not found. May be returned by any method that returns a uniquely identified resource, for instance, any State, Agent Profile, or Activity Profile Resource request targeting a specific document, or the method to retrieve a single Statement.
• 409 Conflict - Indicates an error condition due to a conflict with the current state of a resource, in the case of State Resource, Agent Profile Resource or Activity Profile Resource requests, or in the Statement Resource PUT or POST calls.
• 412 Precondition Failed - Indicates an error condition due to a failure of a precondition posted with the request, in the case of State or Agent Profile or Activity Profile API requests.
• 413 Request Entity Too Large - Indicates that the LRS has rejected the Statement or document because its size (or the size of an Attachment included in the request) is larger than the maximum allowed by the LRS.
• 429 Too Many Requests - Indicates that the LRS has rejected the request because it has received too many requests from the system or set of credentials in a given amount of time.
• 500 Internal Server Error - Indicates a general error condition, typically an unexpected exception in processing on the server.

Requirements

• A Learning Record Provider should send an “Accept” header with requests to enable content negotiation.

5.1.6 LRS Resources

Each LRS Resource is described in Section 5.1.6. Each Resource has requirements for each of the HTTP methods that may be made to it. Each section includes the expected contents of the body of the request, the request parameters, and the expected returns. If an HTTP method is not described, it is out of scope of this document.

LRPs leverage both Statements and documents as data structures. An LRP may interact with any of the resources described in this section.

• A Learning Record Provider may send documents to any of the Document Resources for Activities and Agents that the LRS does not have prior knowledge of.

Note: In all of the examples in this specification, http://example.com/xAPI/ is the example base endpoint (resource location) of the LRS. All other IRI syntax after this represents the particular resource used.

5.1.6.1 Statement Resource (/statements)

Statements are the key data structure of xAPI. This resource facilitates their storage and retrieval.

Example resource location/endpoint: http://example.com/xAPI/statements

PUT Request:

Summary: Stores a single Statement with the given id.

Body: The Statement object to be stored.

Returns: 204 No Content

Learning Record Provider Requirements

• Learning Record Providers should POST Statements including the Statement “id” property instead of using PUT.
• When PUTing Statements, the “id” property of the Statement should be used.
• Where provided, the “id” property of the Statement shall match the “statementId” parameter of the request.

POST Request:

Summary: Stores a Statement, or a set of Statements.

Body: An array of Statements or a single Statement to be stored.

Returns: 200 OK, Array of Statement id(s) (UUID) in the same order as the corresponding stored Statements

GET Request:

Summary: Fetches a single Statement or multiple Statements. If the statementId or voidedStatementId parameter is specified a single Statement is returned. Otherwise, a StatementResult Object, a list of Statements in reverse chronological order based on “stored” time, subject to permissions and maximum list length. If additional results are available, an IRL to retrieve them is included in the StatementResult Object.

        <br><br>See <a href="#5221-actor">agent/group</a> Object definition for details. </td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row4"> <td>verb</td> <td>Verb id (IRI)</td> <td> </td> <td>Filter, only return Statements matching the specified Verb id.</td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row5"> <td>activity</td> <td>Activity id (IRI)</td> <td> </td> <td> Filter, only return Statements for which the Object of the Statement is an Activity with the specified id. </td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row6"> <td>registration</td> <td>UUID</td> <td> </td> <td> Filter, only return Statements matching the specified registration id. Note that although frequently a unique registration is used for one Actor assigned to one Activity, this cannot be assumed. If only Statements for a certain Actor or Activity are required, those parameters also need to be specified. </td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row7"> <td>related_activities</td> <td>Boolean</td> <td>false</td> <td> Apply the Activity filter broadly. Include Statements for which the Object, any of the  context Activities, or any of those properties in a contained SubStatement match the Activity parameter, instead of that parameter's normal behavior. Matching is defined in the same way it is for the "activity" parameter. </td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row8"> <td>related_agents</td> <td>Boolean</td> <td>false</td> <td> Apply the Agent filter broadly. Include Statements for which the Actor, Object, Authority, Instructor, Team, Context Agent, Context Group, or any of these properties in a contained SubStatement match the Agent parameter, instead of that parameter's normal behavior. Matching is defined in the same way it is for the "agent" parameter. </td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row9"> <td>since</td> <td>Timestamp</td> <td> </td> <td>Only Statements stored since the specified Timestamp (exclusive) are returned.</td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row10"> <td>until</td> <td>Timestamp</td> <td> </td> <td>Only Statements stored at or before the specified Timestamp are returned.</td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row11"> <td>limit</td> <td>Nonnegative Integer</td> <td>0</td> <td> Maximum number of Statements to return. 0 indicates return the maximum the server allows. </td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row12"> <td>format</td> <td>String: (<code>ids</code>, <code>exact</code>, or <code>canonical</code>)</td> <td>exact</td> <td>If <code>ids</code>, only include minimum information necessary in Agent, Activity, Verb and Group Objects to identify them. For Anonymous Groups this means including the minimum information needed to identify each member. <br/><br/> If <code>exact</code>, return Agent, Activity, Verb and Group Objects populated exactly as they were when the Statement was received. An LRS requesting Statements for the purpose of importing them would use a format of "exact" in order to maintain <a href="#statement-immutability">Statement Immutability</a>. <br/><br/> If <code>canonical</code>, return Activity Objects and Verbs populated with the canonical definition of the Activity Objects and Display of the Verbs as determined by the LRS, after applying the language filtering process defined below, and return the original Agent and Group Objects as in "exact" mode. </td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row13"> <td>attachments</td><td>Boolean</td><td>false</td> <td>If <code>true</code>, the LRS uses the multipart response format and includes all attachments as described previously.  If <code>false</code>, the LRS sends the prescribed response with Content-Type application/json and does not send attachment data.</td> <td>Optional</td> </tr> <tr id="2.1.3.s1.table1.row14"> <td>ascending</td> <td>Boolean</td> <td>false</td> <td>If <code>true</code>, return results in ascending order of stored time</td> <td>Optional</td> </tr>

Body: None.

Returns: 200 OK, Statement or Statement Result

Note: The values of Boolean parameters are represented as true or false as in JSON.

Voided Statements

This section describes how voided Statements are handled by the LRS when queried via a GET request.

Learning Record Providers can identify the presence and Statement id of any voided Statements by the target of the voiding Statement.

5.1.6.2 State Resource (/activities/state)

Generally, this is a scratch area for Learning Record Providers that do not have their own internal storage, or need to persist state across devices. The State Resource is a place to store information about the state of an activity in a generic form called a document. The intent of this resource is to store/retrieve a specific agent's data within a specific activity, potentially tied to a registration.

The semantics of the LRS response are driven by the presence of a “stateId” parameter. If it is included, the GET and DELETE methods shall act upon a single defined state document identified by “stateId”. Otherwise, GET returns the available ids, and DELETE deletes all state in the context given through the other parameters. This resource has concurrency controls associated with it.

Example resource location/endpoint: http://example.com/xAPI/activities/state

PUT Request:

Summary: Stores a single document with the given id.

Body: The document object to be stored.

Returns: 204 No Content

POST Request:

Summary: Updates/stores a single document with the given id.

Body: The document object to be stored/updated.

Returns: 204 No Content

• If a Learning Record Provider needs to delete a property, it should use a PUT request to replace the whole document.

(Single Document) GET Request:

Summary: Fetches a single document with the given id.

Body: None.

Returns: 200, The State Document

(Single Document) DELETE Request:

Summary: Deletes a single document with the given id.

Body: None.

Returns: 204 No Content

(Multiple Document) GET Request:

Summary: Fetches State ids of all state data for this context (Activity + Agent [+ registration if specified]). If “since” parameter is specified, this is limited to entries that have been stored or updated since the specified timestamp (exclusive).

Body: None.

Returns: 200, Array of State ids

(Multiple Document) DELETE Request:

Summary: Deletes all state data for this context (Activity + Agent [+ registration if specified]).

Body: None.

Returns: 204 No Content

5.1.6.3 Agents Resource (/agents)

The Agents Resource provides a method to retrieve a special Object with combined information about an Agent derived from an outside service, such as a directory service. This object is called a “Person Object”. The Person Object is very similar to an Agent Object, but instead of each attribute having a single value, each attribute has an array value, and it is legal to include multiple identifying properties. This is different from the FOAF concept of person, person is being used here to indicate a person-centric view of the LRS Agent data, but Agents just refer to one persona (a person in one context).

Example resource location/endpoint: http://example.com/xAPI/agents

GET Request:

Summary: Return a Person Object for a specified Agent.

Body: None.

Returns: 200 OK, Person Object

Person Object Table:

• All array properties shall be populated with members with the same definition as the similarly named property from Agent Objects.

5.1.6.4 Activities Resource (/activities)

The Activities Resource provides a method to retrieve a full description of an Activity from the LRS.

Example resource location/endpoint: http://example.com/xAPI/activities

GET Request:

Summary: Fetches the complete Activity Object specified.

Body: None.

Returns: 200 OK, Content

5.1.6.5 Agent Profile Resource (/agents/profile)

A place to store information about an Agent in a generic form called a document. This information is not tied to an activity or registration. The semantics of the LRS response are driven by the presence of a “profileId” parameter. If it is included, the GET and method acts upon a single defined profile document identified by “profileId”. Otherwise, GET returns the available ids given through the other parameter. This resource has concurrency controls associated with it.

Example resource location/endpoint: http://example.com/xAPI/agents/profile

PUT Request:

Summary: Stores a single document with the given id.

Body: The document to be stored.

Returns: 204 No Content

• An LRP making a PUT request to this resource shall include the “If-Match” header or the If-None-Match header.

POST Request:

Summary: Stores/updates a single document with the given id.

Body: The document to be stored/updated.

Returns: 204 No Content

• If a Learning Record Provider needs to delete a property, it should use a PUT request to replace the whole document.
• An LRP making a POST request to this resource shall include the “If-Match” header or the If-None-Match header.

DELETE Request:

Summary: Deletes a single document with the given id.

Body: None.

Returns: 204 No Content

• An LRP making a DELETE request to this resource shall include the “If-Match” header.

(Single Document) GET Request:

Summary: Fetches a single document with the given id.

Body: None.

Returns: 200 OK, the Profile document

(Multiple Document) GET Request:

Summary: Fetches Profile ids of all Profile documents for an Agent. If “since” parameter is specified, this is limited to entries that have been stored or updated since the specified Timestamp (exclusive).

Body: None.

Returns: 200 OK, Array of profileIds.

5.1.6.6 Activity Profile Resource (/activities/profile)

A place to store information about an Activity in a generic form called a document. This information is not tied to an Actor or registration. The semantics of the LRS response are driven by the presence of a “profileId” parameter. If it is included, the GET and method shall act upon a single defined profile document identified by “ProfileId”. Otherwise, GET returns the available ids given through the other parameter. This resource has concurrency controls associated with it.

Example resource location/endpoint: http://example.com/xAPI/activities/profile

PUT Request:

Summary: Stores a single document with the given id.

Body: The document to be stored.

Returns: 204 No Content

• An LRP making a PUT request to this resource shall include the “If-Match” header or the If-None-Match header.

POST Request:

Summary: Stores/updates a single document with the given id.

Body: The document to be stored/updated.

Returns: 204 No Content

• If a Learning Record Provider needs to delete a property, it should use a PUT request to replace the whole document.
• An LRP making a POST request to this resource shall include the “If-Match” header or the If-None-Match header.

DELETE Request:

Summary: Deletes a single document with the given id.

Body: None.

Returns: 204 No Content

• An LRP making a DELETE request to this resource shall include the “If-Match” header.

(Single Document) GET Request:

Summary: Fetches a single document with the given id.

Body: None.

Returns: 200 OK, the Profile document

(Multiple Document) GET Request:

Summary: Fetches Profile ids of all Profile documents for an Activity. If “since” parameter is specified, this is limited to entries that have been stored or updated since the specified Timestamp (exclusive).

Body: None.

Returns: 200 OK, Array of profileIds.

5.1.6.7 About Resource (/about)

Returns JSON Object containing information about this LRS, including supported extensions and xAPI version(s).

Example resource location/endpoint: http://example.com/xAPI/about

GET Request:

Body: None.

Returns: 200 OK, JSON object containing basic metadata about this LRS

5.1.7 Versioning

Using Semantic Versioning allows LRPs to remain interoperable as the specification changes.

Every request to the LRS and every response from the LRS shall include an HTTP header with the name X-Experience-API-Version and the version as the value. For example, X-Experience-API-Version: 2.0.0 for version 2.0.0;

LRP Requirements

• The LRP shall include the “X-Experience-API-Version” header in every request.
• The LRP shall set this header to the latest patch version.

5.1.8 Authentication

In order to support the varying security requirements of different environments, a specific authentication mechanism is not defined.

5.1.9 Security

Security is beyond the scope of this document and left to the individual LRS provider as an implementation detail. Implementors are encouraged to follow industry best practices, e.g., The HTTPS-Only Standard from the office of the White House CIO.

It is possible that security concerns may arise in the implementation of this specification, and implementers might choose to break a conformance requirement for the sake of security. In these cases, implementers are encouraged to consider both the security and interoperability implications of their implementation decisions.

5.2 LRP Data Requirements

The LRP is responsible for creation of various data formats described in this document. The most common data format in xAPI is the Statement.

An LRP shall not use a property in a Statement more than one time

The required field in each of these tables dictates the LRP responsibility in creating data. Required indicates the LRP shall include this property in the format supplied. Recommended indicates that the LRP should create the property, many of which are set by the LRS if not provided. Optional indicates that the field may be used by an LRP, but the LRS takes no default responsibility if it is not provided. Not Recommended indicates that the LRP should not use this property and instead the LRS should populate the value.

Statement Immutability:

Statements are inevitably stored in databases. While the methods to PUT/POST and GET them are specific, the storage mechanism is not. JSON has flexibility in form, which means that a reconstruction may not be exact, ordering being a very common example. This document defines only certain aspects of Statements to be immutable. For all intents and purposes, if immutability required fields are equal, then the Statements are equal.

• The following properties are immutable
  • Actor (except the ordering of group members)
  • Verb (except for display)
  • Object
  • Duration (see section on Duration for further requirements)
• The following properties are not immutable
  • Case
  • Id
  • Order of any Group Members
  • Authority
  • Stored
  • Timestamp
  • Version
  • Any attachments
  • Any referenced Activity Definitions

5.2.1 Table Guidelines

Tables in this document represent requirements that shall be followed. It is the responsibility of an LRP to create Statements and requests that contain data that follow requirements in these tables. The following requirements are expected to be followed for each table in this section. Note: The “description” portion of table contains requirements, in particular for controlled vocabulary, enumerations, etc.

An LRP shall not add additional properties to Statements

An LRP shall not use a property more than once

The LRP shall create Statements:

• With all required properties
• Without any null values (except inside extensions).
• Following all formatting of the data type provided
• Following format of key or value, including not providing an empty string, where a string with a particular format (such as mailto IRI, UUID, or IRI) is required.
• Where the case of a key does match the case specified in this specification.
• Where the case of a value restricted to enumerated values matches an enumerated value given in this specification exactly.
• Which do not have a key or value that is not allowed by this specification.
• That contain IRL or IRI values with a scheme.

5.2.2 Statement

Each Statement in xAPI has the following JSON structure and requirements. Note that properties with type “Object” are detailed in subsequent tables.

5.2.2.1 Actor

Actors can take on the form of either Groups or Agents. Groups can be identified, and if they are not, are considered to be anonymous groups. Specific requirements are found in the tables below.

Actor as Agent Table: An actor property that implements an Agent has the following JSON structure and requirements:

Actor as Anonymous Group Table: An actor property that represents an Anonymous Group shall adhere to the requirements in the following table.

Actor as Identified Group Table: An actor property that implements an Identified Group shall adhere to the requirements in the following table.

Account Table: Actors (Agents and Groups, including when they are Objects) may use the Account Object (as demonstrated in previous tables). If used, the properties of that Account Object are:

5.2.2.2 Verb

Verbs appear in Statements as Objects consisting of an IRI and a set of display names corresponding to multiple languages or dialects which provide human-readable meanings of the Verb. The table below lists all properties of the Verb Object.

5.2.2.3 Object

Objects in xAPI vary widely in use and are classified in that use by the objectType property. Each of the following sections provides additional requirements that stem from the use of objectType. That is, if an Object is to be used as an Activity, its objectType shall be “Activity”.

Object As Activity Table: The format for an Activity Object is described in the table below:

Activity Definition (referenced in Object as Activity) Table: All properties are optional, but if implemented include requirements described below.

Interaction Activities (referenced in Activity Definition) Table: The format for Interaction Activities is described in the table below:

Interaction Types (referenced in Interaction Activities Table): The interactionType is controlled vocabulary. Based on the term used, the data formatting and purpose changes according to the following table.

The Correct Responses Pattern contains an array of response patterns. A learner's response is be considered correct if it matches any of the response patterns in that array. Where a response pattern is a delimited list, the learner's response is only considered correct if all of the items in that list match the learner's response.

Characterstring parameters

Some of the values within the responses described above can be prepended with certain additional parameters. These parameters are represented by the format {parameter=value}.

Characterstring parameters are not validated by the LRS. Systems interpreting Statement data can use their best judgement in interpreting (or ignoring) invalid characterstring parameters and values.

The following parameters are valid at the start of the string representing the list of items for the listed interaction types:

The following parameters are valid at the start of each item in the list for the listed interaction types:

Interaction Components, Expanded (part of the Interaction Activities Table): Depending on interactionType, Interaction Activities can take additional properties, each containing a list of interaction components. These additional properties are called “interaction component lists”. The following table shows the supported interaction component list(s) for an Interaction Activity with the given interactionType.

Regardless of interactionType, each Component List has the following additional properties:

Object As Actor Table: The table below lists all properties of an Actor Object

Object As Statement Table: The table below lists all properties of a Statement Reference Object

Object As Sub-Statement Table: The table below lists all properties of a Sub-Statement Object

5.2.2.4 Result

Represents a measured outcome related to the Statement in which it is included.

Result Table: The table below lists all properties of the Result Object.

Score Table: Represents the outcome of a graded Activity achieved by an Agent. The table below lists all properties of the Score Object.

5.2.2.5 Context

Property to add contextual information to a Statement. It can store information such as the instructor for an experience, if this experience happened as part of a team-based Activity, or how an experience fits into some broader activity.

Context Table: The table below lists all properties of the context Object.

Note: With the addition of context agents and context groups, it is recommended not to use instructor or team. They are supported in this document for backward compatibility purposes.

Context Agents and Groups Details:

A single Statement may require the inclusion of many contextually relevant Agent(s) and/or Group(s) in order to properly describe an experience. When this is the case, the relationship between the Agent(s) and/or Group(s) and the Statement itself needs to be represented in a structured manner. The context properties contextAgents and contextGroups serve as this structure.

• Inclusion of contextAgents within a Statement establishes that a relationship exists between said Statement and one or more Agent(s)
• Inclusion of contextGroups within a Statement establishes that a relationship exists between said Statement and one or more Group(s)
• Zero or more Activity Types are used to categorize each Statement specific relationship
• Each Statement specific relationship corresponds to an individual contextAgents or contextGroups Object

The relationship established by each contextAgents and contextGroups Object is limited in scope to the Statement in which the Object is found. In general, an Agent many have permanent characteristics, characteristics which are consistent across experiences, but these kinds of Agent specific properties should be captured in an Agent Profile

All Objects found within the contextAgents and/or contextGroups array(s) are independent of one another.

Context Agents Table:

Each contextAgent Object found within a contextAgents array has the following properties:

• Any and All valid Agent Objects can be used as the agent within a contextAgent Object.
• An Agent Object does not need to be found within any other Statement property in order to be included as the agent property within a contextAgent Object.
• Any and All valid Activity Type IRIs can be included within the relevantTypes array of a contextAgent Object.
• An Activity Type IRI does not need to be found within any other Statement property in order to be included within the relevantTypes property of a contextAgent Object

Context Group Table:

Each contextGroup Object found within a contextGroups array has the following properties:

• Any and All valid Group Objects can be used as the group within a contextGroup Object
• A Group Object does not need to be found within any other Statement property in order to be included as the group property within a contextGroup Object.
• Any and All valid Activity Type IRIs can be included within the relevantTypes array of a contextAgent Object.
• An Activity Type IRI does not need to be found within any other Statement property in order to be included within the relevantTypes property of a contextAgent Object

5.2.2.6 Attachments

In some cases an Attachment is logically an important part of a Learning Record. It could be an essay, a video, etc. Another example of such an Attachment is (the image of) a certificate that was granted as a result of an experience.

Attachments Table: The table below lists all properties of the attachments Object.

5.2.3 Metadata

Metadata is additional information about a resource. It enables decision making, search, and discoverability. In xAPI, metadata can be utilized essentially in two ways.

First, metadata is used in the definition property of an Activity Object (the Object when the objectType is Activity). In this case, the metadata is part of the Statement. Other fields, including extensions, can be used as metadata in a similar regard. Including metadata in a Statement allows metadata about the IRI to be expressed without the necessity of resolving it.

Second, metadata may be hosted. In this case, additional information about an identifier can be provided within a Statement and can be hosted at the location pointed to by the identifier IRI. Hosting metadata at the IRI location allows the owner of the IRI to define the canonical metadata for that IRI. This is the main purpose for which IRIs are used in xAPI.

All hosted metadata, including the format, is optional. However, it is recommended that the Activity Definition Object metadata is followed for hosted Activity identifiers.

For the structure of metadata about all other identifiers, see the format below:

Hosted metadata consists of a document containing a JSON object as described above. If this hosted metadata is provided, it is the canonical source of information about the identifier it describes.

5.2.3.1 Learning Record Provider Recommendations

The following recommendations are made for any LRP that wishes to implement resolvable metadata for querying purposes.

• Metadata may be provided with an identifier.
• If metadata is provided, both “name” and “description” should be included.
• For any of the identifier IRIs above the Metadata Provider should make a human-readable description of the intended usage accessible at the IRI.
• For any of the identifier IRIs above the Metadata Provider should ensure that this JSON metadata available at that IRI when the IRI is requested and a Content-Type of application/json is requested.
• Where the IRI represents an Activity, the Metadata Provider may host metadata using the Activity Definition JSON format which is used in Statements, with a Content-Type of application/json.

5.2.4 LRP Processing of Data

An LRP functions as the creator of xAPI Data. Statements, in particular, are highly structured and have many requirements. An LRP is responsible for formatting and sending statements such that they do not get rejected by the LRS, and otherwise follow Data Design Best Practices

Statements are expected to be unique and to be immutable. In this regard they are unchangeable and should not be deleted. This section outlines requirements that focus on specific practices that are unique to certain Statement properties.

5.2.4.1 LRP Statement Best Practices

Some of the requirements in this section are covered in the tables above but are explained in more detail below or are listed again to reiterate best practices.

• An LRP should provide an id for the Statement
• An LRP should not provide a stored for the Statement
• An LRP should not provide authority for the Statement
• An LRP should not provide a version for the Statement
• If an LRP sets the Statement version, it shall set it to 2.0.0.
• An LRP should not include properties with a value of an empty object
• The Learning Record Provider should ensure that every value in the contextActivities Object is an array of Activity Objects instead of a single Activity Object
• A Learning Record Provider shall not use a future time for a “timestamp” property in a Statement.
• An LRP may create a Statement where a SubStatement has a “timestamp” property that is in the future.
• The LRP shall not create a Statement with an Object with ObjectType SubStatement that has within it an Object with ObjectType SubStatement.
• An LRP should not provide an interaction component's id value with whitespace in the value.
• The LRP shall not provide a “language” property with invalid values for any reason, including if not applicable or unknown.

5.2.5 Statement Voiding

Not all Statements are perpetually valid once they have been issued. Mistakes or other factors could dictate that a previously made Statement is marked as invalid. This is called “voiding a Statement” and the reserved Verb http://adlnet.gov/expapi/verbs/voided is used for this purpose. Any Statement that voids another cannot itself be voided.

An LRP shall not send a Statement with the Verb http://adlnet.gov/expapi/verbs/voided when:

• The Statement's Object's objectType property is not “StatementRef”
• The Statement has no “id” for the Object (e.g. no target for voiding)

5.2.6 Statement Signing

A Statement can include a digital signature to provide strong and durable evidence of the authenticity and integrity of the Statement.

Signed Statements include a JSON web signature (JWS) as an Attachment. This allows the original serialization of the Statement to be included along with the signature. For interoperability, the “RSA + SHA” series of JWS algorithms have been selected, and for discoverability of the signer X.509 certificates should be used.

Statement Signing Process:

• A Signed Statement shall include a JSON web signature (JWS) as defined here: http://tools.ietf.org/html/rfc7515, as an Attachment with a usageType of http://adlnet.gov/expapi/attachments/signature and a contentType of application/octet-stream.
• JWS Compact Serialization shall be used to create the JSON web signature. Use of JWS JSON Serialization is strongly discouraged, is unlikely to be interoperable with other systems, and will be forbidden in a future version of this specification.
• The JWS signature shall have a payload of a valid JSON serialization of the complete Statement before the signature was added.
• The JWS signature shall use an algorithm of “RS256”, “RS384”, or “RS512”.
• The JWS signature should have been created based on the private key associated with an X.509 certificate.
• If X.509 was used to sign, the JWS header should include the “x5c” property containing the associated certificate chain.

5.2.7 Additional Requirements for Data Types

The following section provides guidance and requirements for data types found in this document. Many tables contain specific data types that have requirements found in this section.

IRIs:

Internationalized Resource Identifiers, or IRIs, are unique identifiers which could also be resolvable. Because resolving is not a requirement, IRIs/URIs are used instead of IRLs/URLs. In order to allow the greatest flexibility in the characters used in an identifier, IRIs are used instead of URIs as IRIs can contain some characters outside of the ASCII character set.

The LRP has responsibilities in regard to each IRI as outlined below. Many of these are only best practices as they are not testable through software, but if not followed, undermine the use of xAPI in a larger environment. To put it another way, the should requirements carry the weight of a shall requirement.

• Learning Record Providers defining new IRIs should only use IRIs they control or have permission from the controller to use.

• Where a suitable identifier already exists, the LRP should use the corresponding existing identifier and _should__not_ create a new identifier.

• When re-using an existing identifier, Learning Record Providers should ensure that the exact character equivalent IRI is used.

• A Learning Record Provider may create their own identifiers where a suitable identifier does not already exist.

• When defining identifiers, the Learning Record Provider may use IRIs containing anchors so that a single page can contain definitions for multiple identifiers. E.g. http://example.com/xapi/verbs#defenestrated

• When defining identifiers, the LRP should use lowercase IRIs

Extensions:

Extensions are available as part of Activity Definitions, as part of a Statement's “context” property, or as part of a Statement's “result” property. In each case, extensions are intended to provide a natural way to extend those properties for some specialized use. The contents of these extensions might be something valuable to just one application, or it might be a convention used by an entire Community of Practice.

Extensions are defined by a map and logically relate to the part of the Statement where they are present. The values of an extension can be any JSON value or data structure. Extensions in the “context” property provide context to the core experience, while those in the “result” property provide elements related to some outcome. Within Activities, extensions provide additional information that helps define an Activity within some custom application or Community of Practice. The meaning and structure of extension values under an IRI key are defined by the person who controls the IRI.

• The keys of an extensions map shall be IRIs.
• Learning Record Providers should always strive to map as much information as possible into the built-in elements in order to leverage interoperability among Experience API conformant tools.
• All extension IRIs should have controllers.
• The controller of an IRL extension key should make a human-readable description of the intended meaning of the extension supported by the IRL accessible at the IRL.

Language Maps:

A language map is a dictionary where the key is an RFC 5646 Language Tag, and the value is a string in the language specified in the tag. This map should be populated as fully as possible based on the knowledge of the string in question in different languages.

The shortest valid language code for each language string is generally preferred. The ISO 639 language code plus an ISO 3166-1 country code allows for the designation of basic languages (e.g., es for Spanish) and regions (e.g., es-MX, the dialect of Spanish spoken in Mexico). If only the ISO 639 language code is known for certain, do not guess at the possible ISO 3166-1 country code. For example, if only the primary language is known (e.g., English) then use the top-level language tag en, rather than en-US. If the specific regional variation is known, then use the full language code.

Note: For Chinese languages, the significant linguistic diversity represented by zh means that the ISO 639 language code is generally insufficient.

The content of strings within a language map is plain text. It is expected that any formatting code such as HTML tags or markdown is not rendered but displayed as code when this string is displayed to an end user. An important exception to this is if language map Object is used in an extension and the owner of that extension IRI explicitly states that a particular form of code is to be rendered.

An LRP shall only send a Statement with invalid RFC 5646 language tags (Keys of language maps shall be sent with valid RFC 5646 language tags, for similar reasons, The LRS shall at least validate that the sequence of token lengths for language map keys matches the RFC 5646 standard)

UUIDs:

Universally Unique Identifiers, or UUIDs, are 128-bit values that are globally unique. Unlike IRIs, there is no expectation of resolvability as UUIDs take on a completely different format. UUIDs shall be in the standard string form. It is recommended variant 2 in RFC 4122 is used.

Timestamps:

• A Timestamp shall be formatted according to ISO 8601.
• A Timestamp shall be expressed using the format described in RFC 3339, which is a profile of ISO 8601.
• A Timestamp shall be formatted to UTC
• If used, An LRP should send a Timestamp with at least millisecond precision (3 decimal points beyond seconds).

Duration:

• An LRP shall provide Statements with Duration expressed using the format for Duration in ISO 8601:2004(E) section 4.4.3.2.
• An LRP shall not provide Statements with the alternative format (in conformity with the format used for time points and described in ISO 8601:2004(E) section 4.4.3.3).
• Learning Record Providers should provide a maximum precision of 0.01 seconds.
• Learning Record Providers may provide less precision, for example in the case of reading a University Degree precision might be in months or years.
• When comparing Durations (or Statements containing them), any precision beyond 0.01 second precision shall not be included in the comparison.

Documents:

Note that the following table shows generic properties, not a JSON Object as many other tables in this specification do. The id is stored in the IRL, “updated” is HTTP header information, and “contents” is the HTTP document itself (as opposed to an Object).