adlnet/xAPI-Spec — pull request #57 by bscSCORM (2013-02-09 23:25:59+00:00)
Title: Added proposed attachment feature DISCUSS BEFORE MERGE

This is a proposal for how to handle binary data in statements.
As I wrote up the details, I change the approach from what we discussed in Alexandria, and in the email dicussion with Nik, for reasons I will describe below.

GitHub issues related to the PR:
https://github.com/adlnet/xAPI-Spec/issues/38
https://github.com/adlnet/xAPI-Spec/issues/23

Note that this proposal specifies the use of "multipart/mixed" as a transmission format to handle attachments, rather than using base64 within the json as we had previously discussed. This is a break from the model of "The transmission format of a statement matches the logical model of a statement". Breaking from the model used elsewhere in the spec will add some confusion, so we should not do it lightly. However, we do gain the following advantages:

* Systems receiving statement streams with attachments will be able to inspect the statement(s) before receiving the attachment, and may therefore validate the rest of the statement(s) before storing the attachment(s).
* Attachments may be sent without applying any encoding (such as base64)
* Avoids having a sub-property of the statement JSON which is sometimes included, and sometimes not (the attachment binary is now always outside the JSON)
* Maps very well to the mental model of "email attachments", which the binary feature was emulating in some regards anyway

Additionally, please note that I had discussed in an email with Nik pulling in some concepts from Activity Streams attachments. I wound up not including most of them for the following reasons:

* md5: this is insecure and shouldn't be used. Still, it might have been worth including for compatibility with activity streams, if the SHA-2 wasn't required. However I wanted to require SHA-2 to ensure the integrity of statements where the headers may have been retrieved earlier and then the client goes back to retrieve the data. If one accepts that SHA-2 should be required, also allowing md5 to be included adds nothing.
* compression: This seemed like a nice idea when I first saw it (see Nik's email), but most formats we'd want to include are compressed to some extent anyway, and HTTP itself already supports compression, and servers are free to compress the attachments once they receive them. Additionally, since I wanted the LRS to verify the SHA-2 to ensure statement integrity, what is more useful is the SHA-2 of the uncompressed data... this stopped sounding like a good idea.
* data: since the actual attachment is now being transmitted outside the statement, and TCAPI only defines transmission, not storage, there is no use for this property.

Note, that even without the specified fields, it is possible to convert from an activity streams binary to a Tin Can binary (provided the actual data of the attachment is available). We will not be able to use this attachment feature to represent an activity streams binary object that points to a dead URL, but that could always be done in an extension. And a reference to a dead URL is of limited use.