The Atom Publishing Protocol ([AtomPub]) provides a simple, extensible mechanism for the creation of Web Resources. The SWORD profile builds upon AtomPub and HTTP ([RFC2616]) and incorporates a number of extensions to enable the following kinds of behaviours:
The practical details of the extensions used in the SWORD Profile are provided in the following Internet Drafts:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Throughout this document we will regularly refer to identifiers which are used by SWORD. The following URIs are part of the specification:
All SWORD extensions are defined within the namespace:
Beneath this URI, we use the following extensions for the various parts of the standard:
For all predicates associated with SWORD:
This document uses the prefix sword for this namespace name; for example sword:originalDeposit
Root registry for any SWORD recognised package formats including "default":
Root namespace for any Error documents which SWORD can produce:
Root namespace for any State terms that SWORD wishes to provide:
The AtomPub [AtomPub] namespace is:
This document uses the prefix app for the namespace name; for example app:collection.
The Atom Syndication Format [Atom] namespace is:
This document uses the prefix atom for the namespace name; for example atom:feed
The DCMI Terms [DublinCore] namespace is:
This document uses the prefix dcterms for the namespace name; for example dcterms:title
The RDF [RDF] namespace is:
This document uses the prefix rdf for the namespace name; for example rdf:Description
The OAI-ORE [OAIORE] namespace is:
This document uses the prefix ore for the namespace name; for example ore:aggregates
The default packaging format, which represents a plain ZIP file during resource creation or update, or a ZIP file + Atom embedded DC metadata during Atom Multipart [AtomMultipart] deposit
The packaging format which represents a binary file which should not be unpacked by the server
While specific HTTP status codes are used below, a SWORD client should be prepared to handle any status code as per the HTTP status code definitions [RFC2616]
The client may also supply the On-Behalf-Of header [SWORD001] to provide the username of a target user on whose behalf a deposit will be made. See Section 8: Authentication and Mediated Deposit for more details.
GET SD-URI HTTP/1.1 Authorization: Basic ZGFmZnk6c2VjZXJldA== Host: example.org On-Behalf-Of: [username]
When a server that supports mediated deposit receives an On-Behalf-Of header [SWORD001], the returned Service Document SHOULD identify only those collections to which the combination of mediated user and authenticated user might successfully deposit. If the target server does not support mediated deposit, the returned Service Document SHOULD contain a sword:mediation [SWORD002] extension element with a value of false.
The service document supplied in response MUST meet the following criteria in addition to those specified in [AtomPub]:
Example:
HTTP 1.1 200 OK
Content-Type: text/xml
<?xml version="1.0" ?>
<service xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:sword="http://purl.org/net/sword/terms/"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://www.w3.org/2007/app">
<sword:version>2.0</sword:version>
<sword:maxUploadSize>16777216</sword:maxUploadSize>
<workspace>
<atom:title>Main Site</atom:title>
<collection href="http://swordapp.org/col-uri/43">
<atom:title>Collection 43</atom:title>
<accept>*/*</accept>
<accept alternate="multipart-related">*/*</accept>
<sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
<dcterms:abstract>Collection Description</dcterms:abstract>
<sword:mediation>false</sword:mediation>
<sword:treatment>Treatment description</sword:treatment>
<sword:acceptPackaging>http://purl.org/net/sword/package/default</sword:acceptPackaging>
<sword:acceptPackaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:acceptPackaging>
<sword:service>http://swordapp.org/sd-uri/e4</sword:service>
</collection>
</workspace>
</service>
The following requirements are placed on the client in receipt of a service document:
AtomPub states that Collection Resources MUST provide representations in the form of Atom Feed Documents. Under the SWORD profile, implementations SHOULD provide such representations. Clients MUST NOT require a Collection Feed Document for deposit operation.
The client can create a resource by POSTing the binary content as the body of an HTTP request, with the Content-Type, Content-Disposition, and Packaging headers, with the following requirements:
POST col-uri/43 HTTP/1.1 Host: example.org Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Type: application/zip Content-Length: [content length] Content-MD5: [md5-digest] Content-Disposition: attachment; filename=[filename] Packaging: http://purl.org/net/sword/package/METSDSpaceSIP In-Progress: true On-Behalf-Of: jbloggs Suppress-Metadata: true Slug: [suggested identifier] [request entity]
The requirements placed on the server here are:
Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 11: Deposit Receipt with the HTTP status code 201 (Created) if the server has completed the deposit of the resource or 202 (Accepted) if the server has accepted the resource but still has deposit workflows to run before finally accepting it. The Deposit Receipt MUST be available under the Edit-URI (Member Entry URI), as supplied in the Location header.
For example:
201 Created Location: [Edit-URI] [optional Deposit Receipt]
In order to ensure that all SWORD clients and servers can exchange a full range of file content and metadata, the use of Atom Multipart [AtomMultipart] is permitted to combine a default package with a set of Dublin Core metadata terms [DublinCore] embedded in an Atom Entry.
The client can create a resource by POSTing a multipart mime message to the server with two parts: An Atom Entry containing the metadata for the deposit (known as the Entry Part), and the binary content as the second part (known as the Media Part), with the following requirements:
For example:
POST col-uri/43 HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: multipart/related;
boundary="===============1605871705==";
type="application/atom+xml"
In-Progress: true
On-Behalf-Of: jbloggs
Suppress-Metadata: true
Slug: [suggested identifier]
MIME-Version: 1.0
Media Post
--===============1605871705==
Content-Type: application/atom+xml; charset="utf-8"
Content-Disposition: attachment; name="atom"
MIME-Version: 1.0
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:dcterms="http://purl.org/dc/terms/">
<title>Title</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Contributor</name></author>
<summary type="text">The abstract</summary>
<!-- some embedded metadata -->
<dcterms:abstract>The abstract</dcterms:abstract>
<dcterms:accessRights>Access Rights</dcterms:accessRights>
<dcterms:alternative>Alternative Title</dcterms:alternative>
<dcterms:available>Date Available</dcterms:available>
<dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
<dcterms:contributor>Contributor</dcterms:contributor>
<dcterms:description>Description</dcterms:description>
<dcterms:hasPart>Has Part</dcterms:hasPart>
<dcterms:hasVersion>Has Version</dcterms:hasVersion>
<dcterms:identifier>Identifier</dcterms:identifier>
<dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
<dcterms:publisher>Publisher</dcterms:publisher>
<dcterms:references>References</dcterms:references>
<dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
<dcterms:source>Source</dcterms:source>
<dcterms:title>Title</dcterms:title>
<dcterms:type>Type</dcterms:type>
</entry>
--===============1605871705==
Content-Type: application/zip
Content-Disposition: attachment; name=payload; filename=[filename]
Packaging: http://purl.org/net/sword/package/default
Content-MD5: [md5-digest]
MIME-Version: 1.0
[...binary package data...]
--===============1605871705==--
The requirements placed on the server here are:
Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 11: Deposit Receipt with the HTTP status code 201 (Created) if the server has completed the deposit of the resource or 202 (Accepted) if the server has accepted the resource but still has deposit workflows to run before finally accepting it. The Deposit Receipt MUST be available under the Edit-URI (Member Entry URI), as supplied in the Location header.
For example:
201 Created Location: [Edit-URI] [optional Deposit Receipt]
The Deposit Receipt contains two URIs which can be used to retrieve content from the server: Cont-URI and EM-URI. These are provided in the atom:content@src element and the atom:link@rel="edit-media" elements respectively. Their only functional difference is that the client MUST NOT carry out any HTTP operations other than GET on the Cont-URI, while all operations are permitted on the EM-URI. It is acceptable, but not required, that both URIs to be the same, and in this section we refer only to the EM-URI but in all cases it can be substituted for the Cont-URI.
The Deposit Receipt contains zero or more sword:packaging elements [SWORD002], indicating to the client what package formats can be retrieved from the server. For example:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
[...]
<content type="application/zip" src="http://swordapp.org/cont-uri/43/my_deposit"/>
<link rel="edit-media" href="http://swordapp.org/em-uri/43/my_deposit"/>
<sword:packaging>http://purl.org/net/sword/package/default</sword:packaging>
<sword:packaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:packaging>
<sword:packaging>http://purl.org/net/sword/package/BagIt</sword:packaging>
</entry>
To retrieve the content in the desired packaging format, the client makes an HTTP GET request to the EM-URI and MAY supply an Accept-Packaging header [SWORD001] with the URI from one of the sword:packaging elements.
The server will respond in different ways depending on a number of conditions:
For more details about the packaging process, see Section 7: Packaging
The client can replace the existing content of a resource by performing an HTTP PUT of some new binary content to the EM-URI, with the following requirements:
For example:
POST em-uri/43/my_deposit HTTP/1.1 Host: example.org Content-Type: application/zip Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Length: [content length] Content-MD5: [md5-digest] Content-Disposition: attachment; filename=[filename] Packaging: http://purl.org/net/sword/package/METSDSpaceSIP In-Progress: true On-Behalf-Of: jbloggs Suppress-Metadata: true [request entity]
The requirements placed on the server here are:
Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 11: Deposit Receipt with the HTTP status code 200 (OK) if the server has completed the deposit of the resource or 202 (Accepted) if the server has accepted the resource but still has deposit workflows to run before finally accepting it. The Deposit Receipt MUST be available under the Edit-URI (Member Entry URI), which the server MAY supply in the Location header.
For example:
200 OK Location: [Edit-URI] [optional Deposit Receipt]
The client can remove all the content of a resource without removing the resource itself by issuing an HTTP DELETE request on the EM-URI, with the following requirements:
For example:
DELETE em-uri/43/my_deposit HTTP/1.1 Host: example.org Authorization: Basic ZGFmZnk6c2VjZXJldA== In-Progress: true On-Behalf-Of: jbloggs Suppress-Metadata: true
The requirements placed on the server here are:
Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 11: Deposit Receipt with the HTTP status code 200 (OK) if the server has completed the delete of the content or 202 (Accepted) if the server has accepted the delete request but still has deposit workflows to run before finally accepting it. The Deposit Receipt MUST be available under the Edit-URI (Member Entry URI), which the server MAY supply in the Location header.
For example:
200 OK Location: [Edit-URI] [optional Deposit Receipt]
The client can add further packaged or binary content to a container, adding to existing content rather than overwriting, by issuing an HTTP POST to the Edit-URI, with the following requirements:
POST em-uri/43/my_deposit HTTP/1.1 Host: example.org Content-Type: application/zip Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Length: [content length] Content-MD5: [md5-digest] Content-Disposition: attachment; filename=[filename] Packaging: http://purl.org/net/sword/package/METSDSpaceSIP In-Progress: true On-Behalf-Of: jbloggs Suppress-Metadata: true [request entity]
The requirements placed on the server here are:
Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 11: Deposit Receipt with the HTTP status code 200 (OK) if the server has completed the deposit of the resource or 202 (Accepted) if the server has accepted the resource but still has deposit workflows to run before finally accepting it. The Deposit Receipt MUST be available under the Edit-URI (Member Entry URI), which the server MAY supply in the Location header.
For example:
200 OK Location: [Edit-URI] [optional Deposit Receipt]
The client can update the metadata attached to a resource by issuing an HTTP POST of a new Atom Entry document containing metadata embedded as foreign markup, with the following requirements:
POST /edit-uri/43/my_deposit HTTP/1.1 Host: example.org Content-Type: application/atom+xml;type=entry Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Length: [content length] In-Progress: true On-Behalf-Of: jbloggs Suppress-Metadata: true [entry document]
The requirements placed on the server here are:
Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 11: Deposit Receipt with the HTTP status code 200 (OK) if the server has completed the deposit of the resource or 202 (Accepted) if the server has accepted the resource but still has deposit workflows to run before finally accepting it. The Deposit Receipt MUST be available under the Edit-URI (Member Entry URI), which the server MAY supply in the Location header.
For example:
200 OK Location: [Edit-URI] [optional Deposit Receipt]
The client can add new content and update the metadata attached to a resource by issuing an HTTP POST of an Atom Multipart [AtomMultipart] document, with the following requirements, to the EM-URI:
For example:
POST /em-uri/43/my_deposit HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: multipart/related;
boundary="===============1605871705==";
type="application/atom+xml"
In-Progress: true
On-Behalf-Of: jbloggs
Suppress-Metadata: true
Slug: [suggested identifier]
MIME-Version: 1.0
Media Post
--===============1605871705==
Content-Type: application/atom+xml; charset="utf-8"
Content-Disposition: attachment; name="atom"
MIME-Version: 1.0
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:dcterms="http://purl.org/dc/terms/">
<title>Title</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Contributor</name></author>
<summary type="text">The abstract</summary>
<!-- some embedded metadata -->
<dcterms:abstract>The abstract</dcterms:abstract>
<dcterms:accessRights>Access Rights</dcterms:accessRights>
<dcterms:alternative>Alternative Title</dcterms:alternative>
<dcterms:available>Date Available</dcterms:available>
<dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
<dcterms:contributor>Contributor</dcterms:contributor>
<dcterms:description>Description</dcterms:description>
<dcterms:hasPart>Has Part</dcterms:hasPart>
<dcterms:hasVersion>Has Version</dcterms:hasVersion>
<dcterms:identifier>Identifier</dcterms:identifier>
<dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
<dcterms:publisher>Publisher</dcterms:publisher>
<dcterms:references>References</dcterms:references>
<dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
<dcterms:source>Source</dcterms:source>
<dcterms:title>Title</dcterms:title>
<dcterms:type>Type</dcterms:type>
</entry>
--===============1605871705==
Content-Type: application/zip
Content-Disposition: attachment; name=payload; filename=[filename]
Packaging: http://purl.org/net/sword/package/default
Content-MD5: [md5-digest]
MIME-Version: 1.0
...binary package data...
--===============1605871705==--
The requirements placed on the server here are:
Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 11: Deposit Receipt with the HTTP status code 201 (Created) if the server has completed the deposit of the resource or 202 (Accepted) if the server has accepted the resource but still has deposit workflows to run before finally accepting it. The Deposit Receipt MUST be available under the Edit-URI (Member Entry URI), which the server MAY supply in the Location header.
For example:
201 Created Location: [Edit-URI] [optional Deposit Receipt]
The client can delete the entire object on the server by issuing an HTTP DELETE request on the Edit-URI, with the following requirements:
DELETE /edit-uri/43/my_deposit HTTP/1.1 Host: example.org Authorization: Basic ZGFmZnk6c2VjZXJldA== On-Behalf-Of: jbloggs
The requirements placed on the server here are:
Once the server has processed the request is MUST respond with an HTTP status code 204 (No Content) and leave the response body empty.
The Statement can be found either embedded as foreign markup inside the Deposit Receipt, or can be retrieved by requesting the URI provided in the atom:link@rel="http://purl.org/net/sword/terms/statement" element. The format of the statement is identified by the type attribute of the atom:link@rel="http://purl.org/net/sword/terms/statement" element and MUST be application/rdf+xml for an OAI-ORE Resource Map, or application/atom+xml;type=feed for an Atom Feed.
It MAY also be possible to content negotiate for the statement on the Edit-URI. All negotiable formats MUST also be available as atom:link elements with @rel="http://purl.org/net/sword/terms/statement".
For details on these serialisations see Section 12: SWORD Statement.
AtomPub uses the MIME mechanism to describe the data encoding for resources. This mechanism is inadequate where compound types are involved, such as tar archive files, METS packages, SCORM packages, MPEG21 DIDL packages etc. For example, a server might support certain METS profiles but not others. Other servers might be agnostic towards packaging, but support only certain contents within an archive.
In order to support package deposit and retrieval, SWORD uses the mechanisms described in [SWORD002] to extend AtomPub.
The SWORD Service Document uses the sword:acceptPackaging element from [SWORD002] to indicate that a SWORD collection will accept deposits of a particular packaging format.
Clients should refer to the sword:treatment description in the Service Document to find out the treatment for a particular packaging type.
Packages formats SHOULD be identified by a URI (as per [SWORD002]), but MAY be identified by an arbitrary string.
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<sword:version>2.0</sword:version>
<workspace>
<atom:title>Main Site</atom:title>
<collection href="http://www.swordserver.org/atom/geography-collection" >
<atom:title>My Repository : Geography Collection</atom:title>
<accept>application/zip</accept>
<sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
<dcterms:abstract>Collection description</dcterms:abstract>
<sword:acceptPackaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:acceptPackaging>
<sword:acceptPackaging>http://purl.org/net/sword/package/BagIt</sword:acceptPackaging>
<sword:treatment>Treatment description</sword:treatment>
</collection>
</workspace>
</service>
When creating Media Resources, the client SHOULD indicate the archive file MIME type using the HTTP Content-Type header, and SHOULD also give information about content packaging using the Packaging HTTP header [SWORD001].
The value of the Packaging header SHOULD match one of values the server has advertised as acceptable for the collection in the manner described in Section 7.1..
If a server receives a POST with an unacceptable Packaging header value, it MUST reject the POST by returning an HTTP response with a status code of 415 (Unsupported Media Type), or store the content without further processing (as per [SWORD001]).
POST /col-uri/43 HTTP/1.1 Host: example.org Content-Type: application/zip Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Length: [content length] Content-MD5: [md5-digest] Content-Disposition: filename=myDSpaceMETSItem.zip Packaging: http://purl.org/net/sword/package/METSDSpaceSIP User-Agent: MyJavaClient/0.1 Restlet/2.0
When describing packaged resources in Media Entry documents, servers MUST use the atom:content@type attribute to describe the MIME type of the resource, and MAY add sword:packaging elements to the atom:entry.
If the server does not supply any sword:packaging elements, the client MUST assume that the server only supports the default packaging format.
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
<title>My Deposit</title>
<id>info:something:1</id>
<updated>2008-08-18T14:27:08Z</updated>
<author><name>jbloggs</name></author>
<summary type="text">A summary</summary
<generator uri="http://www.swordserver.org/engine" version="1.0"/>
<content type="application/zip" src="http://swordapp.org/col-uri/43/my_deposit/package.zip"/>
<sword:packaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:packaging>
<sword:packaging>http://purl.org/net/sword/package/BagIt</sword:packaging>
<link rel="edit" href="http://swordapp.org/col-uri/43/my_deposit.atom" />
</entry>
Clients and servers SHOULD use URIs to communicate about package types, and MAY use URIs registered under the SWORD namespace (such as the default package). To register a new URI in the SWORD namespace, please contact the SWORD team at the contact details at the bottom of this document. Registration of package URIs under the SWORD namespace is strictly OPTIONAL.
In [AtomPub] Section 14, implementations MUST support HTTP Basic Authentication in conjunction with a TLS connection. The SWORD Profile relaxes this requirement: SWORD client and server implementations SHOULD be capable of being configured to use HTTP Basic Authentication [RFC2617] in conjunction with a TLS connection as specified by [RFC2818].
In a number of situations the authenticated user using a SWORD client is not the owner of the deposited resource. SWORD provides a way of representing this usage by allowing clients to set a HTTP header field On-Behalf-Of which, if present SHOULD contain a user principle for the owner of the resource. It is also possible to use this SWORD mediation mechanism for situations such as non-interactive batch deposit in which the authenticated user is a software acting on behalf of a user.
The mediation technique described by SWORD is not intrinsically secure - it is assumed that trust between the owning user and the mediating user will be established by extending SWORD, or outside the scope of a resource creation, using a mechanism such as that described by [OAUTH].
SWORD servers SHOULD indicate whether they support mediated deposit by including a sword:mediation element containing a text element of either true or false in app:collection elements in Service Documents.
Clients SHOULD use the On-Behalf-Of header when retrieving Service Documents if they intend to use the feature for resource creation. Servers MAY use this header information along with authentication and any other information in constructing the Service Document representation returned. For example, the server might include only collections to which the On-Behalf-Of can deposit.
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<sword:version>2.0</sword:version>
<workspace>
<atom:title>Main Site</atom:title>
<collection href="http://swordapp.org/col-uri/43" >
<atom:title>Collection 43</atom:title>
<accept>application/xml</accept>
<accept>application/zip</accept>
<accept>application/atom+xml</accept>
<sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
<dcterms:abstract>Collection description</dcterms:abstract>
<sword:mediation>true</sword:mediation>
<sword:treatment>treatment description</sword:treatment>
<sword:packaging>http://purl.org/net/sword/package/BagIt</sword:packaging>
</collection>
</workspace>
</service>
In all cases (mediated or not) where a user has authenticated to make a deposit, servers SHOULD preserve the user's identity in the sword:depositedBy property of the SWORD Statement. In mediated deposit, the value given in the On-Behalf-Of header SHOULD be used for the value of the sword:depositedOnBehalfOf property of the SWORD Statement. See Section 12: SWORD Statement for details of the serialisation.
The Atom Publishing Protocol [AtomPub] has good default support for metadata and the packaging formats that are used to exchange data between scholarly systems often support rich metadata formats. Therefore, handling metadata well is an important aspect to SWORD.
Requests that come into a SWORD server MAY contain a Suppress-Metadata HTTP header [SWORD001] which MUST contain one of the values true or false. If no header is provided the server MUST assume a value of false for the purposes of any internal processing. The following two sections describe how the server should behave under the different conditions.
If Suppress-Metadata is false, then the server SHOULD consider the metadata supplied in the deposit for inclusion in its metadata record for the object being deposited. There are several conditions in which the server may find itself needing to look at the incoming metadata as a source for its records:
If Suppress-Metadata is true, then the server SHOULD consider that any metadata supplied in the deposit be ignored or at least not used in any way to overwrite existing metadata. There are several conditions in which the server may find itself needing to suppress metadata hanlding:
As scholarly systems may wish to give the client more control over the publishing process, SWORD uses the In-Progress HTTP header [SWORD001] to allow the client to indicate that a deposit should not yet be injected into any post-submission or pre-publication workflow. The In-Progress header MUST take the value true or false, and if it is not present the server MUST assume that it is false and behave as described below.
If In-Progress is false, the server MUST assume that it can carry on processing the deposit or deletion as it sees fit.
If In-Progress is true, the server SHOULD expect the client to provide further updates to the item some undetermined time in the future. Details of how this is implemented is dependent on the server's purpose. For example, a repository system may hold items which are marked In-Progress in a workspace until such time as a client request indicates that the deposit is complete.
On successfully accepting a POST (deposit), implementers SHOULD return an Atom Entry Document with the HTTP response. The Atom Entry Document is known in SWORD as the Deposit Receipt must conform to the following conditions:
For example:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
<title>My Deposit</title>
<id>info:something:1</id>
<updated>2008-08-18T14:27:08Z</updated>
<summary type="text">A summary</summary>
<generator uri="http://www.myrepository.ac.uk/sword-plugin" version="1.0"/>
<!-- the item's metadata -->
<dcterms:abstract>The abstract</dcterms:abstract>
<dcterms:accessRights>Access Rights</dcterms:accessRights>
<dcterms:alternative>Alternative Title</dcterms:alternative>
<dcterms:available>Date Available</dcterms:available>
<dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
<dcterms:contributor>Contributor</dcterms:contributor>
<dcterms:description>Description</dcterms:description>
<dcterms:hasPart>Has Part</dcterms:hasPart>
<dcterms:hasVersion>Has Version</dcterms:hasVersion>
<dcterms:identifier>Identifier</dcterms:identifier>
<dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
<dcterms:publisher>Publisher</dcterms:publisher>
<dcterms:references>References</dcterms:references>
<dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
<dcterms:source>Source</dcterms:source>
<dcterms:title>Title</dcterms:title>
<dcterms:type>Type</dcterms:type>
<sword:verboseDescription>Verbose description</sword:verboseDescription>
<sword:treatment>Unpacked. JPEG contents converted to JPEG2000.</sword:treatment>
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/>
<content type="application/zip" src="http://www.swordserver.ac.uk/col1/mydeposit"/>
<link rel="edit-media" href="http://www.swordserver.ac.uk/col1/mydeposit"/>
<link rel="edit" href="http://www.swordserver.ac.uk/col1/mydeposit.atom" />
<sword:packaging>http://purl.org/net/sword/package/BagIt</sword:packaging>
<link rel="http://purl.org/net/sword/terms/statement"
type="application/atom+xml;type=feed"
href="http://www.swordserver.ac.uk/col1/mydeposit.feed"/>
<link rel="http://purl.org/net/sword/terms/statement"
type="application/rdf+xml"
href="http://www.swordserver.ac.uk/col1/mydeposit.rdf"/>
<rdf:RDF>
<!-- OAI-ORE serialisation of Statement here -->
</rdf:RDF>
</entry>
The Statement is a document or region of the Deposit Receipt which describes two features of the object as it appears on the server:
All predicates used by the statement in any of its serialisations are defined here, and all exist under the sword namespace:
URI: http://purl.org/net/sword/terms/originalDeposit
This is used to indicate the URI of a resource on the server which was an original deposit package. This allows the client to easily identify any packages which form the basis of the original deposit among other parts of the object which may be derived from the original.
In XML this may be serialised as:
In RDF/XML this can be serialised as as:
URI: http://purl.org/net/sword/terms/state
This is used to supply the URI representing the state of an item on the server. This can be any URI, and is not constrained to any ontology. This can be used in combination with sword:stateDescription to provide more details to the client.
In XML this may be serialised as:
In RDF/XML this can be serialised as:
URI: http://purl.org/net/sword/terms/packaging
This is used to identify the packaging format of a resource. Particularly, if used in conjunction with sword:originalDeposit, this can be used to indicate the package format that an original deposit package used.
In XML this may be serialised as:
<sword:originalDeposit href="http://location/of/deposit">
<sword:packaging>http://sword/packaging/</sword:packaging>
</sword:originalDeposit>
In RDF/XML this can be serialised as:
<sword:originalDepsit rdf:resource="http://location/of/deposit"/>
<rdf:Description rdf:about="http://location/of/deposit">
<sword:packaging rdf:resource="http://sword/packaging/"/>
</rdf:Description>
URI: http://purl.org/net/sword/terms/depositedOn
This is used to provide a user who was responsible for depositing an original sword package. The use credentials may just be the username of the depositor, but the server is free to add further details where necessary.
In XML this may be serialised as:
<sword:originalDeposit href="http://location/of/deposit">
<sword:depositedOn>2011-01-01T00:00:00Z</sword:depositedOn>
</sword:originalDeposit>
In RDF/XML this may be serialised as
<sword:originalDepsit rdf:resource="http://location/of/deposit"/>
<rdf:Description rdf:about="http://location/of/deposit">
<sword:depositedOn rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2011-01-01T00:00:00Z</sword:depositedOn>
</rdf:Description>
URI: http://purl.org/net/sword/terms/depositedBy
This is used to provide a user who was responsible for depositing an original sword package. The use credentials may just be the username of the depositor, but the server is free to add further details where necessary.
In XML this may be serialised as:
<sword:originalDeposit href="http://location/of/deposit">
<sword:depositedBy>jbloggs</sword:depositedBy>
</sword:originalDeposit>
In RDF/XML this may be serialised as
<sword:originalDepsit rdf:resource="http://location/of/deposit"/> <rdf:Description rdf:about="http://location/of/deposit"> <sword:depositedBy>jbloggs</sword:depositedBy> </rdf:Description>
URI: http://purl.org/net/sword/terms/depositedOnBehalfOf
This is used to provide the user for whom the original sword package was deposited on behalf of. The use credentials may just be the username of the depositor, but the server is free to add further details where necessary.
In XML this may be serialised as:
<sword:originalDeposit href="http://location/of/deposit">
<sword:depositedOnBehalfOf>jbloggs</sword:depositedOnBehalfOf>
</sword:originalDeposit>
In RDF/XML this may be serialised as
<sword:originalDepsit rdf:resource="http://location/of/deposit"/>
<rdf:Description rdf:about="http://location/of/deposit">
<sword:depositedOnBehalfOf>jbloggs</sword:depositedOnBehalfOf>
</rdf:Description>
URI: http://purl.org/net/sword/terms/stateDescription
This is used to provide a human readable description of the state that the item is in on the server. This is used in conjunction with the sword:state to provide additional details for the client to use in its interface with the end user.
In XML this may be serialised as:
<sword:state href="http://sword/state"> <sword:stateDescription>The item has passed through the workflow and is now archived</sword:stateDescription> </sword:state>
In RDF/XML this may be serialised as
<sword:state rdf:resource="http://sword/state"/> <rdf:Description rdf:about="http://sword/state"> <sword:stateDescription>The item has passed through the workflow and is now archived</sword:stateDescription> </rdf:Description>
The SWORD statement can be provided as an OAI-ORE Resource [OAIORE] Map with sword extensions. For an RDF document to comply with the requirements of the SWORD statement it needs to meet the following requirements but is not constrained in any way as to what additional data is provided alongside. As such, it is expected that the SWORD statement may be included with existing RDF serialisations of objects provided by the server.
The responsibilities of the server are:
For example:
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:ore="http://www.openarchives.org/ore/terms/">
<rdf:Description rdf:about="http://localhost:8080/edit-uri/43/my_deposit">
<ore:describes rdf:resource="http://localhost:8080/agg-uri/43/my_deposit"/>
</rdf:Description>
<rdf:Description rdf:about="http://localhost:8080/agg-uri/43/my_deposit">
<ore:isDescribedBy rdf:resource="http://localhost:8080/edit-uri/43/my_deposit"/>
<ore:aggregates rdf:resource="http://localhost:8080/part-uri/43/my_deposit/example.zip"/>
<sword:originalDeposit rdf:resource="http://localhost:8080/part-uri/43/my_deposit/example.zip"/>
<sword:state rdf:resource="http://purl.org/net/sword/state/archived"/>
</rdf:Description>
<rdf:Description rdf:about="http://localhost:8080/part-uri/43/my_deposit/example.zip">
<sword:packaging rdf:resource="http://purl.org/net/sword/package/default"/>
<sword:depositedOn rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
2011-02-25T14:40:09Z
</sword:depositedOn>
<sword:depositedBy rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
sword
</sword:depositedBy>
</rdf:Description>
<rdf:Description rdf:about="http://purl.org/net/sword/state/archived">
<sword:stateDescription>
The work has passed through review and is now in the archive
</sword:stateDescription>
</rdf:Description>
</rdf:RDF>
The client's responsibilities are:
The SWORD statement can be provided as an Atom Feed [Atom] with sword extensions. For an Atom Feed document to comply with the requirements of the SWORD statement it needs to meet the following requirements but is not constrained in any way as to what additional data is provided alongside. As such, it is expected that the SWORD statement may be included with existing serialisations provided by the server, such as with any GData [GData] extensions.
The responsibilities of the server are:
For example:
<atom:feed xmlns:sword="http://purl.org/net/sword/terms/"
xmlns:atom="http://www.w3.org/2005/Atom">
<sword:state href="http://purl.org/net/sword/state/archived">
<sword:stateDescription>
The work has passed through review and is now in the archive
</sword:stateDescription>
</sword:state>
<atom:entry>
<atom:category scheme="http://purl.org/net/sword/terms/"
term="http://purl.org/net/sword/terms/originalDeposit"
label="Orignal Deposit"/>
<atom:content type="application/zip"
src="http://localhost:8080/part-uri/43/my_deposit/example.zip"/>
<sword:packaging>http://purl.org/net/sword/package/default</sword:packaging>
<sword:depositedOn>2011-03-02T20:50:06Z</sword:depositedOn>
<sword:depositedBy>sword</sword:depositedBy>
<sword:depositedOnBehalfOf>jbloggs</sword:depositedBy>
</atom:entry>
</atom:feed>
The client's responsibilities are:
SWORD adds a new class of document to [AtomPub] that gives server implementations the ability to describe error conditions more fully than HTTP response codes allow, as per [SWORD003]. If a server is reporting an error condition in response to a resource POST, it SHOULD also return a document with a root element of sword:error. The sword:error element SHOULD have an href attribute containing a URI that identifies the error. Errors in the SWORD namespace are reserved and legal values are enumerated below. Implementations MAY define their own errors, but MUST use a different namespace to do so.
The sword:error element MAY contain any of the elements normally used in Entry Documents, but all fields are OPTIONAL
URI: http://purl.org/net/sword/error/ErrorContent
The supplied format is not the same as that identified in the Packaging header and/or that supported by the server
URI: http://purl.org/net/sword/error/ErrorChecksumMismatch
Checksum sent does not match the calculated checksum. The server MUST also return a status code of 412 Precondition Failed
URI: http://purl.org/net/sword/error/ErrorBadRequest
Some parameters sent with the POST were not understood. The server MUST also return a status code of 400 Bad Request.
URI: http://purl.org/net/sword/error/TargetOwnerUnknown
Used in mediated deposit when the server does not know the identity of the On-Behalf-Of user.
URI: http://purl.org/net/sword/error/MediationNotAllowed
Used where a client has attempted a mediated deposit, but this is not supported by the server. The server MUST also return a status code of 412 Precondition Failed.
URI: http://purl.org/net/sword/error/MethodNotAllowed
Used when the client has attempted one of the HTTP update verbs (POST, PUT, DELETE) but the server has decided not to respond to such requests on the specified resource at that time. The server MUST also return a status code of 405 Method Not Allowed
HTTP 1.1 400 Bad Request
<?xml version="1.0" encoding="utf-8"?>
<sword:error xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/"
xmlns:arxiv="http://arxiv.org/schemas/atom"
href="http://example.org/errors/BadManifest">
<author>
<name>Example repository</name>
</author>
<title>ERROR</title>
<updated>2008-02-19T09:34:27Z</updated>
<generator uri="https://example.org/sword-app/"
version="0.9">sword@example.org</generator>
<summary>The manifest could be parsed, but was not valid -
no technical metadata was provided.</summary>
<sword:treatment>processing failed</sword:treatment>
<link rel="alternate" href="https://arxiv.org/help" type="text/html"/>
</sword:error>
AtomPub makes no recommendations on the discovery of Service Documents. SWORD RECOMMENDS that server implementations use:
<html:link rel="sword" href="[Service Document URL]"/>
in the head of a relevant HTML document to assist with service discovery.
[Atom] Nottingham, M. and R. Sayre, "The Atom Syndication Format", RFC 4287, December 2005. http://www.ietf.org/rfc/rfc4287.txt
[AtomMultipart] Gregario, J, et al "AtomPub Multipart Media Resource Creation", September 2008. http://tools.ietf.org/html/draft-gregorio-atompub-multipart-04
[AtomPub] Gregario, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, October 2007. http://www.ietf.org/rfc/rfc5023.txt (see also non-normative html version at http://bitworking.org/projects/atom/rfc5023.html)
[DublinCore] DCMI Metadata Terms. http://www.dublincore.org/documents/dcmi-terms/
[GData] Google Documents List API. http://code.google.com/apis/documents/docs/developers_guide.html
[OAUTH] Atwood, A., Conlan, R. et al OAuth Core 1.0 http://oauth.net/core/1.0/, December 2007
[OAIORE] Lagoze, C., Van de Sompel, H et al, Open Archives Initiative Object Reuse and Exchange, http://www.openarchives.org/ore/, June 2008
[RDF] Resource Description Framework. http://www.w3.org/RDF/
[RFC2119] Bradner, S. "Key words for use in RFCs to Indicate Requirement Levels". http://www.ietf.org/rfc/rfc2119.txt, March 1997.
[RFC2183] Troost, R., Dorner, S. and Moore, K., "Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field", RFC 2183, August 1997 http://www.ietf.org/rfc/rfc2183.txt
[RFC2616] Fielding et al, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999 http://www.w3.org/Protocols/rfc2616/rfc2616.html
[RFC2617] Franks, J. et al, "HTTP Authentication: Basic and Digest Access Authentication". http://www.ietf.org/rfc/rfc2617.txt, June 1999
[RFC2818] Rescorla, E. "HTTP over TLS". http://www.ietf.org/rfc/rfc2818.txt, May 2000.
[SWORD001] Jones, R. "Packaged Content Delivery over HTTP", February 2011
[SWORD002] Jones, R. "AtomPub Extensions for Packaged Content", February 2011
[SWORD003] Jones, R. "AtomPub Extensions for Scholarly Systems", February 2011
[SWORD004] Jones, R. "Atom Multipart Extensions for Packaged Content", February 2011
Author: Richard Jones
Document Reviewers:
Julie Allinson
Tim Brody
David Flanders
Stuart Lewis
Graham Klyne
Alister Miles
Ben O'Steen
Rob Sanderson
Nick Sheppard
Ian Stuart
Ed Summers
David Tarrant
Graham Triggs
Scott Wilson