From d79b8a0b69394c031ccd16aa038d0e7e3abeb772 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Mon, 29 Jun 2015 11:53:16 -0400 Subject: [PATCH 01/16] Part1Section1 Restructure I'd like to switch this language to Roger's. I plan on using some of the text after that in future sections, so it could be deleted from this section after the adding phase is over. --- xAPI.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/xAPI.md b/xAPI.md index 23a6ebf4..5a6a53b4 100644 --- a/xAPI.md +++ b/xAPI.md @@ -255,6 +255,25 @@ learning that SCORM could not enable. ## 1.0 Summary of the Experience API +The Experience API (Application Programming Interface) - or xAPI as it is commonly called - is a framework that +facilitates the description of learning experiences and their communication and storage in a consistent manner +in a digital environment. As an application programming interface, the xAPI does not set out how the framework +should be implemented. Rather, it sets out the essential components of that framework and how they relate to each other. The purpose of the xAPI and the goals of this document are: + +* To maximize interoperability and reliability of computer programs which create, gather and store information +about learning experiences. +* To provide a guide to computer programmers who want to build applications that conform to and implement this +framework. +* To provide users of these programs a description of features and capabilities that they can expect from them. +* To provide the ADL that certifies conformance to this framework with criteria against which certification can +be tested. + +There are three main ways that the xAPI promotes the interoperability and reliability of programs that implement the framework. The first is by requiring that programs that gather and store information about learning experiences describe those experiences in a consistent manner. To that end, it sets out a set of terms for describing those experiences including such terms as "Actor", "Activity", "Verb", "Result", and "Context" as well as rules of syntax for how they should be combined. + +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 framework. As part of this, it sets out the information that needs to be included and how it must be handled via RESTFul HTTP methods. + +Finally, a major goal of the framework is to promote the reliability of programs that use the framework. Reliability in this context means that users of the programs can be assured that the descriptions of learning experiences that are stored and retrieved have not been altered but are treated as "immutable". It also means that these programs have implemented certain minimum levels of security. + 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 From fc2680fc8f1f41e93e5e740de493dbf8266f4a01 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Mon, 29 Jun 2015 12:48:48 -0400 Subject: [PATCH 02/16] Part1Section3 Added Section 3 --- xAPI.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/xAPI.md b/xAPI.md index 23a6ebf4..09382cc0 100644 --- a/xAPI.md +++ b/xAPI.md @@ -302,7 +302,44 @@ As a rule of thumb, if the guideline appears technical or seems to be a requirem 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 +## 3.0 Guidelines for Implementing Technical Specifications Like xAPI + +Specific words in all caps will designate the difference between a requirement and simply explanatory text. The +specific tokens used are MUST, SHOULD, MAY, and NOT. Usage of these words outside of requirement language does not +designate a requirement as is avoided whenever possible. Usage is as follows: + +* MUST indicates a 100% requirement or the implementation is non-compliant. +* SHOULD indicates a best practice, typically chosen because it is the only reasonable way. Alternatives could +exist, so the option is open. +* MAY indicates that something can be done, but doesn't have to be. The reason for MAY requirements instead of +simply nothing is to indicate that some thought went into the issue and there are multiple reasonable solutions. +MAY is also used to introduce implementations or details that the reader may not have thought of. +* MUST NOT indicates that if a certain condition is met, then the implementation is non-compliant. +* SHOULD NOT indicates a common practice that is against an industry best practice or that will lead to perceived +poor results in most circumstances. +* MAY NOT is logically the same as MUST NOT and is not used. + +In technical specification documents, it is important to understand the relationships that exist between various +parts which comprise an ecosystem. In the case of xAPI, whose main structured component is Statements, there +are LRSs and other systems (like reporting) that may use the Statement data (among other data). + +Tables are a great way of structuring information and putting a lot of information in one place, but can cause +confusion in requirements. A good rule of thumb is that any required/optional portion will be present if not +everything is uniform. The context of the table (i.e. this behavior is optional) will set the tone. Systems +working with the data structure represented in the table (i.e. Statements in xAPI) implement all fields such that +processing can be done. + +If an optional best practice is given, or an optional implementation, it should be understood that any +instructions following are only necessary if said optional piece is used. That is, if it is implemented, it is +done a certain way, but it doesn't have to be implemented. + +Where there is nothing mentioned about a particular facet of the spec, it is open for interpretation and therefore +has no requirements within the specification. Certain technological limitations and practices sometimes restrict +the choice and may or may not be called out in this spec. This specification tries to avoid vagueness and will +usually give a rationale even if there no requirement in a given area. + +In the absence of requirements, or in the vagueness or requirements, examples should be heavily leaned upon to +show both requirements and industry best practices. ## 4.0 Binding to JavaScript Object Notation (JSON) From 30c1aa69613b66690ab3f6ec0e0b232e73038e39 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Wed, 1 Jul 2015 14:05:06 -0400 Subject: [PATCH 03/16] Changes to Part1Section8 Added some text to extending. Likely we can eliminate text in a couple other stray areas. The text in the later portion of 8.3 should be updated to refer to all "coinable" xAPI constructs. --- xAPI.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/xAPI.md b/xAPI.md index 23a6ebf4..94d8686f 100644 --- a/xAPI.md +++ b/xAPI.md @@ -509,12 +509,56 @@ __Verb__: Defines the action being done by the Actor within the Activity within ## 8.0 Getting More Out of xAPI +xAPI was developed to be as lightweight as possible, but able to be focused to be powerful. xAPI defines only +one verb (for voiding Statements) and only one activity type (cmi.interaction). Obviously, this isn't meant to +be the extent of what xAPI can do. xAPI is limitless in how far it can be taken, which is why this document +doesn't attempt to define a "starting set", because it would encourage adoption of only said set. Many of the +Resources, such as State and Activity Profile, are intentionally left as "a set of name/value" pairs to not try +to force a certain practice. The very notion of IRIs and suggested resolvable metadata be at the location is a +way to continuously increase the value of xAPI by not tying definitions down permanently. + ### 8.1 Extending xAPI +xAPI can be extended in a few ways. The most notable is Statement Extensions, which are covered in a +later section. Extending Statements is how new types of information are brought into a +Statement and can only be done in three places. + +The About Resource is another way xAPI enables extensions. Of the Resources (located at various Endpoints), the +only one that can be extended is the About Resource. It is hoped that if more information is available about an +LRS, that the About Resource captures it. + +Finally, the set of Resources implemented is not expected to be constrained by this document. While not explicitly +defined, this document suggests that no new Endpoints defined in future iterations of this specification will +begin with /extensions and that LRSs create other custom xAPI Resources there. + ### 8.2 Profiles +Profile in this specification usually refers to the Activity Profile or Agent Profile, which are useful Resources, +each having their own Endpoint. These profiles, while useful, are not very defined. Another use of profile in +xAPI is applying a set of rules and/or vocabularies consistently. An xAPI Profile follows all rules (MUSTs) of +the specification, but can more narrowly define xAPI requirements or create its own. + +A profile will typically define some of the open-ended areas of the specification, such as identifying verbs, activity types, structure and domains for IRIs, and names/possible values within xAPI Resources like the State API. + +The implementation details of profile are typically best practices as defined by one or more Communities of Practice + + +It is recommended that a profile use a unique "category" within a Statement's context to refer to any Statement +which follows the profile. + + + ### 8.3 Communities of Practice +xAPI Communities of Practice (CoP)s are groups of people that have common goals for tracking a certain domain that can utilize xAPI. A CoP typically already has a certain taxonomy to it, methodologies, and values. xAPI CoPs +can define their own Verbs, Activity types, extensions, and other parts of Statements and Resources to align with +their group's needs. + +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. + +The text below will be expanded to include all "coined" parts + ##### Use in Communities of Practice ###### Description From a7a3b3c6d27c4dc412cb02bf213e25075f321fc9 Mon Sep 17 00:00:00 2001 From: Andrew Downes Date: Fri, 10 Jul 2015 17:35:03 +0100 Subject: [PATCH 04/16] Updates to 1.0 Summary of the Experience API --- xAPI.md | 66 +++++++++++++++++++++++++-------------------------------- 1 file changed, 29 insertions(+), 37 deletions(-) diff --git a/xAPI.md b/xAPI.md index 5a6a53b4..146e7c9a 100644 --- a/xAPI.md +++ b/xAPI.md @@ -252,47 +252,39 @@ learning that SCORM could not enable. - ## 1.0 Summary of the Experience API -The Experience API (Application Programming Interface) - or xAPI as it is commonly called - is a framework that -facilitates the description of learning experiences and their communication and storage in a consistent manner -in a digital environment. As an application programming interface, the xAPI does not set out how the framework -should be implemented. Rather, it sets out the essential components of that framework and how they relate to each other. The purpose of the xAPI and the goals of this document are: - -* To maximize interoperability and reliability of computer programs which create, gather and store information -about learning experiences. -* To provide a guide to computer programmers who want to build applications that conform to and implement this -framework. -* To provide users of these programs a description of features and capabilities that they can expect from them. -* To provide the ADL that certifies conformance to this framework with criteria against which certification can -be tested. - -There are three main ways that the xAPI promotes the interoperability and reliability of programs that implement the framework. The first is by requiring that programs that gather and store information about learning experiences describe those experiences in a consistent manner. To that end, it sets out a set of terms for describing those experiences including such terms as "Actor", "Activity", "Verb", "Result", and "Context" as well as rules of syntax for how they should be combined. - -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 framework. As part of this, it sets out the information that needs to be included and how it must be handled via RESTFul HTTP methods. - -Finally, a major goal of the framework is to promote the reliability of programs that use the framework. Reliability in this context means that users of the programs can be assured that the descriptions of learning experiences that are stored and retrieved have not been altered but are treated as "immutable". It also means that these programs have implemented certain minimum levels of security. +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. These experiences are typically learning experiences, but the API can be used +to facilitates communication about any kind of experience. The scope of xAPI is limited to the communication of data +between these systems. -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. +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. -Specifically, the Experience API provides: - -* The structure and definition of Statement, State, Learner, Activity and Objects, -which are the means by which experiences are conveyed by an Activity Provider. - -* 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 guidlines 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 From 8cb71505bbe97b843180e8f51d3b7cf70dd6a869 Mon Sep 17 00:00:00 2001 From: Andrew Downes Date: Fri, 10 Jul 2015 19:08:58 +0100 Subject: [PATCH 05/16] re-wording to section 2.0 and 3.0 --- xAPI.md | 77 ++++++++++++++++++++++----------------------------------- 1 file changed, 30 insertions(+), 47 deletions(-) diff --git a/xAPI.md b/xAPI.md index 09382cc0..90722649 100644 --- a/xAPI.md +++ b/xAPI.md @@ -298,48 +298,46 @@ 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 +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 best practices. 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 Guidelines for Implementing Technical Specifications Like xAPI - -Specific words in all caps will designate the difference between a requirement and simply explanatory text. The -specific tokens used are MUST, SHOULD, MAY, and NOT. Usage of these words outside of requirement language does not -designate a requirement as is avoided whenever possible. Usage is as follows: - -* MUST indicates a 100% requirement or the implementation is non-compliant. -* SHOULD indicates a best practice, typically chosen because it is the only reasonable way. Alternatives could -exist, so the option is open. -* MAY indicates that something can be done, but doesn't have to be. The reason for MAY requirements instead of -simply nothing is to indicate that some thought went into the issue and there are multiple reasonable solutions. -MAY is also used to introduce implementations or details that the reader may not have thought of. -* MUST NOT indicates that if a certain condition is met, then the implementation is non-compliant. -* SHOULD NOT indicates a common practice that is against an industry best practice or that will lead to perceived -poor results in most circumstances. -* MAY NOT is logically the same as MUST NOT and is not used. - -In technical specification documents, it is important to understand the relationships that exist between various -parts which comprise an ecosystem. In the case of xAPI, whose main structured component is Statements, there -are LRSs and other systems (like reporting) that may use the Statement data (among other data). - -Tables are a great way of structuring information and putting a lot of information in one place, but can cause -confusion in requirements. A good rule of thumb is that any required/optional portion will be present if not -everything is uniform. The context of the table (i.e. this behavior is optional) will set the tone. Systems -working with the data structure represented in the table (i.e. Statements in xAPI) implement all fields such that -processing can be done. +Tables are used throughout this specification to define the data structure of objects. 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 best practice is given, or an optional implementation, it should be understood that any instructions following are only necessary if said optional piece is used. That is, if it is implemented, it is done a certain way, but it doesn't have to be implemented. -Where there is nothing mentioned about a particular facet of the spec, it is open for interpretation and therefore -has no requirements within the specification. Certain technological limitations and practices sometimes restrict -the choice and may or may not be called out in this spec. This specification tries to avoid vagueness and will -usually give a rationale even if there no requirement in a given area. +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. -In the absence of requirements, or in the vagueness or requirements, examples should be heavily leaned upon to -show both requirements and industry best practices. +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) @@ -377,7 +375,6 @@ show both requirements and industry best practices. * [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) @@ -493,20 +490,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, From 82ffd847dfe6f889ae63b349c6b7093718bcda51 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Tue, 21 Jul 2015 10:32:17 -0400 Subject: [PATCH 06/16] Part2Section2Renumbering No additions, just changed numbering in 2.3-2.5 --- xAPI.md | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/xAPI.md b/xAPI.md index 23a6ebf4..737b166f 100644 --- a/xAPI.md +++ b/xAPI.md @@ -859,7 +859,7 @@ See [Appendix A: Example Statements](#AppendixA) for more examples. -#### 4.1.1 ID +#### 2.3.1 ID ###### Description @@ -872,14 +872,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 +906,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 +967,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 +997,7 @@ for the "mbox_sha1sum" property. -##### 4.1.2.4 Account Object +##### 2.3.2.4 Account Object ###### Description @@ -1039,7 +1039,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 +1133,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 +1164,7 @@ or the Verb IRI http://example.com/فعل/خواندن might denote the action o -####4.1.4 Object +####2.3.4 Object ###### Description @@ -1189,7 +1189,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 +1569,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 +1579,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 +1703,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 +1767,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 +1820,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 +1912,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 +1925,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 +2002,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 +2038,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 +2062,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 +2137,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 +2159,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 +2378,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 +2422,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 From ba316d153f8f7a62fa830f329321553b4bd708d1 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Thu, 23 Jul 2015 16:36:22 -0400 Subject: [PATCH 07/16] Part3Section3Edit Just title changes --- xAPI.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/xAPI.md b/xAPI.md index 23a6ebf4..a5920368 100644 --- a/xAPI.md +++ b/xAPI.md @@ -3778,10 +3778,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 +3794,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 +3865,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 +3999,7 @@ This set of credentials SHOULD* be used for conformance testing but MAY be delet -### 3.4 Versioning +### 3.3 Versioning ###### Rationale From 26331a2d38b8d07ed38655358b78d23133d10d62 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Mon, 27 Jul 2015 17:06:14 -0400 Subject: [PATCH 08/16] Update xAPI.md Halfway through Andrew's comments --- xAPI.md | 38 +++++++++++++------------------------- 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/xAPI.md b/xAPI.md index 94d8686f..69aef8ed 100644 --- a/xAPI.md +++ b/xAPI.md @@ -509,48 +509,36 @@ __Verb__: Defines the action being done by the Actor within the Activity within ## 8.0 Getting More Out of xAPI -xAPI was developed to be as lightweight as possible, but able to be focused to be powerful. xAPI defines only -one verb (for voiding Statements) and only one activity type (cmi.interaction). Obviously, this isn't meant to -be the extent of what xAPI can do. xAPI is limitless in how far it can be taken, which is why this document -doesn't attempt to define a "starting set", because it would encourage adoption of only said set. Many of the -Resources, such as State and Activity Profile, are intentionally left as "a set of name/value" pairs to not try -to force a certain practice. The very notion of IRIs and suggested resolvable metadata be at the location is a -way to continuously increase the value of xAPI by not tying definitions down permanently. +xAPI focuses on the structure of communication between a client and an LRS. It spares many details of the content to +increase flexibility. The intention in only supplying a basic amount of syntax rules is that Communities of Practice (CoP) can define content (verbs, activity types, contextual relationships, extensions, etc.) for their use cases. It is very +important that such communities exist and share best practices. ### 8.1 Extending xAPI -xAPI can be extended in a few ways. The most notable is Statement Extensions, which are covered in a -later section. Extending Statements is how new types of information are brought into a -Statement and can only be done in three places. +xAPI can be extended in a few ways. The most notable and extensive 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. -The About Resource is another way xAPI enables extensions. Of the Resources (located at various Endpoints), the -only one that can be extended is the About Resource. It is hoped that if more information is available about an +The About Resource is another way xAPI enables extensions. The LRS may find it useful to communicate features or +behaviors beyond this specification to activity provider. It is hoped that if more information is available about an LRS, that the About Resource captures it. Finally, the set of Resources implemented is not expected to be constrained by this document. While not explicitly defined, this document suggests that no new Endpoints defined in future iterations of this specification will begin with /extensions and that LRSs create other custom xAPI Resources there. -### 8.2 Profiles - -Profile in this specification usually refers to the Activity Profile or Agent Profile, which are useful Resources, -each having their own Endpoint. These profiles, while useful, are not very defined. Another use of profile in -xAPI is applying a set of rules and/or vocabularies consistently. An xAPI Profile follows all rules (MUSTs) of -the specification, but can more narrowly define xAPI requirements or create its own. + -A profile will typically define some of the open-ended areas of the specification, such as identifying verbs, activity types, structure and domains for IRIs, and names/possible values within xAPI Resources like the State API. +### 8.2 Profiles and Communities of Practice -The implementation details of profile are typically best practices as defined by one or more Communities of Practice +A profile of xAPI is a set of rules and/or vocabularies applied to a valid xAPI implementation. Often, a CoP leverages many best practices to create a profile. +A profile will typically define some of the open-ended areas of the specification, such as identifying verbs, activity types, structure and domains for IRIs, and names/possible values within xAPI Resources like the State API. It is recommended that a profile use a unique "category" within a Statement's context to refer to any Statement which follows the profile. - - -### 8.3 Communities of Practice - -xAPI Communities of Practice (CoP)s are groups of people that have common goals for tracking a certain domain that can utilize xAPI. A CoP typically already has a certain taxonomy to it, methodologies, and values. xAPI CoPs +xAPI Communities of Practice are groups of people that have common goals for tracking a certain domain that can utilize xAPI. A CoP typically already has a certain taxonomy to it, methodologies, and values. xAPI CoPs can define their own Verbs, Activity types, extensions, and other parts of Statements and Resources to align with their group's needs. From 1f51afc6d843f4842267615d0433b0a7e62d5c82 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Tue, 28 Jul 2015 08:26:45 -0400 Subject: [PATCH 09/16] Update xAPI.md 2nd half of edits, github got weird on me so hopefully no conflicts. --- xAPI.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/xAPI.md b/xAPI.md index 69aef8ed..f1b977f4 100644 --- a/xAPI.md +++ b/xAPI.md @@ -533,17 +533,21 @@ begin with /extensions and that LRSs create other custom xAPI Resources there. A profile of xAPI is a set of rules and/or vocabularies applied to a valid xAPI implementation. Often, a CoP leverages many best practices to create a profile. -A profile will typically define some of the open-ended areas of the specification, such as identifying verbs, activity types, structure and domains for IRIs, and names/possible values within xAPI Resources like the State API. +A profile will typically define some of the open-ended areas of the specification, such as identifying verbs, activity types, structure and domains for IRIs, and names/possible values within xAPI Resources like the State API. This is +referred to as creating a vocabulary. It is recommended that a profile use a unique "category" within a Statement's context to refer to any Statement -which follows the profile. +which follows the profile. An example profile is cmi5 , which fits the +traditional single learner, single online learning use case. -xAPI Communities of Practice are groups of people that have common goals for tracking a certain domain that can utilize xAPI. A CoP typically already has a certain taxonomy to it, methodologies, and values. xAPI CoPs -can define their own Verbs, Activity types, extensions, and other parts of Statements and Resources to align with -their group's needs. +xAPI Communities of Practice are groups that have common goals for tracking a certain domain that can utilize xAPI. +A CoP typically already has a certain vocabulary used, processes, and values. xAPI CoPs can define their own verbs, +activity types, extensions, and other parts of statements and resources to align with their group's needs. 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. +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 . The text below will be expanded to include all "coined" parts From b2eb7ce4a6831bae59514d9c242ff16d319e05f2 Mon Sep 17 00:00:00 2001 From: Andrew Downes Date: Tue, 28 Jul 2015 16:52:40 +0100 Subject: [PATCH 10/16] Edits to part 1 section 1 --- xAPI.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/xAPI.md b/xAPI.md index 146e7c9a..903c076c 100644 --- a/xAPI.md +++ b/xAPI.md @@ -256,9 +256,8 @@ learning that SCORM could not enable. 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. These experiences are typically learning experiences, but the API can be used -to facilitates communication about any kind of experience. The scope of xAPI is limited to the communication of data -between these systems. +typically an Activity Provider. This specification was developed with learning experiences in mind, +but many other kinds of experiences could be tracked using xAPI. 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 @@ -282,7 +281,7 @@ The second way that the xAPI promotes interoperability is by setting out the tra 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 guidlines of the REST software architecture style, and as such data is tranferred via HTTP requests and +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. From 73fc3a8aa4050cb9f6d15ea01a0ab3c1bd6c0104 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Tue, 4 Aug 2015 09:49:41 -0400 Subject: [PATCH 11/16] Table language, requirements, etc. Mostly agreed upon text, one minor tweak --- xAPI.md | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/xAPI.md b/xAPI.md index 90722649..49057b2e 100644 --- a/xAPI.md +++ b/xAPI.md @@ -300,35 +300,32 @@ _high-level overview_ of a given facet of the Experience API are labeled **descr ### 2.1 MUST / SHOULD / MAY -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 best practices. 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). +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. +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 +### 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. -Tables are used throughout this specification to define the data structure of objects. 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. +Tables are used throughout this specification to define requirements for lists of properties, parameters, etc. +The tables define which propertiesare 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 best practice is given, or an optional implementation, it should be understood that any -instructions following are only necessary if said optional piece is used. That is, if it is implemented, it is -done a certain way, but it doesn't have to be implemented. +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 From 9455612a3a4a0d3720fd5d023fc89fea02f279fb Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Fri, 7 Aug 2015 13:55:31 -0400 Subject: [PATCH 12/16] Split into 8.0 and 9.0 Now 8.0 and 9.0. Also incorporated suggestions. --- xAPI.md | 42 ++++++++++++++++-------------------------- 1 file changed, 16 insertions(+), 26 deletions(-) diff --git a/xAPI.md b/xAPI.md index f1b977f4..ee85f933 100644 --- a/xAPI.md +++ b/xAPI.md @@ -507,49 +507,39 @@ __Verb__: Defines the action being done by the Actor within the Activity within ## 7.0 xAPI Components -## 8.0 Getting More Out of xAPI -xAPI focuses on the structure of communication between a client and an LRS. It spares many details of the content to -increase flexibility. The intention in only supplying a basic amount of syntax rules is that Communities of Practice (CoP) can define content (verbs, activity types, contextual relationships, extensions, etc.) for their use cases. It is very -important that such communities exist and share best practices. -### 8.1 Extending xAPI +## 8.0 Extending xAPI -xAPI can be extended in a few ways. The most notable and extensive 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. +xAPI can be extended in a few ways. The most notable and extensive 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 way xAPI enables extensions. The LRS may find it useful to communicate features or -behaviors beyond this specification to activity provider. It is hoped that if more information is available about an -LRS, that the About Resource captures it. +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. It is hoped that if more information is available about an LRS, that the About Resource contains it. -Finally, the set of Resources implemented is not expected to be constrained by this document. While not explicitly -defined, this document suggests that no new Endpoints defined in future iterations of this specification will -begin with /extensions and that LRSs create other custom xAPI Resources there. +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 current Resources. -### 8.2 Profiles and Communities of Practice +## 9.0 Profiles and Communities of Practice + +xAPI focuses on the structure of communication between a client and an LRS. It spares many details of the content +to increase flexibility. The intention in keeping the specification somewhat loose is that Communities of +Practice (CoP) can define content (verbs, activity types, contextual relationships, extensions, etc.) for their use cases. It is very important that such communities exist and share best practices. A profile of xAPI is a set of rules and/or vocabularies applied to a valid xAPI implementation. Often, a CoP leverages many best practices to create a profile. -A profile will typically define some of the open-ended areas of the specification, such as identifying verbs, activity types, structure and domains for IRIs, and names/possible values within xAPI Resources like the State API. This is -referred to as creating a vocabulary. +A profile will typically describe in greater detail some of the open-ended areas of the specification, such as +verbs, activity types, attachment usage, extensions, structure and domains for IRIs, and keys/possible values +within xAPI Resources like the State API. This is referred to as creating a vocabulary. 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 , which fits the -traditional single learner, single online learning use case. - -xAPI Communities of Practice are groups that have common goals for tracking a certain domain that can utilize xAPI. -A CoP typically already has a certain vocabulary used, processes, and values. xAPI CoPs can define their own verbs, -activity types, extensions, and other parts of statements and resources to align with their group's needs. +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 . +field is the [Medbiquitous xAPI Interest Group](http://groups.medbiq.org/medbiq/display/XIG/XAPI+Interest+Group+Home). -The text below will be expanded to include all "coined" parts ##### Use in Communities of Practice From 67ccb06594b9e13243d928add6384d4425d94585 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Fri, 7 Aug 2015 14:17:48 -0400 Subject: [PATCH 13/16] 2 minor tweaks, some re-aligning Only the tweaks and line break adjusting --- xAPI.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/xAPI.md b/xAPI.md index 49057b2e..1c79cf4f 100644 --- a/xAPI.md +++ b/xAPI.md @@ -319,22 +319,21 @@ as such. This is especially true of longer, more, detailed explanations and of t be unintuitive and/or lengthy to dissect into a list of requirements. Tables are used throughout this specification to define requirements for lists of properties, parameters, etc. -The tables define which propertiesare required, recommended and optional. Generally, 'optional' relates to the +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. +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. +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. +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) From e623980b468431d8a5d7c8ea4609795a5cefc12c Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Wed, 12 Aug 2015 09:06:18 -0400 Subject: [PATCH 14/16] Revert "Part1 section8" --- xAPI.md | 34 ++++------------------------------ 1 file changed, 4 insertions(+), 30 deletions(-) diff --git a/xAPI.md b/xAPI.md index d02a15bc..9782b64c 100644 --- a/xAPI.md +++ b/xAPI.md @@ -533,39 +533,13 @@ __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.1 Extending xAPI -## 8.0 Extending xAPI - -xAPI can be extended in a few ways. The most notable and extensive 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. It is hoped that if more information is available about an LRS, that the About Resource contains it. - -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 current Resources. - - - -## 9.0 Profiles and Communities of Practice - -xAPI focuses on the structure of communication between a client and an LRS. It spares many details of the content -to increase flexibility. The intention in keeping the specification somewhat loose is that Communities of -Practice (CoP) can define content (verbs, activity types, contextual relationships, extensions, etc.) for their use cases. It is very important that such communities exist and share best practices. - -A profile of xAPI is a set of rules and/or vocabularies applied to a valid xAPI implementation. Often, a CoP leverages many best practices to create a profile. - -A profile will typically describe in greater detail some of the open-ended areas of the specification, such as -verbs, activity types, attachment usage, extensions, structure and domains for IRIs, and keys/possible values -within xAPI Resources like the State API. This is referred to as creating a vocabulary. - -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). +### 8.2 Profiles +### 8.3 Communities of Practice ##### Use in Communities of Practice From 713d691d7fda1c3bf7af5222be60195ff16c28f9 Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Wed, 12 Aug 2015 09:26:53 -0400 Subject: [PATCH 15/16] Restores garemoko's Version Should have all changes from @garemoko's PR --- xAPI.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/xAPI.md b/xAPI.md index 9782b64c..f7cb8312 100644 --- a/xAPI.md +++ b/xAPI.md @@ -533,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 -### 8.1 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) -### 8.2 Profiles +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.3 Communities of Practice +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. + + + +## 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 Tin Can 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 From b560bb6793e492948b422ad956f45ecd2d793c8d Mon Sep 17 00:00:00 2001 From: Andy Johnson Date: Wed, 19 Aug 2015 10:03:35 -0400 Subject: [PATCH 16/16] Kicked the Can ;) --- xAPI.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xAPI.md b/xAPI.md index f7cb8312..4d64507e 100644 --- a/xAPI.md +++ b/xAPI.md @@ -547,10 +547,10 @@ those listed in this specification can be implemented and co-exist with the Reso ## 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 Tin Can to be used in any context, including future use cases not envisaged by the specification authors. +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 +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