Re: [sword-app-tech] [sword] Fwd: SWORD 1.3

[Stuart L. <sd...@ab...>]

Hi Jim,

First off, thanks for writing this spec - it is a great document.

Here are some comments / issues with the document (nothing very big):

 = Editors
  - Please cold you change Neil's and my affiliation to 'Aberystwyth
University'. Richard: Does yours need changing now too?

 = Document Structure
  - Small typo: "this document describe the" needs an 's' on describe?

 = 1.2 Package support during resource creation
  - In the second paragraph you have that we SHOULD return a 400 (Bad
request). This is different from 1.2 of the spec which uses 415 (Unsupported
Media Type) which seems a better fit, and is contradictory to the last
bullet point in 5.5 which says to use a 415.

 = 2 Mediated Deposit
  - Is it a bit strong to say OAuth should be preferred by implementers?

 = 2.1 Mediation In Service Description
  - In the example service document, you still list <sword:level>. More
about this later.

 = 2.2 Metadata Interractions In Mediated Deposit
  - Typo in Interractions
  - Why is the X-On-Behalf-Of listed as contributor, and the depositing user
as author? I can see why it is this way round, but it somehow feels wrong as
the X-On-Behalf-Of-User is probably the author, and the depositing user is
just helping (contributing)?

 = 4 Auto-discovery
  - Were we going to suggest that there can be a link rel on a collection
web page to a service document specifically for that collection?
  - Should we recommend that the link rel of the master service document
appears on the repository home page if possible, as the 'relevant HTML
document'?

 = 6 Service Documents
  - sword:verbose and sword:noOp both say 'SHOULD be included'. This is
contradictory to section 3 (developer features) which specify 'MAY'.
  - sword:level: Can we just dump this requirement? AFAIK there are no real
production users of SWORD yet who couldn't easily change their tools, so
shall we drop it while we can? If we're not dropping it, most other service
documents in the spec are missing it.

 = 8.1 Workspaces
  - I see the addition of sword:service. Have we discussed this (how it
would be implemented rather than should we have them), I don't remember?
Either way, I think it is a neat addition and would work well as specified.

 = 9.6 Media Resources and Media Link Entries
  - Does the second paragraph need some clarification about what should be
returned by the location: element in the event of the deposited file having
been deleted (e.g. rejected during workflow)?

 = 9.8 The Atom Entry Document
  - atom:generator - Should we recommend the use of the standard
'User-Agent' header? A lot easier than multiparting just for the sake of it.


And some responses to your questions:

> 1/ sword:formatNamespace and X-Formatnamespace aren't particularly well named;
> sword:acceptPackaging X-Packaging seem more appropriate. I erred on the side
> of not changing things.

+1

I think we are still just about at the stage where we can get away with
these modifications. Just look at some of the big changes between minor
revision numbered APP docs... :)   (e.g. what MIME type service documents
should have)
  
> 3/ How does the server obtain the identity of the client to use in the
> atom:generator element? There's no header for it.

As above - User-Agent header?

> 4/ I'm ambivalent about whether the error-codes should be in headers or in a
> document. If we want to enforce back-compatibility the headers will have to be
> supported in either case.

Maybe both? Codes in the header, descriptions in the document?
 
> 5/ Adopting the multipart proposal would solve some issues (e.g. the
> atom:generator issue above). It would mean a bit more complexity to the
> authentication / mediation section. Also, it seems premature to base SWORD on
> a draft RFC. Thoughts?

Yes - perhaps a bit premature, but shows a lot of promise. Also not needed
so much if User-Agent is OK?
 
> 6/ Pablo at MS requested a "preferred format" feature in the collection
> element of the service document, or alternatively a @preference attribute
> containing an ordinal number. Would others find this useful?

I think it would be useful. Can we come up with some concrete examples where
this is required or very useful in order to help justify it?

Cheers,


Stuart
_________________________________________________________________

Gwasanaethau Gwybodaeth                      Information Services
Prifysgol Aberystwyth                      Aberystwyth University

            E-bost / E-mail: Stu...@ab...
                 Ffon / Tel: (01970) 622860
_________________________________________________________________