Context and Goals

[rswetnam]

In order to promote the wider adoption of the xAPI, I think that it's important that the document set out more clearly, the rationale for the xAPI and situate it's historical context more clearly. It should answer questions for both technical and non-technical readers such as "Why should i use it?" "What can it do that SCORM can't" I don't think these questions adequately set out in the document.

My own experience in reading the xAOI document the first few times was that the "helpful" Reading Guidelines in the description and rationale sections actually impaired my attempts to understand the document. Rather than just complain about this, I thought I would offer some suggestions on how the document could be improved in that regard through "pull requests" - now that I under stand what they are. But before doing this, there are a number of questions - some quite mundane and trivial - that I have that hopefully members of the community can help me with.

1. Why does the document not have the version number in the title? I think it should though this may be some requirement of the specializations world that I am not aware of.
2. In 2.0, it says that the "Experience API is a service that allows for statements of experience to be delivered to and stored securely in a Learning Record Store". I don't believe that the xAPI is a service. I believe it's a framework or a description of a framework. Am I missing something? Also, while API is prominent in the title and the discussion, it is never defined in the document. (I'm assuming that it stands for" Application Programming Interface") Should this not be addressed somewhere in the document?
3. What is the relationship with SCORM? Why was it decided to come up with a whole new title and spec rather than updating SCORM to include non LMS applications?
4. Why could learning experiences could not be stored in Learning Management Systems based on an updated SCORM specification?
5. What are the major benefits of allowing learning experiences to be stored in and queried from Learning Record Stores?
6. I am assuming that a primary goal of having the spec and the ADL oversee it is to promote interoperability between applications and Learning Management Stores. Is that true? Should that be stated i the spec?
7. What are examples of uses that the xAPI will be able to support that have inspired its creation that were not possible before it. For me the statement "Authentication services, querying services, visualization services and personal data services" given in the introduction as additional technologies that the xAPI is designed to support is neither inspiring nor instructive - as I believe that most of these services could be "supported" by existing frameworks and specifications.
8. What is the primary goal of the xAPI?

[garemoko]

Thanks for raising this issue Roger!

On points 1 and 2, I agree these are areas for improvement and I'd welcome if you'd like to make a pull request for one or both of those. Perhaps on point 2, we could say "The Experience API describes a service" instead of "is a service".

On your main point, my personal view is that this kind of background and selling of the benefits of Tin Can doesn't belong in the document itself. This document, I think, is aimed at people that have already been sold on the benefits and are looking to implement.

One reason for this is that the document, as a specification, is taken to be very precise. If we were to list use cases, for example, it could be taken to mean that we don't support the use cases that we missed out.

Another reason for keeping this stuff out is that the tighter the scope, the less work! Somebody would need to write all of that content and maintain it. if we can keep the specification focused, we can move faster and make the text we do have clearer.

[andyjohnson]

Hey Roger, let me answer these to the best of my ability.

1) Yes, we really should. In the major releases they have been part of the title, but we need to make that so on the "active" version. 2) Also needs work as you point out, it is indeed API. More accurately it is a framework consisting of APIs. Service enabler is more of what it is. 3) Not really part of the spec. SCORM has a certain scope and even some level of backward compatibility. xAPI is only really like the RTE of SCORM (so a scope change), is nowhere near backward compatible, and also has a completely different level of interoperability. SCORM was very tight, whereas xAPI is lose. 4) They certainly could, this is what the CMI5 effort is looking at. Those wanting xAPI didn't want to be "confined" to the single-learner and LMS required model. Truth is many of the possibilities of xAPI are POSSIBLE in SCORM, but just really tedious or difficult and are technology dependent. 5) I take this to mean in comparison to an LMS. If you knew an LMS would be interoperable with the data, there really wouldn't be a "benefit" to the LRS. The LRS is a subset of the LMS and can be viewed as the least common multiple of what is needed to run xAPI. 6) ADL is developing this spec as it sees it as value-added to the DoD especially and to the rest of the world as an important secondary "client". While this advancement isn't the primary function of ADL, we think it is worth pursuing as far as we can. We also view it as a key enabler of the ADL's vision of a Training and Learning Architecture (TLA). 7) My favorites are simulations, games, blended experiences, augmented reality, and expert vs. novice behaviors. The "services" get to the point of what you can do with the data rather than the types of experiences. 8) This will certainly vary by person because there are a lot of benefits - I'll say that "allowing a wider range of trackable learning experiences" is mine. The "trackable" implies interoperability, but the wider expresses more flexibility.

[rswetnam]

Hi Andrew:

I agree with the need to keep the document concise and the language precise. I do feel however, that by not stating what the purpose of the document is and the problems it is designed to solve - and not solve, we get a great deal of misunderstanding and needless disagreement about details in the document that could be solved if there was a clearly articulated statement and shared understanding about purpose, goals and scope. (e.g. security) Rather than adding sales bumf which adds to the clutter, I see a clearer statement of goals, objectives and context as something that helps us to move ahead more quickly. I'm prepared to take up that challenge..

