diff --git a/xAPI.md b/xAPI.md index 23a6ebf4..4d64507e 100644 --- a/xAPI.md +++ b/xAPI.md @@ -252,28 +252,38 @@ learning that SCORM could not enable. - ## 1.0 Summary of the Experience API -The Experience API is a service that allows for statements of experience -to be delivered to and stored securely in a Learning Record Store (LRS). These statements -of experience are typically learning experiences, but the API can address statements -of any kind of experience. The Experience API is dependent on Activity Providers to -create and track these learning experiences; this specification provides a data model and -associated components on how to accomplish these tasks. - -Specifically, the Experience API provides: +The Experience API (xAPI) is an Application Programming Interface (API) specification that +facilitates communication about experiences between a Learning Record Store and a client, +typically an Activity Provider. This specification was developed with learning experiences in mind, +but many other kinds of experiences could be tracked using xAPI. -* The structure and definition of Statement, State, Learner, Activity and Objects, -which are the means by which experiences are conveyed by an Activity Provider. +This specification does not attempt to standardize how the Activity Provider facilitates and tracks the learning experience, +nor how the Learning Store stores and procesess that data. The scope of this specification is limited to the requests and responses +between Learning Record Store and client. -* Data Transfer methods for the storage and retrieval (but not validation) of -these Objects to/from a Learning Record Store. Note that the systems storing -or retrieving records need not be Activity Providers. LRSs can -communicate with other LRSs, or systems. - -* Security methods allowing for the trusted exchange of information between -the Learning Record Store and trusted sources. +The purpose of the xAPI and the goals of this document are: +* To maximize interoperability of systems which create, gather and store information +about learning experiences. +* To provide a guide to those who want to build applications that conform to and implement this +specification. +* To provide criteria against which conformance to this specification can be tested. + +There are two main ways that the xAPI promotes interoperability between systems that +implement the specification. The first is by requiring that systems implementing the specification +follow a consistent data structure. To that end, this specification defines a data model for various data +objects that are transferred between systems. The most significant object within the xAPI data model is the Statement object. This +specification defines the properties of the Statement object (including "Actor", "Verb", "Object", "Result", and "Context") +and the rules of syntax for the values of those properties and how they are represented. + +The second way that the xAPI promotes interoperability is by setting out the transfer methods that must +be used when communicating information about learning experiences between programs that adhere to the +specification. As part of this, it sets out the format of requests and the expected responses. Note that the +systems storing or retrieving records need not be Activity Providers. LRSs can communicate with other LRSs, or systems. +xAPI follows the guidelines of the REST software architecture style, and as such data is tranferred via HTTP requests and +responses. xAPI also defines security methods allowing for the trusted exchange of information between +the Learning Record Store and trusted sources. The Experience API is the first of many envisioned technologies that will enable a richer architecture of online learning and training. Authentication @@ -298,11 +308,42 @@ are based on the specification set described below. For this reason, sections th _high-level overview_ of a given facet of the Experience API are labeled **description** or **rationale**. Items in this document labeled as **requirements**, **details** or **examples** are more technical. + +### 2.1 MUST / SHOULD / MAY +There are three levels of obligation with regards to conformance to the xAPI specification identified by the terms +MUST, SHOULD and MAY. A system that fails to implement a MUST (or a MUST NOT) requirement is non-conformant. +Failing to meet a SHOULD requirement is not a violation of conformity, but goes against the recommendations of the specification. MAY indicates an option, to be decided by the developer with no consequences for conformity. Usage +of these terms outside of requirement language does not designate a requirement and is avoided whenever possible. +Complete definitions of MUST, SHOULD, MAY, MUST NOT and SHOULD NOT are found in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +The use of an asterisk* following SHOULD indicates a very strong recommendation. It is planned that these +recommendations will become MUST requirements in a future version. Not following these recommendations could +risk interoperability and and/or lead to various other issues depending on the specifics of the recommendation. +Whilst these recommendations cannot be MUST requirements within this version (as these would be breaking changes) +the xAPI Working Group strongly encourages adopters to implement these requirements as though they were MUST +requirements, whilst continuing to support other adopters that might not do so. + +### 2.2 Guidelines for Interpreting Descriptive Text and Tables As a rule of thumb, if the guideline appears technical or seems to be a requirement, interpret it as such. This is especially true of longer, more, detailed explanations and of tables, each of which would be unintuitive and/or lengthy to dissect into a list of requirements. -## 3.0 Guidenelines for Implementing Technical Specificationss Like xAPI +Tables are used throughout this specification to define requirements for lists of properties, parameters, etc. +The tables define which properties are required, recommended and optional. Generally, 'optional' relates to the +system creating the object and systems receiving and interpreting the object need to be able to interpret all +properties of that object. Often, properties are optional because the data may not be relevant in all contexts; +if the data is relevant in a particular context, then it's expected the property will be populated. + +If an optional property or parameter contains an object with properties that are recommended or required, then +these properties are only recommended/required if the property or parameter containing them is used. + +Examples are provided through the specification and in appendices to illustrate implementation. The content of these examples is fictional in order to illustrate the requirements of the specification and may not always +illustrate the best practice approach to tracking the particular learning experience used in the example. Examples +can be used to inform interpretation of requirements but aren't intended to take precedence over requirements. + +Where the specification does not include requirements relating to a particular facet of implementation, that detail can be considered to be outside of the scope of this specification and it is up to the implementer to determine a +sensible approach. This specification tries to avoid vagueness and will usually give a rationale even if there no +requirement in a given area. ## 4.0 Binding to JavaScript Object Notation (JSON) @@ -340,7 +381,6 @@ be unintuitive and/or lengthy to dissect into a list of requirements. * [Learning Record Store (LRS)](#def-learning-record-store) * [Metadata Provider](#def-metadata-provider) * [Metadata Consumer](#def-metadata-consumer) -* [MUST / SHOULD / MAY](#def-must-should-may) * [Profile](#def-profile) * [Registration](#def-registration) * [Representational State Transfer (REST)](#def-rest) @@ -456,20 +496,6 @@ might not be a metadata consumer. __Metadata Provider__: A person, organization, software program or other thing that coins IRIs to be used within this specification and/or hosts metadata about an IRI. - - -__MUST / SHOULD / MAY__: Three levels of obligation with regards to conformance to the xAPI -specification. A system that fails to implement a MUST (or a MUST NOT) requirement is non-conformant. -Failing to meet a SHOULD requirement is not a violation of conformity, but goes against best practices. -MAY indicates an option, to be decided by the developer with no consequences for conformity. - -The use of an asterisk* following SHOULD indicates a very strong recommendation. It is planned that these -recommendations will become MUST requirements in a future version. Not following these recommendations could -risk interoperability and and/or lead to various other issues depending on the specifics of the recommendation. -Whilst these recommendations cannot be MUST requirements within this version (as these would be breaking changes) -the xAPI Working Group strongly encourages adopters to implement these requirements as though they were MUST requirements, -whilst continuing to support other adopters that might not do so. - __Profile__: A construct where information about the learner or activity is kept, @@ -507,13 +533,32 @@ __Verb__: Defines the action being done by the Actor within the Activity within ## 7.0 xAPI Components -## 8.0 Getting More Out of xAPI +## 8.0 Extending xAPI + +xAPI can be extended in a few ways. The most notable is Statement Extensions, which allow great flexibility within Statements. It is recommended that profiles or Communities or Practice agree on how to use +extensions for their particular use cases. Implementation details are covered in a [later section](#miscext) + +The About Resource is another place xAPI supports Extensions. The LRS may find it useful to communicate features or behaviors beyond this specification to activity provider. The LRS can use extensions to the About Resource to communicate these features and behaviours. -### 8.1 Extending xAPI +Finally, the set of Resources implemented is not expected to be constrained by this document. Resources beyond +those listed in this specification can be implemented and co-exist with the Resources defined in this specification. -### 8.2 Profiles + -### 8.3 Communities of Practice +## 9.0 Profiles and Communities of Practice + +xAPI strictly defines the structure of statements communicated between the client and an LRS but is very flexible as to the content of that statement structure. For example, the specification requires that all statements have a verb property, but does not restrict the values of that property; any verb can be used. This flexibility enables xAPI to be used in any context, including future use cases not envisaged by the specification authors. + +It is intended that Communities of Practice (CoPs) will define the identifiers (verbs, activity types, contextual relationships, extensions, etc.) to be used in their use cases. It is very important that such communities exist +and share best practices. The CoP will define these identifiers in a profile. This is a set of rules and/or +vocabularies to implemented in addition to xAPI for the particular use case being addressed. + +It is recommended that a profile use a unique "category" within a Statement's context to refer to any Statement +which follows the profile. An example profile is [cmi5](https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_runtime.md#ContextActivities"), which is designed for the traditional single learner, single online learning use case. + +CoPs are highly recommended to avoid duplication of effort, as creating too many ways to solve the same problem +will cause fragmentation in similar domains and will hurt interoperability. An example of a CoP for the medical +field is the [Medbiquitous xAPI Interest Group](http://groups.medbiq.org/medbiq/display/XIG/XAPI+Interest+Group+Home). ##### Use in Communities of Practice @@ -859,7 +904,7 @@ See [Appendix A: Example Statements](#AppendixA) for more examples. -#### 4.1.1 ID +#### 2.3.1 ID ###### Description @@ -872,14 +917,14 @@ A UUID (all versions of variant 2 in [RFC 4122](http://www.ietf.org/rfc/rfc4122. -#### 4.1.2 Actor +#### 2.3.2 Actor ###### Description A mandatory Agent or Group Object. -##### 4.1.2.1 When the Actor ObjectType is Agent +##### 2.3.2.1 When the Actor ObjectType is Agent ###### Description An Agent (an individual) is a persona or system. @@ -906,7 +951,7 @@ The table below lists the properties of Agent Objects. -##### 4.1.2.2 When the Actor ObjectType is Group +##### 2.3.2.2 When the Actor ObjectType is Group ###### Description A Group represents a collection of Agents and can be used in most of the same situations an Agent @@ -967,7 +1012,7 @@ or store and retrieve documents relating to a group. -##### 4.1.2.3 Inverse Functional Identifier +##### 2.3.2.3 Inverse Functional Identifier ###### Description An Inverse Functional Identifier (IFI) is a value of an Agent or Identified Group that is guaranteed to only ever refer to that Agent or Identified Group. @@ -997,7 +1042,7 @@ for the "mbox_sha1sum" property. -##### 4.1.2.4 Account Object +##### 2.3.2.4 Account Object ###### Description @@ -1039,7 +1084,7 @@ This example shows an Agent identified by an opaque account: -#### 4.1.3 Verb +#### 2.3.3 Verb ###### Description The Verb defines the action between Actor and Activity. @@ -1133,7 +1178,7 @@ The Verb in the example above is included for illustrative purposes only. This i a Verb with this meaning has been defined with this id. This applies to all example verbs given in this specification document, with the exception of the reserved Verb 'http://adlnet.gov/expapi/verbs/voided'. -##### 4.1.3.1 Use in Language and Semantics of Verbs +##### 2.3.3.1 Use in Language and Semantics of Verbs ###### Details _Semantics_ @@ -1164,7 +1209,7 @@ or the Verb IRI http://example.com/فعل/خواندن might denote the action o -####4.1.4 Object +####2.3.4 Object ###### Description @@ -1189,7 +1234,7 @@ The properties of an Object change according to the objectType. -##### 4.1.4.1 When the ObjectType is Activity +##### 2.3.4.1 When the ObjectType is Activity ###### Details @@ -1569,7 +1614,7 @@ See [Appendix C](#AppendixC) for examples of Activity Definitions for each of th -##### 4.1.4.2 When the "Object" is an Agent or a Group +##### 2.3.4.2 When the "Object" is an Agent or a Group ###### Requirements @@ -1579,7 +1624,7 @@ See [Section 4.1.2 Actor](#actor) for details regarding Agents. -##### 4.1.4.3 When the "Object" is a Statement +##### 2.3.4.3 When the "Object" is a Statement ###### Rationale @@ -1703,7 +1748,7 @@ action. The concrete example that follows logically states that -#### 4.1.5 Result +#### 2.3.5 Result ###### Description An optional property that represents a measured outcome related to the Statement in which it is included. @@ -1767,7 +1812,7 @@ truncate the Duration property to 0.01 second precision. -##### 4.1.5.1 Score +##### 2.3.5.1 Score ###### Description An optional property that represents the outcome of a graded Activity achieved by an Agent. @@ -1820,7 +1865,7 @@ from an extension profile instead. -#### 4.1.6 Context +#### 2.3.6 Context ###### Description An optional property that provides a place to add contextual information to a Statement. All properties are optional. @@ -1912,7 +1957,7 @@ so that it is available for systems interpreting and displaying data. -##### 4.1.6.1 Registration Property +##### 2.3.6.1 Registration Property ###### Description An instance of a learner undertaking a particular learning activity. @@ -1925,7 +1970,7 @@ completing an Activity ends a registration. Nor is a registration necessarily co -##### 4.1.6.2 ContextActivities Property +##### 2.3.6.2 ContextActivities Property ###### Description A map of the types of learning activity context that this Statement is related to. @@ -2002,7 +2047,7 @@ useful when the Object of the Statement is an Agent, not an Activity. -#### 4.1.7 Timestamp +#### 2.3.7 Timestamp ###### Description The time at which the experience occurred. @@ -2038,7 +2083,7 @@ so long as the point in time referenced is not affected. The LRS SHOULD* return -#### 4.1.8 Stored +#### 2.3.8 Stored ###### Description The time at which a Statement is stored by the LRS. This can be any time between when the LRS receives the Statement and when it is written @@ -2062,7 +2107,7 @@ for seconds (millisecond precision MUST be preserved). -#### 4.1.9 Authority +#### 2.3.9 Authority ###### Description The authority property provides information about whom or what has asserted that @@ -2137,7 +2182,7 @@ The pairing of an OAuth consumer and a user. -#### 4.1.10 Version +#### 2.3.10 Version ###### Description Version information in Statements helps systems that process data from an LRS get their bearings. Since the Statement data model is guaranteed consistent through all 1.0.x versions, in order to support data @@ -2159,7 +2204,7 @@ lack a version, the version MUST be set to 1.0.0. -#### 4.1.11 Attachments +#### 2.3.11 Attachments ###### Description A digital artifact providing evidence of a learning experience. @@ -2378,7 +2423,7 @@ X-Experience-API-Hash:495395e777cd98da653df9615d09c0fd6bb2f8d4788394cd53c56a3bfd here is a simple attachment --abcABC0123'()+_,-./:=?-- ``` -### 3.4 Retrieval of Statements +### 2.4 Retrieval of Statements ###### Description A collection of Statements can be retrieved by performing a query on the "statements" @@ -2422,7 +2467,7 @@ returned matches those statements that would have been returned when the origina * The consumer SHOULD NOT attempt to interpret any meaning from the IRL returned from the more property. -### 3.5 Signed Statements +### 2.5 Signed Statements ##### Description A Statement can include a @@ -3778,10 +3823,6 @@ required by 6.2 API Versioning. ## 3.0 Data Validation - - -### 3.1 Basics (May not need and just put at 2.0) - ###### Description The function of the LRS within the xAPI is to store and retrieve Statements. @@ -3798,7 +3839,7 @@ responsibility of the Activity Provider sending the Statement. -### 3.2 Concurrency +### 3.1 Concurrency ##### Description Concurrency control makes certain that an API consumer does not PUT, POST or DELETE documents based on old @@ -3869,7 +3910,7 @@ If a PUT request is received without either header for a resource that already e -### 3.3 Error Codes +### 3.2 Error Codes ##### Description @@ -4003,7 +4044,7 @@ This set of credentials SHOULD* be used for conformance testing but MAY be delet -### 3.4 Versioning +### 3.3 Versioning ###### Rationale