The SWORD deposit receipt currently provisions the following identifiers
[SWORD spec section B.9.6], with the associated possible interpretations:
- An atom:content element which provides the URI to one of:
- The splash page for the repository item;
- A machine readable description of the repository item;
- The originally deposited package;
- Some combination of (i) and (ii) (for example, RDFa embedded in a splash page);
- Some other identifier, unspecified.
- An atom:link element with @rel=edit-media, which provides the URI to one of:
- A version of the resource which can be updated by HTTP PUT;
- A representation which supplies metadata from the package and access to unpacked binary files.
- An arbitrary number of atom:link elements with repository specific @rel values which may contain URIs for the parts of the unpacked item.
- An atom:link element with @rel=edit, which provides the URI to one of:
- The Entry document, from which an equivalent document to the deposit receipt can be obtained, and to which HTTP DELETE requests could be directed;
- A jump-off page;
- Users private metadata;
- A workflow management page;
- Some other identifier, unspecified.
As this shows, the specification does not say anything particularly strong about any of the URIs which are returned, while making allowances for the large number of uses the a repository may wish to make of them. This is interesting, as it is indicative of the requirements that we must find a way to formally support. We should, firstly, bring the meanings of each of these URIs into line with AtomPub thus [AtomPub spec section 9.6]:
- An atom:content element which resolves to the Media Resource; in the case of package deposit, the Media Resource is the package itself, and therefore this element provides a URI from which the originally deposited package can be retrieved.
- An atom:link element with @rel=edit-media which resolves to the Media Resource; since this is the original package, as noted in (1), this should resolve to the same content as the atom:content source during HTTP GET, but must also be able to support HTTP PUT of a new package. This means, therefore, that the server is free to use a different URI for this link to the one used in atom:content if that suits the implementation better.
- An atom:link element with @rel=edit which resolves to the Entry document; in the case of package deposit this would behave as follows:
- HTTP GET returns the Atom Entry document which is equivalent to the deposit receipt produced by the server;
- HTTP PUT has no defined behaviour, as it is used traditionally to update the item metadata, but since package deposit has no independent metadata this is meaningless;
- HTTP DELETE would allow us to request the deletion of the repository item itself, including the original package and the associated unpackaged content.
- An element which provides a link which resolves to another document which we use to describe additional repository specific information about the deposited item. This manifest document will be described in the next section.
- An element which provides a link to the splash page of the repository item if one exists; this page may also include embedded RDFa.
In addition to these, we should also introduce the following new links with appropriate semantics for our environment:
Notice that we have not specified how these additional new links should be serialised in Atom. There are two possible routes: to use atom:link elements with @rel values specific to SWORD, or to embed new foreign markup such as sword:manifest and sword:splash. The first approach is more in line with the Atom standard approach, but formal recognition of new @rel values is strongly suggested, and this requires passing through the IANA registration procedure [16]. The second approach will be easier to implement in the standard but be less in line with Atom.
We have also pushed a lot of the vague uses of the identifiers in the current SWORD specification into the link described in (4): this will give us the opportunity to define a document which can give the client all of the relevant additional information which the current specification alludes to.
The issue with all of this is that the repository (or whatever system) is going to “change” the submitted content. This could just be that it serialises it in a new form but it’s still a change. I agree however that it would be nice to support full CRUD on the repository using a set of URIs. I just don’t feel that you can ever get the “original” back, and you might not want to if you are actually interested in what the repository might have done with it.
This is also where with a GET request the client should use an ACCEPT header and ask for application/atom+xml to get the atom back. If the repository does not support this format… maybe it should…
#5 starts to get at one of the biggest frustrations with SWORD 1.3 responses (which is a good thing). In SWORD 1.3 there is no recommended place to return a link to the “splash page” in the response after a deposit. This essentially means that although a Client knows the deposit completed, it is unable to consistently forward the user to the splash page for their deposited item. It’ll be good to have a common specification here, as currently DSpace, Fedora and EPrints all return the “splash page” link in different parts of the ATOM response (or not at all). In fact, for Fedora and EPrints, last I checked they only return an object ID (not a resolvable URL).
It would be really useful to have a table of all the URLs a client needs to implement and what methods should be implemented. For example:
http://swordserver/serivce/item
POST – submit Atom Entry Doc
GET – return atom entry doc
PUT – edit atom entry data
DELETE – remove atom entry + media resource
I’ve got a question regarding the following
“HTTP PUT has no defined behaviour, as it is used traditionally to update the item metadata, but since package deposit has no independent metadata this is meaningless;”
How do you edit the metadata in the repository if you can’t update the atom entry document? I can imagine the case where someone sends across a deposit using a mistyped title and unless this method is implemented the user would have to go to the repository to change the meta data. If its possible to update/delete the media resource it should be possible to edit the metadata. Are there any issues with updating an items metadata from a updated Atom Entry document?
(1) It would be very nice if this were more loosely specified. Requiring that sword impls always persist and make available the original deposited package/media seems a big thing to ask. If the resulting document would allow a URN in the ‘src’ attribute, that would be really nice. A URN is an IRI, right
I interpret the resolvability assumption as a “should” rather than a “must”. Summary and rel=alt are prescribed coping strategies already in place.
“”"
The first approach is more in line with the Atom standard approach, but formal recognition of new @rel values is strongly suggested, and this requires passing through the IANA registration procedure.
“”"
It might be worth clarifying that, if you want to use @rel values within the IANA namespace, then you should go through the IANA registration process. But if you define link relations within another namespace, then no registration is necessary. Defining new link relations in a namespace other than IANA is, I believe, a common practice for defining extensions to AtomPub.
I would favour defining new link relations over foreign markup because it is already understood (i.e., part of the Atom media type definition) that the atom:link element represents a hypermedia control (i.e., a link). If you use foreign markup, a client would need out-of-band information to discover that sword:splash or sword:manifest is intended as a hypermedia control.
I’m no REST expert, but I believe this is the argument you would make if you wanted to respect REST’s constraints, in particular the hypermedia constraint.
I’m not keen on either when there is already another way. I feel that the URI given in the atom:id of the receipt should be resolvable and allow content negotiation to enable a user to reach the HTML splash page, or the RDF, or the ATOM, or the ORE or the…. etc. I don’t see any point in putting all these links in the receipt as we could potentially be providing hundreds of them and still missing one. This missing one could then added but because it wasn’t in the receipt the user doesn’t know it’s there or how to get at it.
Also wouldn’t sword:manifest be better used upon deposit to define the first file the repository should take note of in the package?
The reference given here is probably not the most helpful one.
I think section 7.1 of http://atompub.org/rfc4287.html#IANA is more apposite.
The given reference is relevant to the extent that it indicates that an “IANA Considerations” section in an RFC is an appropriate way to create a new entry in an IANA-maintained registry.
I just realized that the next para addresses the concerns I rased – but I think there’s a potential presentation problem here: it’s possible top read para 2 and not notice the “bring … into line with AtomPub” in the next para. I think the fact that para 2 indicates some problem areas needs to be more clearly indicated.
I believe option 2(ii) to be a violation of he AtomPub spec. It SWORD is to reap the advantages of building upon AtomPub. it must conform to the specified behaviour of AtomPub.
Most of the options under item 4 seem similarly non-conforming to AtomPub.