Roger

On Mon, Dec 15, 2014 at 11:18 AM, Andrew Downes notifications@github.com wrote:

Thanks for raising this issue Roger!

On points 1 and 2, I agree these are areas for improvement and I'd welcome if you'd like to make a pull request for one or both of those. Perhaps on point 2, we could say "The Experience API describes a service" instead of "is a service".

On your main point, my personal view is that this kind of background and selling of the benefits of Tin Can doesn't belong in the document itself. This document, I think, is aimed at people that have already been sold on the benefits and are looking to implement.

One reason for this is that the document, as a specification, is taken to be very precise. If we were to list use cases, for example, it could be taken to mean that we don't support the use cases that we missed out.

Another reason for keeping this stuff out is that the tighter the scope, the less work! Somebody would need to write all of that content and maintain it. if we can keep the specification focused, we can move faster and make the text we do have clearer.

— Reply to this email directly or view it on GitHub https://github.com/adlnet/xAPI-Spec/issues/556#issuecomment-67048565.

Roger Swetnam p. 604-408-5703 c. 778-848-3118

[aaronesilvers]

WRT andy's comment below, it's important to note that an LRS is not required to conform to the xAPI specification. It is a way and the spec does encourage employing an LRS, but to be clear, one can simply apply the data model to activity providers and send statements to any any endpoint, such as a Postgres database.

-a-

---

mobile

Aaron E. Silvers | MakingBetter

857.34.BEARD | @aaronesilvers

Let’s meet! Pick a time.

On Monday, Dec 15, 2014 at 2:42 PM, Andy Johnson notifications@github.com, wrote:​

5) I take this to mean in comparison to an LMS. If you knew an LMS would be interoperable with the data, there really wouldn't be a "benefit" to the LRS. The LRS is a subset of the LMS and can be viewed as the least common multiple of what is needed to run xAPI.

[aaronesilvers]

Roger,

The challenge of stating the intentions behind the development of xAPI is, as Andrew Downes alluded to, a story that will change over time and so the narrative itself must be maintained. 

And then, who is to own that narrative? Groups write specifications well enough and that takes discussion, debate, trolling, reconciliation, etc. it's a process just to get on the same, objective technical page. Narratives are subjective.

The messy reality is there are many reasons that overlapped and reinforced each other that brought xAPI into being. A strong narrative arc is that of addressing longstanding limitations of SCORM, but that is not the main reason the (now called) TLA gained the attention of the CNRI and ADL in 2009-2010. 

For so many reasons, these stories of our sausage making should be retold… just not in the spec, imho. ;)

-a-

---

mobile

Aaron E. Silvers | MakingBetter

857.34.BEARD | @aaronesilvers

Let’s meet! Pick a time.

On Mon, Dec 15, 2014 at 2:51 PM, rswetnam notifications@github.com wrote:

Hi Andrew: I agree with the need to keep the document concise and the language precise. I do feel however, that by not stating what the purpose of the document is and the problems it is designed to solve - and not solve, we get a great deal of misunderstanding and needless disagreement about details in the document that could be solved if there was a clearly articulated statement and shared understanding about purpose, goals and scope. (e.g. security) Rather than adding sales bumf which adds to the clutter, I see a clearer statement of goals, objectives and context as something that helps us to move ahead more quickly. I'm prepared to take up that challenge.. Roger On Mon, Dec 15, 2014 at 11:18 AM, Andrew Downes notifications@github.com wrote:

Thanks for raising this issue Roger!

On points 1 and 2, I agree these are areas for improvement and I'd welcome if you'd like to make a pull request for one or both of those. Perhaps on point 2, we could say "The Experience API describes a service" instead of "is a service".

On your main point, my personal view is that this kind of background and selling of the benefits of Tin Can doesn't belong in the document itself. This document, I think, is aimed at people that have already been sold on the benefits and are looking to implement.

One reason for this is that the document, as a specification, is taken to be very precise. If we were to list use cases, for example, it could be taken to mean that we don't support the use cases that we missed out.

Another reason for keeping this stuff out is that the tighter the scope, the less work! Somebody would need to write all of that content and maintain it. if we can keep the specification focused, we can move faster and make the text we do have clearer.

— Reply to this email directly or view it on GitHub https://github.com/adlnet/xAPI-Spec/issues/556#issuecomment-67048565.

Roger Swetnam p. 604-408-5703

c. 778-848-3118

Reply to this email directly or view it on GitHub: https://github.com/adlnet/xAPI-Spec/issues/556#issuecomment-67053905

[garemoko]

Seems like consensus is that we do need aims, but we don't need to make any changes to the spec. Can this be closed?

[rswetnam]

