IEEE.org     |     IEEE Xplore Digital Library     |     IEEE Standards     |     IEEE Spectrum     |     More Sites

Commit 7e736283 authored by Josh Gay's avatar Josh Gay 🤹
Browse files

Merge branch 'main' into 'main'

PR for CRG group to public repo 9274.1.1 xAPI Base Standard

See merge request !1
parents 24586e13 9ce696d2
......@@ -6,6 +6,8 @@
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.
......@@ -133,8 +135,12 @@ LRPs leverage both Statements and documents as data structures. An LRP may inter
- 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.
......@@ -340,7 +346,7 @@ Learning Record Providers can identify the presence and Statement id of any void
#### 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.
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.
......@@ -357,7 +363,7 @@ Example resource location/endpoint: http://example.com/xAPI/activities/state
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent Object (JSON) | The Agent 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 |
......@@ -372,7 +378,7 @@ Example resource location/endpoint: http://example.com/xAPI/activities/state
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent Object (JSON) | The Agent 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 |
......@@ -389,7 +395,7 @@ Example resource location/endpoint: http://example.com/xAPI/activities/state
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent Object (JSON) | The Agent 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. |
......@@ -405,13 +411,13 @@ Example resource location/endpoint: http://example.com/xAPI/activities/state
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| activityId | Activity id (IRI) | The Activity id associated with this state. | Required |
| agent | Agent Object (JSON) | The Agent 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 [+ registration if specified]). If "since" parameter is specified, this is limited to entries that have been stored or updated since the specified timestamp (exclusive).
**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.
......@@ -420,7 +426,7 @@ Example resource location/endpoint: http://example.com/xAPI/activities/state
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| activityId | Activity id (IRI) | The Activity id associated with these states. | Required |
| agent | Agent object (JSON) | The Agent 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. |
......@@ -436,7 +442,7 @@ Example resource location/endpoint: http://example.com/xAPI/activities/state
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| activityId | Activity id (IRI) | The Activity id associated with these states. | Required |
| agent | Agent object (JSON) | The Agent 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)
......@@ -490,7 +496,7 @@ Example resource location/endpoint: http://example.com/xAPI/activities
#### 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.
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
......@@ -504,7 +510,7 @@ Example resource location/endpoint: http://example.com/xAPI/agents/profile
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| agent | Agent object (JSON) | The Agent associated with this Profile document. | 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 |
......@@ -520,7 +526,7 @@ Example resource location/endpoint: http://example.com/xAPI/agents/profile
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| agent | Agent object (JSON) | The Agent associated with this Profile document. | 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.
......@@ -536,7 +542,7 @@ Example resource location/endpoint: http://example.com/xAPI/agents/profile
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| agent | Agent object (JSON) | The Agent associated with this Profile document. | 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.
......@@ -551,12 +557,12 @@ Example resource location/endpoint: http://example.com/xAPI/agents/profile
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| agent | Agent object (JSON) | The Agent associated with this Profile document. | 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. If "since" parameter is specified, this is limited to entries that have been stored or updated since the specified Timestamp (exclusive).
**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.
......@@ -564,7 +570,7 @@ Example resource location/endpoint: http://example.com/xAPI/agents/profile
| **Parameter** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| agent | Agent object (JSON) | The Agent associated with this Profile document. | 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)
......@@ -691,6 +697,8 @@ 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.
......@@ -996,7 +1004,7 @@ Each contextGroup Object found within a contextGroups array has the following pr
| **Property** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| objectType | String | contextGroup | Required |
| group | Group (Follow requirements in linked section to specify Group type and description) | A single Group Object for which a Statement specific relationship is being defined. | Required |
| group | Group | A single Group Object for which a Statement specific relationship is being defined. | Required |
| relevantTypes | Array of Activity "type" IRIs | A collection of 1 or more Activity 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
......@@ -1090,7 +1098,7 @@ Signed Statements include a JSON web signature (JWS) as an Attachment. This allo
**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.
- 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.
......
......@@ -12,6 +12,8 @@ The following table summarizes the Resources with which HTTP methods can interac
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)
Examples of the resources and data requirements can be found at https://opensource.ieee.org/xapi/xapi-base-standard-examples.
| **Base Resource IRI/URL of the LRS Precedes Each Entry** | **Function** |**Supported Calls** |
| --- | --- | --- |
| statements | Statement Storage/Retrieval | PUT, POST, GET, HEAD |
......@@ -195,6 +197,8 @@ The LRS shall reject Requests where parameters are:
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).
Examples of the resources can be found at https://opensource.ieee.org/xapi/xapi-base-standard-examples.
| **Property** | **Type** | **Description** |
| --- | --- | --- |
| id | String | Set by Learning Record Provider, unique within the scope of the Agent or Activity. |
......@@ -827,6 +831,8 @@ While the methods to PUT/POST and GET Statements are specific, the storage mecha
- Any attachments
- Any referenced Activity Definitions
Examples of the data requirements can be found at https://opensource.ieee.org/xapi/xapi-base-standard-examples.
### 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.
......@@ -1108,7 +1114,7 @@ All Objects found within the contextAgents and/or contextGroups array(s) are ind
| **Property** | **Type** | **Description** | **Required** |
| --- | --- | --- | --- |
| objectType | String | contextGroup | Required |
| group | Group (Follow requirements in linked section to specify Group type and description) | A single Group Object for which a Statement specific relationship is being defined. | Required |
| group | Group | A single Group Object for which a Statement specific relationship is being defined. | Required |
| relevantTypes | Array of Activity "type" IRIs | A collection of 1 or more Activity 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
......@@ -1246,7 +1252,7 @@ Signed Statements include a JSON web signature (JWS) as an Attachment. This allo
**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.
- 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.
- 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.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment