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

[Jim D. <jim...@po...>]

Hi Stuart,

thanks for these.

2008/8/27 Stuart Lewis <sd...@ab...>

> 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?


Noted.


>   = 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.


I agree - my notes don't make it clear why I didn't use 415 in both places.
It's possible I was trying to signal a difference between Content-Type
support and X-Format-Namespace support, but that kind of distinction can be
made in the message.

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


I really meant that in the sense that secure trust establishing standards
should be preferred to relying solely on SWORD mediation. I'll reword the
section.

  = 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)?


I'm glad you asked that question :-) I realized that there was a problem
with the mediation specification in 1.2: a number of cases were described,
and servers were expected to behave in a slightly different way for each,
but didn't have any way of working out which of the cases applied for a
particular deposit. Rather than having yet another header to represent this,
it seemed easier to simplify it to a single, predictable behaviour. The
second reason is that most of the time SWORD is conceptually creating a
resource to represent the deposit action, and will link through to the
payload resources, which can have the X-On-Behalf-Of user as the author.

The only situation it seems a little skew for is where the user is mediated
by a user agent. At least, though, the user agent knows that it performed
this kind of mediation and the server's metadata is predictable.

As an aside I'd note that this issue would disappear if multipart AtomPub is
adopted in the future: clients could assert whatever author and contributor
they felt appropriate.

  = 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'?


It seems like useful guidance to have, and it's probably too brief to form a
whole user guide on its own. I'll add this unless anyone objects?

  = 6 Service Documents
>  - sword:verbose and sword:noOp both say 'SHOULD be included'. This is
> contradictory to section 3 (developer features) which specify 'MAY'.


An error, but nonetheless a useful issue to discuss. I think MAY is more
sensible, but SHOULD is required if we want compatibility.

  - 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.


We need to make a decision on what level of back and forward compatibility
we want between 1.2 and 1.3. There are a number of things that could be
changed if compatibility is desired. I've started at a point of trying to
make 1.3 compatible with AtomPub and 1.2, preferring AtomPub where 1.2 broke
AtomPub.

  = 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.

I don't think it has been discussed beyond being on the desiderata list for
1.3. It seemed like the simplest way. There needs to be a little more
guidance on it: for example, you shouldn't be able to commute values for
e.g. sword:noOp from a service document to a child service document.


  = 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)?


Yes, I suppose that it SHOULD return 410 Gone.

  = 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.


As Scott pointed out, atom:generator is usually used for the feed generating
software, i.e. it identifies the server software. As far as I can see
AtomPub doesn't provide a mechanism for identifying the client. I don't
think we should change the semantics of atom:source in the way specified in
1.2, so if we want client identification, we should probably add a
sword:client that can contain an atom:generator element. Using User-Agent to
populate this makes a lot of sense.

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)



Do we have a policy on how many votes constitutes a quorum?


> > 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?


Do you mean 'both' or 'either'. 'either' pushes the implementation effort to
the client, so I'd prefer it to be 'both' or in just one place.

> 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?


True - although it's the potential to move all the X headers into an XML
document that's probably the main goal.


> > 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?


I'll get in touch with Pablo to come up with an example and a proposed
mechanism.

Best regards,
jim