I suggest that Section 2.0 The Role of the Experience API be rewritten to address the following issues:

1. API is in the title but never referred to in the document
2. XAPI is wrongly described as a service - it is not - it is an an application programming interface or if you will a framework which describes an API

3.Although the xAPI describes an interface, the first line defines it in terms of one concrete implementation of that interface - namely as a service that allows statements of experience to be stored in an LRS Here's a first stab at the first paragraph

The Experience API (Application Programming Interface) - or xAPI as it is commonly called - is a framework that facilitates the description, communication and storage of learning experiences in a consistent manner in a digital environment. The purpose of the xAPI is to promote interoperability of computer programs that follow this framework. The xAPI builds upon and extends the Shareable Content Object Reference Model or SCORM that was developed to track users' progress as they took online computer-based training courses. Unlike SCORM, however, the xAPI is meant to deal with all types of learning experience, both online and offline.

The current version of that para is as follows:

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.

[andyjohnson]

Hey thanks @rswetnam. In response to the comments:

1) It is more accurately said a bundle of APIs: Statement, State, Activity, Agent, etc., but since they themselves have endpoints, etc. the larger work could be considered an API. Describing it as a bundle is probably a good thing to do as a part of the restructuring.

2) Agreed.

3) I like the direction your paragraph is going, but xAPI doesn't use much at all from SCORM and we are trying to scrub that notion out. While xAPI does have some common history in ADL with SCORM, it is completely standalone and doesn't need the history in this documentation in my opinion. We could say that xAPI tracking can go beyond that of traditional computer-based training courses, or something like that, but even that may be getting too grounded in history. I'd also avoid the online/offline comment as even SCORM could be used offline and not all xAPI solutions need to support both.

Overall, great catches and we'll have to get those in a PR soon.

[rswetnam]

I suggest changing the title of Section 2.0 to Overview or Introduction from Role of the Experience API since a couple of the subheadings have nothing to do with the role.

2.0 Introduction

The Experience API (Application Programming Interface) - or xAPI as it is commonly called - is a framework that facilitates the description, communication and storage of learning experiences in a consistent manner in a digital environment. The purpose of the xAPI is to promote interoperability of computer programs that follow this framework.

I also suggest removing the second paragraph since the xAPI does not provide Data Transfer methods for the storage and retrieval of Objects to/from a Learning Record Store nor does it provide security methods allowing for the trusted exchange of information between the Learning Record Store and trusted sources as stated there

[garemoko]

I may be missing a technically, but a good bit of the spec is about transferring data in the form of objects that are stored and retrieved. The security section is here: https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md#security

[rswetnam]

I suggested earlier in this thread some of the inaccuracies that I felt were in 2.0 - Role of the Experience API. Here I will suggest some changes and my reasons for them. Here goes...

2.0 Introduction

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:

1. To maximize interoperability and reliability of computer programs which create, gather and store information about learning experiences
2. To provide a guide to computer programmers who want to build applications that conform to and implement this framework;
3. To provide users of these programs a description of features and capabilities that they can expect from them;
4. To provide the ADL that certifies conformance to this framework with criteria against which certification can be tested.

Remove following paragraph - although the xAPI talks about security and data transfer, it does not provide methods for implementing them as this paragraph suggests

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

Replace with 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. This is set out in Sections 4.0 and 5.0

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. This is set out in Sections 6 and 7.

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. This is also set out Sections 6 and 7.

[garemoko]

I'm all in favour of updating that introduction text but I have some comments on the text proposed. I wonder if this could be more easily reviewed and commented on as a pull request?

My main concern with this change is that I think the emphasis on computer programs and programmers is unhelpful. Certainly programs written by programmers will be on the front line of interoperability, but the goal is interoperability of the wider systems that these programs are part of.

A more minor concern is that the term 'specification' is more commonly used than 'framework' in referring to xAPI.

[rswetnam]

Hi Andrew:

Your point about over-emphasizing computer programs and programmers is well taken and I will have another go at it. Before doing so, I'd be interested in your thoughts about including Application Programming Interface in the title of the document (xAPI)? Is there a reason that it is there or should we think of xAPI in similar terms as the Xke in Jaguar - a kind of sexy name but with no real meaning - I think?

[garemoko]

@rswetnam Just to check I've understood; are you suggesting changing the name of the spec?

I definitely don't think that changing the name of the specification after there's already a ton adopters using that name is a good idea, regardless of any arguments for and against the good-ness of that name.

[rswetnam]

No - I'm not suggesting that the name be changed - I'm just wondering if in fact the we should be saying that the framework/specification is in fact an Application Programming Interface as suggested by the acronym xAPI.

[garemoko]

I don't think it is an API itself, despite the name, it's a specification describing an API.

[fugu13]

API is commonly used to describe specifications for their implementations, which are also called APIs. The term's more than a bit overloaded ;)

[garemoko]

can we close this now it's been answered?