adlnet/xapi-spec

The xAPI Specification describes communication about learner activity and experiences between technologies.

xAPI-Spec

This Github repository contains the xAPI Specification. xAPI is a learning technologies interoperability specification that describes communication about learner activity and experiences between technologies. The specification is divided into three documents:

• Part One: About the Experience API
• Part Two: Experience API Data
• Part Three: Data Processing, Validation, and Security

Specification versions

This is an old version of the specification found at 1.0.3.

The current version of the specification is xAPI 2.0.

The next version of the specification has not been planned.

What to do if the spec is unclear

If when implementing the specification you find something is unclear or unhelpful, you can help to improve the specification by raising an issue here. When raising an issue, please give as much detail as you can in regards to:

• Which part/parts of the specification you are reading.
• Your understanding of what these parts mean.
• The product and feature you are implementing xAPI in; what's the use case you are trying to achieve?
• How you would like the specification to be improved. Suggest some specific new wording if you like!

You'll need to sign up for a GitHub account if you do not already have one in order to raise and comment on issues.

You can discuss any issues before or after raising them on the specification Google Group and at our weekly specification calls.

How you can contribute

You'll need to sign up for a GitHub account if you do not already have one in order to contribute to the specification.

The xAPI Spec Working Group meets the first and third Wednesdays of each month at 2:30 (US Eastern) on GoToMeeting. You can join at https://global.gotomeeting.com/join/686232837

The xAPI Conformance Testing Working Group meets the second Wednesdays of each month at 2:30 (US Eastern) on GoToMeeting. You can join at https://global.gotomeeting.com/join/686232837

Please refer to the Contribution guidelines for further direction and a list of contributors.

xapi-spec's Issues

Activity and Verb Metadata

TODOs from working group meeting:

COURSES OF ACTION:
TODO: 1 - change to JSON from XML within spec
TODO: 2 - define JSON format
TODO: 3 - allow any type of metadata at URI (LRMI, microdata, RDF, etc)
TODO: 4 - do the same for verb metadata
TODO: 5 - create 2 content types (application/json+XXX)
TODO: 6 - it may simply be a human readable document
TODO: 7 - ADD ‘url’ field to activity definition for ‘read more’ or ‘launch

Activity Versioning clarification

Clarify activity section stating, activity version is handled outside of the scope, use the revision field in context to handle versioning, but LRS doesn't need to interpret it.

URI equality and case sensitivity

We should add explicit language to avoid ambiguity when comparing URIs such as:

http://example.com/foo/bar
http//example.com/FOO/bar
http//EXAMPLE.com/foo/bar

