My takeaway from reading xAPI specs: I wanted to have a memo easy to read and memorize on what I learned from xAPI so far. Reading a standard is not the most enjoyable read one could have. I did it, have some questions, things I surely misunderstood and I take this occasion to surface them. I have opinions also but I wish to make sure I understood clearly the choices, so let’s do homework first, we are in learning aren’t we ? Minor remarks are prefixed by IMO. Why I’m interested in eLearning and xAPI as architect of Kneaver ? What could be the use of xAPI for KM and PKM ? I plan another paper on that. Before going further I wish to remind that I’m not an eLearning expert, I’m just an observer of the learning community. The need: Keep track of stakeholders various experiences contributing to their learning path.

We deal with:

LRS aka Learning Record Store, a minimal abstraction of what is needed to record and share the learning experience. It could very well be the LMS itself viewed from an LRS perspective, or it can be a dedicated LRS server, or a proxy (something that just moves data back and forth across the doorway). LMS aka Learning Management System. Those exists already, most readers will have more experience of them than me. AFAIK they are large systems with multiple aspects and features to keep track of who gained which competency, how, contents, lessons etc… How LMS interacts/relates with LRS is not covered here. IMHO Since many statements recorded in the LRS may very well never make their way to the LMS it’s perfectly sensible to consider them as very distincts. Activity Provider: the software sending the statements. It could be a front end facing the learner (Articulate, Browser) or it can be a server side app (like the SMS/Twillio sample from SaltBox) or it can be a background task sitting on top of some stream of events (Reading tweets for example). In many cases the Activity Provider will also be the grader in charge of deciding if the action was completed, successful and fixing the grade if one is attached. It’s important to remember that statements are sent once for all, they can’t be deleted or modified. IMHO in many cases the activity provider will not be facing the user if only to ensure robustess, data protection, confidentiality of grading. Client: A software using the xAPI. Outside from Activity providers, clients can be report generators or replication engines. Stakeholders: They are not defined as learners, teachers, mentors or anything. Each statement will provide the semantic necessary to make sense of who the stakeholders are. Since statements are based on the metaphore of activities the actors of the statement will be the one acting, taking decisions and steps to achieve the change of state corresponding to the action. It can be a single individual and will be called agent or a group. FOAF has a better terminology where agent are precisely the abstract concept above individuals, groups), Kneaver follows FOAF. Stakeholders may also appear in the context as the instructor or as the object (sic). Technology background: xAPI relies on HTTP, REST, OAuth, JSON, MIME, Signing. If you are not familiar with this it’s likely you will use xAPI via libraries or gateways taking care of it for you. If you are familiar with these technologies it sufficient to know that they are used in a predictable way with a few deviation to accomodate pure browser based client (Cross Origin stuff see Appendix A and B). Details like end point, client keys, secret keys, actual capabilities will be provided by the choosen LRS. IRI must be clarified since it’s not yet very common and it’s used in many places. What we become accustomed to are URL (L like Locator). That’s what you see in your browser ‘s navigation bar. http://kneaver.com/bruno for example. Syntacticaly it starts with the scheme (usually a protocol) followed by a colon, it uses only letters between a and z, digits, and some signs like / @ ? = - etc, no spaces, no accentuated characters, it can be resolved AND it points to something that be fetched. You keep the same syntax but accept that it resolves (we can tell where it should be) but don’t imply that there should be a page there it is called a URI (I like Identifier) and serves to uniquely identify stuff. http://kneaver.com/solar/earth/moon could be used as URI for the moon for example. If you accept all types of alphabets and letters it becomes international and is called a IRI. Internally IRI can be encoded as UTF8 and map to a unique URI, there is a one-one correspondance. example: http://kneaver/com/ma première leçon is a IRI (it contains accentuated characters and there is no page there) http://kneaver/com/ma+premi%C3%A8re+le%C3%A7on is the corresponding URI . (encoding is here http://www.url-encode-decode.com/ ). The benefit of the IRI is that it stays readable. Note that 2 encoding applies, first to UF8, then url encoding. see ref here http://tools.ietf.org/html/rfc3987 and here http://jero.net/articles/iris-uris-urls . There is not such thing as IRL, IRI are always abstract and must be converted to URI before trying to fetch a page. What will come to the web server is GET /ma+premi%C3%A8re+le%C3%A7on . (IRL do exists but it’s again different). An important consequence even for the english language is that spaces and punctuations MAY be used without encoding in IRI. It seems that not everyone agree:  (http://lists.w3.org/Archives/Public/uri/2002Nov/0032.html), http://answers.semanticweb.com/questions/8244/how-do-you-handle-non-iri-compatible-urirefs. See on the standard 3.1 page 12 ). IMO it’s better to stay away from spaces. NB: When statements are sent they are inside JSON format which is itself UTF8 encoded, so when reading a JSON text with a raw viewer one would see the IRI encoded in UTF8 but not yet url-encoded. They can’t be compared with the 2 steps encoding to URL So beware when directly editing json. Important: As will be seen below xAPI imposes that some IRI must actually lead to a real object. Specs says for example “Anyone establishing a new Verb SHOULD make a human-readable description of the intended usage of the Verb accessible at the IRI.”. So I want a new verb “tweet” defined with IRI http://kneaver.com/xAPI/verbs/tweet I must make sure that something human readable (html for example) will be available at this IRI. The best is may be to use the TinCan Registry. LRS are supposed to test the existence of the verbs IRI, faillure to get the human description may lead to latency in statements recording.

