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¶
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.
Examples of the resources and data requirements can be found at https://opensource.ieee.org/xapi/xapi-base-standard-examples.
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.
| Base Resource IRI/URL of the LRS Precedes Each Entry | Function | Supported Calls |
|---|---|---|
| statements | Statement Storage/Retrieval | PUT, POST, GET,HEAD |
| agents | Agent Object Storage/Retrieval | GET, HEAD |
| agents/profile | Agent Profile Resource | PUT, POST, GET, HEAD, DELETE |
| activities | Activity Object Storage/Retrieval | GET, HEAD |
| activities/profile | Activity Profile Resource | PUT, POST, GET, HEAD, DELETE |
| activities/state | State Resource | PUT, POST, GET, DELETE, HEAD |
| about | LRS Information | GET, HEAD |
| extensions/"yourext" | Any Additional Resource Not Identified in this Document | Not specified |
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.
For Groups, it is only necessary to provide enough information for the LRS to construct the IFI of the Agent object. In the case of an Identified Group, the array of members does not contribute to the IFI and may be omitted (If the array of members is included, the LRS will ignore the members and only use the IFI for comparison purposes).
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.
Examples of the resources can be found at https://opensource.ieee.org/xapi/xapi-base-standard-examples.
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.
| Parameter | Type | Default | Description | Required |
|---|---|---|---|---|
| statementId | String | Id of Statement to record | Required |
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.
| Parameter | Type | Default | Description | Required |
|---|---|---|---|---|
| statementId | String | Id of Statement to fetch | Optional | |
| voidedStatementId | String | Id of voided Statement to fetch. see Voided Statements | Optional | |
| agent | Agent or Identified Group Object (JSON) | Filter, only return Statements for which the specified Agent or Group is
the Actor or Object of the Statement.
See agent/group Object definition for details. |
Optional | |
| verb | Verb id (IRI) | Filter, only return Statements matching the specified Verb id. | Optional | |
| activity | Activity id (IRI) | Filter, only return Statements for which the Object of the Statement is an Activity with the specified id. | Optional | |
| registration | UUID | 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. | Optional | |
| related_activities | Boolean | false | 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. | Optional |
| related_agents | Boolean | false | 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. | Optional |
| since | Timestamp | Only Statements stored since the specified Timestamp (exclusive) are returned. | Optional | |
| until | Timestamp | Only Statements stored at or before the specified Timestamp are returned. | Optional | |
| limit | Nonnegative Integer | 0 | Maximum number of Statements to return. 0 indicates return the maximum the server allows. | Optional |
| format | String: (ids, exact, or canonical) |
exact | If ids, 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.
If exact, 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
Statement Immutability.
If canonical, 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.
|
Optional |
| attachments | Boolean | false | If true, the LRS uses the multipart response format and includes all attachments as
described previously. If false, the LRS sends the prescribed response with Content-Type
application/json and does not send attachment data. |
Optional |
| ascending | Boolean | false | If true, return results in ascending order of stored time |
Optional |
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 or Identified Group'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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this state. | Required |
| registration | UUID | The registration associated with this state. | Optional |
| stateId | String | The id for this state, within the given context. | Required |
POST Request:¶
Summary: Updates/stores a single document with the given id.
Body: The document object to be stored/updated.
Returns: 204 No Content
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this state. | Required |
| registration | UUID | The registration associated with this state. | Optional |
| stateId | String | The id for this state, within the given context. | Required |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this state. | Required |
| registration | UUID | The registration associated with this state. | Optional |
| stateId | String | The id for this state, within the given context. | Required unless since parameter is present. In that case, Not Allowed. |
| since | Timestamp | Do not use for single document GET request. | Optional if stateId is not used. If the stateId parameter is included, Not Allowed. |
(Single Document) DELETE Request:¶
Summary: Deletes a single document with the given id.
Body: None.
Returns: 204 No Content
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this state. | Required |
| registration | UUID | The registration associated with this state. | Optional |
| stateId | String | The id for this state, within the given context. | Required |
(Multiple Document) GET Request:¶
Summary: Fetches State ids of all state data for this context (Activity + Agent (or Identified Group) [+ 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with these states. | Required |
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with these states. | Required |
| registration | UUID | The Registration associated with these states. | Optional |
| stateId | String | Do not use for Multiple Document GET request. | Required unless since parameter is present. In that case, Not Allowed. |
| since | Timestamp | Only ids of states stored since the specified Timestamp (exclusive) are returned. | Optional as long as stateId is not used. If the stateId parameter is included, Not Allowed. |
(Multiple Document) DELETE Request:¶
Summary: Deletes all state data for this context (Activity + Agent [+ registration if specified]).
Body: None.
Returns: 204 No Content
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with these states. | Required |
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with these states. | Required |
| registration | UUID | The Registration associated with these states. | Optional |
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
| Parameter | Type | Description | Required |
|---|---|---|---|
| agent | Agent object (JSON) | The Agent representation to use in fetching expanded Agent information. | Required |
Person Object Table:¶
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | Person | Required |
| name | Array of strings. | List of names of Agents retrieved. | Optional |
| mbox | Array of IRIs in the form "mailto:email address". | List of e-mail addresses of Agents retrieved. | Optional |
| mbox_sha1sum | Array of strings. | List of the SHA1 hashes of mailto IRIs (such as go in an mbox property). | Optional |
| openid | Array of strings. | List of openids that uniquely identify the Agents retrieved. | Optional |
| account | Array of account objects. | List of accounts to match. Complete account Objects (homePage and name) shall be provided. | Optional |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The id associated with the Activities to load. | Required |
5.1.6.5 Agent Profile Resource (/agents/profile)¶
A place to store information about an Agent or Identified Group 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
(Multiple Document) GET Request:¶
Summary: Fetches Profile ids of all Profile documents for an Agent or Identified Group. 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.
| Parameter | Type | Description | Required |
|---|---|---|---|
| agent | Agent or Identified Group Object (JSON) | The Agent or Identified Group associated with this Profile document. | Required |
| since | Timestamp | Only ids of Profiles stored since the specified Timestamp (exclusive) are returned. | Optional |
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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with this Profile document. | Required |
| profileId | String | The profile id associated with this Profile document. | Required |
(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.
| Parameter | Type | Description | Required |
|---|---|---|---|
| activityId | Activity id (IRI) | The Activity id associated with these Profile documents. | Required |
| since | Timestamp | Only ids of Profile documents stored since the specified Timestamp (exclusive) are returned. | Optional |
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
| Property | Type | Description | Required |
|---|---|---|---|
| version | Array of version strings | xAPI versions this LRS supports | Required |
| extensions | Object | A map of other properties as needed or supported additional resources (extensions) | Optional |
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.
Examples of the data requirements can be found at https://opensource.ieee.org/xapi/xapi-base-standard-examples.
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.
| Property | Type | Description | Required |
|---|---|---|---|
| id | UUID | UUID assigned by LRS if not set by the Learning Record Provider. | Recommended |
| actor | Object | Whom the Statement is about, as an Agent or Group Object. | Required |
| verb | Object | Action taken by the Actor. | Required |
| object | Object | Activity, Agent, or another Statement that is the Object of the Statement. | Required |
| result | Object | Result Object, further details representing a measured outcome. | Optional |
| context | Object | Context that gives the Statement more meaning. Examples: a team the Actor is working with, altitude at which a scenario was attempted in a flight simulator. | Optional |
| timestamp | Timestamp | Timestamp of when the events described within this Statement occurred. Set by the LRS if not provided. | Optional |
| stored | Timestamp | Timestamp of when this Statement was recorded. | Set by LRS |
| authority | Object | Agent or Group who is asserting this Statement is true. Verified by the LRS based on authentication. Set by LRS if not provided or if a strong trust relationship between the Learning Record Provider and LRS has not been established. | Optional |
| version | Version | The Statement's associated xAPI version, formatted according to Semantic Versioning 1.0.0. | Not Recommended |
| attachments | Ordered array of Attachment Objects | Headers for Attachments to the Statement | Optional |
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:
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | Value is "Agent". This property is optional except when the Agent is used as a Statement's object. | Optional (except when it is to be used in a Statement Object) |
| name | String | Full name of the Agent. | Optional |
| mbox | mailto IRI | The required format is "mailto:email address". Only email addresses uniquely assigned to this Agent, but no others, should be used for this property and mbox_sha1sum. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
| mbox_sha1sum | String | The hex-encoded SHA1 hash of a mailto IRI (i.e. the value of an mbox property). An LRS may include Agents with a matching hash when a request is based on an mbox. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
| openid | URI | An openID that uniquely identifies the Agent. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
| account | Object | A user account on an existing system e.g. an LMS or intranet. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
Actor as Anonymous Group Table: An actor property that represents an Anonymous Group shall adhere to the requirements in the following table.
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | Group. | Required |
| name | String | Name of the Group. | Optional |
| member | Array of Agent Objects | The members of this Group. This is an unordered list. | Required |
Actor as Identified Group Table: An actor property that implements an Identified Group shall adhere to the requirements in the following table.
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | Group. | Required |
| name | String | Name of the Group. | Optional |
| member | Array of Agent Objects | The members of this Group. This is an unordered list. | Optional |
| mbox | mailto IRI | The required format is "mailto:email address". Only email addresses uniquely assigned assigned to this Agent, but no others, should be used for this property and mbox_sha1sum. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
| mbox_sha1sum | String | The hex-encoded SHA1 hash of a mailto IRI (i.e. the value of an mbox property). An LRS may include Agents with a matching hash when a request is based on an mbox. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
| openid | URI | An openID that uniquely identifies the Agent. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
| account | Object | A user account on an existing system e.g. an LMS or intranet. | Exactly One of mbox, mbox_sha1sum, openid, account is required |
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:
| Property | Type | Description | Required |
|---|---|---|---|
| homePage | IRL | The canonical home page for the system the account is on. This is based on FOAF's accountServiceHomePage. | Required |
| name | String | The unique id or name used to log in to this account. This is based on FOAF's accountName. | Required |
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.
| Property | Type | Description | Required |
|---|---|---|---|
| id | IRI | Corresponds to a Verb definition. Each Verb definition corresponds to the meaning of a Verb, not the word. | Required |
| display | Language Map | The human readable representation of the Verb in one or more languages. This does not have any impact on the meaning of the Statement, but serves to give a human-readable display of the meaning already determined by the chosen Verb. | Recommended |
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:
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | shall be Activity when present | Required |
| id | IRI | An identifier for a single unique Activity | Required |
| definition | Object | Metadata | Optional |
Activity Definition (referenced in Object as Activity) Table: All properties are optional, but if implemented include requirements described below.
| Property | Type | Description | Required |
|---|---|---|---|
| name | Language Map | The human readable/visual name of the Activity | Recommended |
| description | Language Map | A description of the Activity | Recommended |
| type | IRI | The type of Activity. | Recommended |
| moreInfo | IRL | Resolves to a document with human-readable information about the Activity, which could include a way to launch the activity. | Optional |
| Interaction Activities | Object | Interaction definitions | Optional |
| extensions | Object | A map of other properties as needed | Optional |
Interaction Activities (referenced in Activity Definition) Table: The format for Interaction Activities is described in the table below:
| Property | Type | Description | Required |
|---|---|---|---|
| interactionType | String | The type of interaction. Possible values are: true-false, choice, fill-in, long-fill-in, matching, performance, sequencing, likert, numeric or other. | Required |
| correctResponsesPattern | Array of Strings | A pattern representing the correct response to the interaction. The structure of this pattern varies depending on the interactionType. This is detailed below. | Optional |
| choices, scale, source, target, or steps | Array of interaction components | Specific to the given interactionType (see below). | Optional |
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.
| interactionType | Description | Format |
|---|---|---|
| true-false | An interaction with two possible responses: true or false. | Either true or false |
| choice | An interaction with a number of possible choices from which the learner can select. This includes interactions in which the learner can select only one answer from the list and those where the learner can select multiple items. | A list of item ids delimited by [,]. If the response contains only one item, the delimiter shall not be used. |
| fill-in | An interaction which requires the learner to supply a short response in the form of one or more strings of characters. Typically, the correct response consists of part of a word, one word or a few words. "Short" means that the correct responses pattern and learner response strings are normally 250 characters or less. | A list of responses delimited by [,]. If the response contains only one item, the delimiter shall not be used. |
| long-fill-in | An interaction which requires the learner to supply a response in the form of a long string of characters. "Long" means that the correct responses pattern and learner response strings are normally more than 250 characters. | A list of responses delimited by [,]. If the response contains only one item, the delimiter shall not be used. |
| matching | An interaction where the learner is asked to match items in one set (the source set) to items in another set (the target set). Items do not have to pair off exactly and it is possible for multiple or zero source items to be matched to a given target and vice versa. | A list of matching pairs, where each pair consists of a source item id followed by a target item id. Items can appear in multiple (or zero) pairs. Items within a pair are delimited by [.]. Pairs are delimited by [,]. |
| performance | An interaction that requires the learner to perform a task that requires multiple steps. | A list of steps containing a step ids and the response to that step. Step ids are separated from responses by [.]. Steps are delimited by [,]. The response can be a String as in a fill-in interaction or a number range as in a numeric interaction. |
| sequencing | An interaction where the learner is asked to order items in a set. | An ordered list of item ids delimited by [,]. |
| likert | An interaction which asks the learner to select from a discrete set of choices on a scale | A single item id |
| numeric | Any interaction which requires a numeric response from the learner. | A range of numbers represented by a minimum and a maximum delimited by [:]. Where the range does not have a maximum or does not have a minimum, that number is omitted but the delimiter is still used. E.g. [:]4 indicates a maximum for 4 and no minimum. Where the correct response or learner's response is a single number rather than a range, the single number with no delimiter may be used. |
| other | Another type of interaction that does not fit into those defined above. | Any format is valid within this string as appropriate for the type of interaction. |
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:
| Parameter | Default | Description | Value | Interaction types |
|---|---|---|---|---|
| case_matters | false | Whether or not the case of items in the list matters. | true or false | fill-in, long-fill-in |
| order_matters | true | Whether or not the order of items in the list matters. | true or false | fill-in, long-fill-in, performance |
The following parameters are valid at the start of each item in the list for the listed interaction types:
| Parameter | Description | Value | Interaction types |
|---|---|---|---|
| lang | The language used within the item. | RFC 5646 Language Tag | fill-in, long-fill-in, performance (String responses only) |
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.
| interactionType | Interaction Component Lists | Description |
|---|---|---|
| choice, sequencing | choices | A list of the options available in the interaction for selection or ordering. |
| likert | scale | A list of the options on the likert scale. |
| matching | source, target | Lists of sources and targets to be matched. |
| performance | steps | A list of the elements making up the performance interaction. |
| true-false, fill-in, long-fill-in, numeric, other | [No component lists supported] | None |
Regardless of interactionType, each Component List has the following additional properties:
| Property | Type | Description | Required |
|---|---|---|---|
| id | String | Identifies the interaction component within the list. | Required |
| description | Language Map | A description of the interaction component (for example, the text for a given choice in a multiple-choice interaction) | Optional |
Object As Actor Table: The table below lists all properties of an Actor Object
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | shall be Agent or Group | Required |
| See Actor section for addtional details regarding Agent properties. |
Object As Statement Table: The table below lists all properties of a Statement Reference Object
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | In this case, shall be StatementRef. | Required |
| id | UUID | The UUID of a Statement. | Required |
Object As Sub-Statement Table: The table below lists all properties of a Sub-Statement Object
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | In this case, shall be SubStatement. | Required |
| actor | Object | Whom the Statement is about, as an Agent or Group Object. | Required |
| verb | Object | Action taken by the Actor. | Required |
| object | Object | Activity, Agent, or another Statement that is the Object of the Statement. | Required |
| result | Object | Result Object, further details representing a measured outcome. | Optional |
| context | Object | Context that gives the Statement more meaning. Examples: a team the Actor is working with, altitude at which a scenario was attempted in a flight simulator. | Optional |
| timestamp | Timestamp | Timestamp of when the events described within this Statement occurred. Set by the LRS if not provided. | Optional |
| attachments | Ordered array of Attachment Objects | Headers for Attachments to the Statement | Optional |
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.
| Property | Type | Description | Required |
|---|---|---|---|
| score | Object | The score of the Agent in relation to the success or quality of the experience. | Optional |
| success | Boolean | Indicates whether or not the attempt on the Activity was successful. | Optional |
| completion | Boolean | Indicates whether or not the Activity was completed. | Optional |
| response | String | A response appropriately formatted for the given Activity. | Optional |
| duration | Duration | Period of time over which the Statement occurred. | Optional |
| extensions | Object | A map of other properties as needed. | Optional |
Score Table: Represents the outcome of a graded Activity achieved by an Agent. The table below lists all properties of the Score Object.
| Property | Type | Description | Required |
|---|---|---|---|
| scaled | Decimal number between -1 and 1, inclusive | The score related to the experience as modified by scaling and/or normalization. | Recommended |
| raw | Decimal number between min and max (if present, otherwise unrestricted), inclusive | The score achieved by the Actor in the experience described by the Statement. This is not modified by any scaling or normalization. | Optional |
| min | Decimal number less than max (if present) | The lowest possible score for the experience described by the Statement. | Optional |
| max | Decimal number greater than min (if present) | The highest possible score for the experience described by the Statement. | Optional |
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.
| Property | Type | Description | Required |
|---|---|---|---|
| registration | UUID | The registration that the Statement is associated with. | Optional |
| instructor | Agent (may be a Group) | Instructor that the Statement relates to, if not included as the Actor of the Statement. | Not Recommended |
| team | Group | Team that this Statement relates to, if not included as the Actor of the Statement. | Not Recommended |
| contextActivities | contextActivities Object | A map of the types of learning activity context that this Statement is related to. Every key in the contextActivities Object shall be one of "parent", "grouping", "category", or "other". Every value in the contextActivities Object shall be either a single Activity Object or an array of Activity Objects. | Optional |
| contextAgents | Array of contextAgent Objects | Collection of Objects describing relationship(s) between Agent(s) and the current Statement. Zero or more Relevant Type IRIs are used to categorize these relationship(s) | Optional |
| contextGroups | Array of contextGroup Objects | Collection of Objects describing relationship(s) between Identified or Anonymous Group(s) and the current Statement. Zero or more Relevant Type IRIs are used to categorize these relationship(s) | Optional |
| revision | String | Revision of the learning activity associated with this Statement. Format is free. | Optional |
| platform | String | Platform used in the experience of this learning activity. | Optional |
| language | String (as defined in RFC 5646) | Code representing the language in which the experience being recorded in this Statement (mainly) occurred in, if applicable and known. | Optional |
| statement | Statement Reference | Another Statement to be considered as context for this Statement. | Optional |
| extensions | Object | A map of any other domain-specific context relevant to this Statement. For example, in a flight simulator altitude, airspeed, wind, attitude, GPS coordinates might all be relevant. | Optional |
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 Relevant 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:
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | contextAgent | Required |
| agent | Agent Object | A single Agent Object for which a Statement specific relationship is being defined | Required |
| relevantTypes | Array of Relevant "type" IRIs | A collection of 1 or more Relevant Type(s) used to characterize the relationship between the Statement and the Agent. If not provided, only a generic relationship is intended (not recommended) | Optional |
- 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 Relevant Type IRIs can be included within the relevantTypes array of a contextAgent Object.
- A Relevant 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:
| Property | Type | Description | Required |
|---|---|---|---|
| objectType | String | contextGroup | Required |
| group | Group | A single Group Object for which a Statement specific relationship is being defined. | Required |
| relevantTypes | Array of Relevant "type" IRIs | A collection of 1 or more Relevant Type(s) used to characterize the relationship between the Statement and the Agent. If not provided, only a generic relationship is intended (not recommended) | Optional |
- 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 Relevant Type IRIs can be included within the relevantTypes array of a contextAgent Object.
- An Relevant 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.
| Property | Type | Description | Required | Corresponding Request Parameter |
|---|---|---|---|---|
| usageType | IRI | Identifies the usage of this Attachment. For example: one expected use case for Attachments is to include a "completion certificate". An IRI corresponding to this usage shall be coined, and used with completion certificate attachments. | Required | |
| display | Language Map | Display name (title) of this Attachment. | Required | |
| description | Language Map | A description of the Attachment | Optional | |
| contentType | Internet Media Type | The content type of the Attachment. | Required | Content-Type |
| length | Integer | The length of the Attachment data in octets. | Required | Content-Length |
| sha2 | String | The SHA-2 hash of the Attachment data. This property is always required, even if fileURL is also specified. | Required | X-Experience-API-Hash |
| fileUrl | IRL | An IRL at which the Attachment data can be retrieved, or from which it used to be retrievable. | Optional |
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:
| Property | Type | Description | Required |
|---|---|---|---|
| name | Language Map | The human readable/visual name. For Verbs, this is equivalent to the "display" property in a Statement. | Optional |
| description | Language Map | description | Optional |
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.
- 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).
| Property | Type | Description |
|---|---|---|
| id | String | Set by Learning Record Provider, unique within the scope of the Agent or Activity. |
| updated | Timestamp | When the document was most recently modified (HTTP Header). |
| contents | Arbitrary binary data | The contents of the document |