I've now read through the SWORD proto-internet-drafts 001 to 004, and skimmed parts of the profile. While I think the reorganization of material towards possible standardization is a useful start, I think there is a lot of work remaining to do.
The SWORD 001 to 004 documents, which I take to be those which might in due course be considered for standards track submissions, are way too perfunctory, and much of the specific normative material that they invoke is still described in the "application" document. I think the balance here is wrong: the detailed normative material should as far as possible be in the proto-standard documents, with the application document pulling the pieces together and adding application-specific elements. While I have many comments to make about the individual documents, I think it's worth standing back and trying to sketch what I think the overall approach should look like. ... My starting point is that SWORD is an application and "thin" extension of AtomPub and Atom, themselves applications based on HTTP and XML respectively, which is intended for deposit of scholarly materials. The extensions should be chosen very carefully to be (a) a minimum set of extenstions that satisfy the application goals, (b) to the extent possible without adding undue complexity to be generically useful to other applications that use HTTP, AtomPub and/or Atom, and (c) to be orthogonal, defined and usable in isolation from each other and from the SWORD application as a whole. As such, I think it is important to emphasize the extent to which, and how, SWORD uses standard AtomPub and Atom features, and then to call out the small areas where there are gaps in the underlying specifications. Based on my reading, I think these are: (1) mediated transactions (2) packaged content (though I'm not yet clear why *packaging* alone is what is lacking). (3) server capability descriptions; though, in the case of collectionpolicy and treatment, this is information only intended for human presentation, so why not just have a description element. How do these differ from atom:category elements in a service document? An I have no idea what is the purpose of the service element. My point here is that the new descriptions introduced are not adequately described (in SWORD 003). Note that I've separated mediated transfers above from packaged content - I think these should be orthogonal issues. Taking each of these in turn: (1) Mediated transfers The extensions here consist of one new HTTP header field, and one capability declaration in an AtomPub service document. I think the latter might usefully be covered along with other capability descriptions. Different HTTP-based services might implement different capability discovery mechanisms. This leaves the on-behalf-of header field, which I'd specify in a separate document. It's hard to define full normative requirements on the use of this in protocol exchanges, so some specifics may need to be covered in the application document, but I think some of the material in the SWORD profile document (e.g. elements of section 6.1 - server responding with information restricted to that appropriate to the declared user) should be included with the specification of the header field. Also make mention of any appropriate return codes. Also, this will need a serious "Security considerations" section. (2) Packaged content I'm really not sure exactly why all the extension elements are needed. The only substantive normative statement of behaviour I have unearthed is that if a server received a deposit described as using a package format for which it has not declared support, then it MUST respond with 415. AFAICT, everything else here is just wishful thinking about what an implementer may or may not choose to do with the information provided. (It's not clear to me why "Accept-packaging" *and* the service document extensions are needed here. I'm also completely unclear what purpose is served by the atom multipart extension; I also think the use of content-disposition may be broken.) So, for interoperability, all we need is a way for a server to say "I support these features", form a submission to say "I depend on these features" and a status response for the server to reject any submission it cannot support. Under heading (3), we already see other ad-hoc mechanisms for a server to declare capabilities. Why not do this uniformly in some way. As I say above for mediated transfers, I'd separate the submission feature (HTTP header) from the capability declaration. (3) AtomPub server capability descriptions I find some of the specific "capabilities" confusing, as they are only presented as human-readable text. It seems to me that what would be more useful here is a way to declare both human- and/or machine-readable capabilities in the service document, with the specific capabilities used covered in the SWORD application document. ... I have noted many more detailed comments, but I won't post them immediately as I think they could, or should, be overtaken by discussion of the overall structure and organization of SWORD. #g ------------------------------------------------------------------------------ Xperia(TM) PLAY It's a major breakthrough. An authentic gaming smartphone on the nation's most reliable network. And it wants your games. http://p.sf.net/sfu/verizon-sfdev _______________________________________________ Sword-app-techadvisorypanel mailing list Sword-app-techadvisorypanel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sword-app-techadvisorypanel