Records

We deal with 4 types of objects or records : Activities Profile, Agents Profile, States on one side, Statements on another,

Documents

Let’s start with Activities Profiles, Agents Profile and States. The spec call them collectively document API because they follow the same pattern. Contentwise they are merely pairs (Name, value) providers. They support all 4 CRUD operations (Create = PUT, Update = POST, Read=GET, Delete=DELETE). They could be used to keep some settings, transient data (like what was the last step of a user of a group of activities). Note that since we don’t have indications of expected performance and concurrency they should be used wisely.

Statements

The statements themselves are made of attributes. They are based on the metaphore of an activity: <actor> <verb> <object>. These 3 attributes are the very minimum a statement must have.

Verb: The fact that we use the term activity underlies the fact the verb will be an action verb not a state or descriptive verb and not in it’s progressive form. Because the statement is issued after the activity took place and can’t be on progress the verb will frequently end up being used on its past tens like in “A did that”.

Actor: It’s more precise than subject because the actor is the agent ( individual) or  group (of individual) causing the action to happen. This is an easy guideline for choosing who is the actor and who stays in the context.

Object: It is really depending on the verb and the semantic. xAPI allows the use of:

- an activity

- an individual or a group

- another existing statement (it must have an ID already)

- a sub statement (futures and substatements will not be discussed here).

Next we got 3 attributes that can be set by the Activity Provider or by the LRS if it is not supplied.

ID : This is a UUID, something used very frequently in IT when we need an identifier we are sure to be unique. Most operating system have a function to generated a UUID in a clean way using the internal clock and some unique characteristic of the device like the MAC address. A UUID looks like 994376276b3e3f0b26dabc319fe7f25b529c3a5b. when the Activity provider don’t supply the ID the LRS will compute one and return it upon insertion. This ID is important to set objects of subsequent statements as reference to this statement.

timestamp: In ISO ISO 8601 format, looks like 2013-05-18T05:32:34.804Z, defaults to store time. Timestamp can’t be in the future.

authority: Who asserted this statement. Defaults to the credentials of the Activity Provider.

version, stored: Two attributes set by the LRS. Next attributes are optional: result, context, attachements. result is itself made of several attributes. I list them in order of importance IMO. - completion: true, false. IMO if completion: false the rest of the values are not very interesting. - success: true, false. Here I’m not sure it we have to consider success is the large sense, the activity was completed properly or in the grading sense the activity led to a successful assessment. I would guess the last meaning. - score: a value with lower and upper range. No indication if it is passed or not. - response: some string. - duration: duration of the activity. - extensions: name, value pairs used as desired. Keep her what results from actor actions as opposed to the same extensions in context where one would keep informations independant on actor actions. context is very open. - instructor: an “agent” - team - contextActivities - revision - plateform: I would put the name of activity provider here - language - statement - extensions: name, value pairs used as desired attachements Files can be attached to a statement. Part 2 coming soon