According to the URI spec, 1 and 3 are identical, but 2 is different from 1 and 3. (the host name part of a URI is case insensitive, the rest is case sensitive.

This is likely enough to be overlooked we should add some "MUST" language to ensure all systems handle URI equality the same way.

PUT activity and agent?

Morning all,
I notice that the Agent and Activity resources (not activity/profile and agent/profile) have no PUT method.

For activities, this could be a useful way of the AP providing a canonical definition (I think we may have discussed this previously?) It would also allow the activity to add its definition to the LRS as a separate task from sending statements so it could always just use activity id in statements. The AP can already do this by using some otherwise meaningless statement using a registered or updated definition verb or some such.

If we're doing this for activities we should also do this for agents.

Thoughts?

/about resource for LRS

"about" would be a sibling of the other resources (statements, state, activities, agents).

The purpose would be for API consumers to gather basic information about an LRS. This resource would only respond to "GET", would not require any authentication, and would not check the version header of the request.

The response would be a JSON document that contains:

• Version
• Extensions
• (anything else we decide to add... I can think of other possibilities, but I think these might need more time to 'bake' before going in in a later version, such as:)
  • auth types supported
  • administrator contact information
  • statement size limits etc

For 1.0 I think this should just be version & extensions.

Modify query options? (need ISD input)

Need ISD input. We talked briefly about changing this up, and it seemed like there were needs.

Context Activity Update (need ISD input)

Clarify/add in section 4.1.6 under context activities-

-Recommend 0 or 1 parent

-Allow array of activities

-Strong guidance on use of multiple parents and indication that context applies to the statement, not the activity

-Consider backwards compatibility with v0.95

shall vs must

Hi,

See this issue on the cmi5 github:

AICC/CMI-5_Spec_Current#11

Anybody over here care to comment?

Andrew

7.1 Error codes needs some "MUST"

Error codes mentioned in 7.1 should be requirements for the LRS, not optional.

Definition of an activity

Update section 4.1.4.1 to better clarify what an activity is. From the work group - 'Activity is a thing with which to be interacted."

Potential Use Case - Complex Branching Scenario Results

I have a level 3 courseware with the ability to serve learning activities within a single frame or page with sequencing on. This is 2d gamefication or a complex graphic novel type of activity that has multiple outcomes but only certain outcomes are acceptable to allow forward progress. The 3 outcomes can be configured multiple ways; they are Success, Acceptable, Fail (or Green, Yellow, Red). The ID has the option to require a certain outcome or outcomes in order to register the activity complete and allow forward progress Hinting is also an option via a hint button that appears or automatically when the learner chooses a questionable path. Each time the learner hits a branch they also have the option to restart the entire scenario. I should be able to capture all results as the learner attempts, multiple attempts, Hints, Ticks etc.
My team is in the beginning stages of setting up a local LRS and work this issue with current specs. I don't know if it is helpful or not to post.

Attachment Example

I promised to create an example attachment for the binary data/attachment feature.

activity and learning activity

We now have two definitions of activity. These need to be merged.

Definition of the word "Activity" in the spec

Clearly this needs clarification.

I suggest we include a definition that maps to current and anticipated usage. That is, change what we say to match what we meant.

Use of Activity Definition Types

Add something about using activity definition types from the companion document, the activity streams project (if they have them?) and repositories.

Use of verbs

Add something about using verbs from the companion document, the activity streams list and repositories.

Extension Profiles

We need to add a section on extension profiles. I suggest either before the statements section or before the Runtime Communications section. My preference is for the later.

heading sizes

Headings need to be standardised. I suggest

Experience API (1 hash)

1 Statement (2 hashes)

1.1 Top level property (3 hashes)

1.1.1 next level (4 hashes)

1.1.1.1 next level and any deeper levels (5 hashes)

Rationale, details etc. (6 hashes)

Binary Data in Statements

From working group:

Can we add an icon , i.e image, for the activity URI?

TODO: look at common ways of defining metadata - common current methods should be used (ex. Open Graph, etc.) which could make some web pages themselves an activity definition
TODO: spec SHOULD provide guidance for LRSs and maximum sizes for statements

Timezone

The discussion on timezone here: garemoko@4c558de#xapi-md-P55 looks unfinished.

Do we need to look at the timestamp in more detail?

Also, "stored" needs to be updated to match timestamp.

stored/timestamp precision

Precision is stated specifically for the "duration" property of a result but I didn't see a precision specified for values for "stored" and "timestamp". Should such a precision be stated? Is this an "up to the LRS" type of thing? In the latter case if a "meta" object describing an LRS' feature set was ever in existence this should be filed with it (IOW, what precision can I expect for this LRS).

change heading example to details in result

Converting statements to other versions:

6.2 API Versioning:

• Systems MAY convert statements of older versions into a newer version only by following the methods described in the companion document.

When the above line went in, we were still thinking in terms of "the" companion document. We seem to be moving (reasonably so) in a direction of the ADL companion document being just the ADL profile, one of potentially many.

However: There MUST be only one way to do this conversion, and I suggest that it deserves being in an appendix of the specification itself.

Basic outline for what I'd like to see us define:

• mapping of 0.9 verbs to ADL profile equivilants
• handling of 0.9 actors with multiple inverse functional identifiers (this will hardly apply to any real statements, so I suggest we do something fairly naive, define a preference order like: account on a system, openId, email and then take the first IFP that we find in preference order
• for 0.95, voided statements are discarded

Should multi-statement posts be atomic?

We discussed in Alexandria that multi-statement posts should be atomic, however particularly with attachments this becomes potentially costly for the LRS. (see: #57 (comment)).

Max Statement Size

TODOs from the working group:

TODO: add to spec - LRSs may reject statements that are not of ‘reasonable and customary’ size
TODO: add conformance test for statements larger than ‘reasonable and customary’ size
TODO: add to spec - add guidance on creating large enough max DB field size that will accommodate most uses
TODO: recommend using a hash to store URIs as keys

Verb Registry

Marked as TODOs from working group:

-add to spec - Verb author SHOULD create a machine- or human-readable document (can use hash bookmark in human readable to create a single document)

-ADL will add the current human readable verb definitions at the URIs specified

6.4.2 OAuth Authorization Scope

The first few paragraphs here need to be reviewed to ensure clarity.

For example: the first paragraph states that "If no scope is specified, a requested scope of “statements/write” and “statements/read/mine” will be assumed." but the second paragraph states that "LRSs are not required to support any of these scopes except “all”." If the LRS does not support “statements/write” and “statements/read/mine” and no scope is specified, what happens?

Document API POST to store application/json doesn't specify behavior where no document exists

I'd like to clarify that if no document exists, this should behave like "PUT".

Any objections?

documents content type

The discussion here: garemoko@0e4d79a#xapi-md-P11

Never got actioned. If you have the time and ability to do this, please do!

Need consultation from ISD community on Parent and Grouping activities

The group proposed additional guidance with the ISD community to offer more guidance, but allow flexibility.

I find this reference "(see query API)" - but I cannot find the "query API"

I find this reference "(see query API)" - but I cannot find the "query API"

Is this misnamed ?

Backwards Compatibility

From the working group meeting notes, these were marked as TODOs and should be added in the spec:

Conformance Requirement: v1.0.0 LRSs should accept v1.0.X statements
-LRS Should reject anything 1.1.X+
-No new properties, params, etc that would cause breaking changes are allowed in a new build release - v1.0.0 LRS MUST accept 1.0.X statements

Guiding Principle - Each release contains the algorithm to upconvert from the previous statement format

More distinction between grouping & category in context activities

We should add additional language describing the difference between grouping and category in context activities, once PR #96 goes in

Statement Signing

This was brought up during the onsite spec meetings, but hasn't been talked out recently.

Ben Clark proposed:
“statement in statement” (https://docs.google.com/document/d/1wbfByhlWCzwbA89CdWrp00vR72YnSLY-F7PRzuSiUW4/edit)

Russel Duhon shared this also:
http://blog.saltbox.com/blog/2012/12/31/a-web-of-string-pki-signatures-and-the-tin-can-api/

"Targeted" statements query behavior example

We need a better example for the query behavior regarding targeted statements.

Common Access Cards

"Common Access Cards (implementation details to follow in a later version)"

Section 6.4, Security, states that one one method of authentication might be Common Access Cards and that details will follow in a later version. I suggest that for 1.0 we should either provide the details or remove it from the list.

ByRef ByVal Activities

Marked as TODOs from working group meeting:

• add a flag to show your intentions when querying (what’s the default? return exactly what was originally passed to LRS?) (this new flag might replace ‘sparse’)
  1 - return exactly what was reported
  2 - return the activity portion completely filled out, whether it was included in the originally reported statement
  • add clarification in spec so people don’t use example.com/test

Add more examples to Appendix D

We should have enough examples in Appendix D so that every property and object type is shown at least once.

What activity provider was the statement generated by

There should be a way to identify the activity provider that generated a statement.

• I want to find all the statements that were sent by "activity provider" where the activity provider is self-defined, but generally at a much higher level than an individual activity, eg: "Storyline" would be an activity provider, not each individual activity created in storyline.

Attachments should specify binary encoding

We probably need to add the header:
Content-Transfer-Encoding : binary

In the attachment portion of the spec. See:
http://en.wikipedia.org/wiki/MIME#Content-Transfer-Encoding

Eventual consistancy

We discussed and agreed that the API, or at least the statements resource MAY be "eventually consistent". This should be called out in the spec.

Furthermore, we discussed having systems push their "stored" times in to the future in order to enable synchronizing statements based on the "since" parameter. However, for this to work the clocks of the LRS and the client that is pulling statements to be exactly synchronized.

A more robust approach could be to say that the LRS MUST include a header in any response on the statements resource (or maybe any resource), stating the time that it is consistent through (in its own system time). This would tend to be slightly behind the real system time. Clients could then use that time as a "since" parameter with reasonable certainty that if they had previously gotten all relevant statements they would not miss any added statements by starting at this time.

Tag .95, branch for 1.x

Was looking to identify differences between .95 and what will become 1.0. It'd be nice to have a git tag identifying the last commit from what was originally .95 or at least no material changes from .95 and where 1.0 diverged. Since .95 was out when github became the source of truth the following was presumably the closest to the actual original spec:

https://github.com/adlnet/xAPI-Spec/blob/c924ef33f7e784ca42da39e93eae1b63c4690a62/xAPI.md

But I'm not sure that is the best tag for .95. There are numerous commits after it that might not have materially changed the spec so that it could be considered .95, but that might be better as the .95 spec to look at.

Going forward after 1.0 lands it would be nice that master remain at 1.0 and have a working draft be in a separate branch, or at least minimally 1.0 needs to get tagged on master when it is cut if master is going to be the working draft version.

Stored shouldn't be in the future

The following line should be removed from the requirements for 'stored':

MAY be a moment in the future, to denote a deadline for planned learning, provided it is included inside a SubStatement;

Not creating a PR for this at the moment as it would conflict with #96 , which fixes the case of 'substatement' in that line incidentally.

HTTP HEAD

We should clarify what the expected behavior is for HTTP HEAD requests to Tin Can resources. From the HTTP spec:

The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification.

If we embrace this requirement for Tin Can (and make it a "MUST"), clients will be able to do the following:

• check if a particular statement exists, or if statements matching a particular query exist
• determine the modification date of documents before deciding to load them (state, activity profile, actor profile)

If we don't do this, we should add some explicit language to indicate that clients should not rely on the HEAD method.

In order to avoid forcing the LRS to do a lot of work for what seems like a trivial request to the client, I suggest we exempt the LRS from returning an accurate Content-Length header in response to queries against the statements resource.

section 4.1.11 Metadata

I think this whole section should be deleted because I don't think it actually says anything.

Any objections?

Binary (potentially large) data in statements

CMI 5 requires the ability to include binary data in a learner's transcript.

This could be a PDF completion certificate, and image of the students work, an audio clip (simulated communication with ATC for example), even a (hopefully short) video of their work.

In order to avoid cluttering up results when a list of statements is pulled, we might consider an "attachment" approach similar to email.

Each attachment would be added to a statement with the title (possibly a brief description), the content-type (mime type) of the attachment, and the size of the attachment.

Clients querying an LRS for a statement list would be able to specify a parameter to exclude attachments , and only receive the above metadata.

The "exclude attachments" mode SHOULD NOT be attempted for transfer from one LRS to another, and an LRS MUST NOT accept statements with attachment headers but no attachments.

The attachment data itself would be stored as BASE64 in the statement, or as a link to where the attachment data can be found along with a hash of the data.

remove activity definition extensions

Hi,
I'd like to propose that we remove activity definition extensions and encourage people to use the activity profile API instead. This avoids people storing the same data in different places.

Thoughts?

Andrew

IE and http/https requests

PR 15 (#15) had a suggestion from Ben that never got actioned before the PR was merged. This still needs to be done. If you have time and skills to do it, please do!

Searching statements for keywords

Case:

The user wants to search their statements for some key words and view the results. For example say they wanted to view all their statements on a particular subject such as "Cars".

How this would be done currently:

At the moment the API does not support this kind of request directly.

To do this would require some middle-ware that would need to pull back all of the users statements, parse them and then search through them for the supplied terms, returning only those that met the condition. This could get very inefficient if the user has lots of statements.

Possible solution:

What would be really useful is a 'search_text' or keyword property on the statement object that can be populated with the text that should be searchable for the statement. For example if it is an 'Activity' then the search text could include the activity description. The GET statement API would also provide a 'search_text' property to enable searching.

context session

I notice that cmi 5 has separate session and registration properties. This could also be relevant to other areas e.g. handgliding.

Should this be include in the core spec?