SWORD AtomPub Profile version 1.3

Simple Webservice Offering Repository Deposit

Change control

Version 1.3, published XXXX
Revised deviations from [AtomPub] and [Atom], increasing requirement for persistent Atom Entry Documents. Changed references to APP to refer to AtomPub. Restructured document to include description of SWORD specific extensions before comparison with AtomPub. Removed notion of levels of compliance. Removed section on Slug headers; it didn't add anything over Atom. Added sword:userAgent, sword:error, sword:service, sword:version and sword:maxUploadSize elements. The formatNamespace mechanism was renamed for clarity to sword:acceptPackaging (in Service Documents), sword:packaging (in Atom Entry Documents) and X-Packaging (in POST request-headers), and the values that can be taken are better defined. Quality Value mechanism added to sword:acceptPackaging.
Version 1.2, created 22nd January 2008, revised 22 February 2008.
Changes from Version 1.1: corrections to namespaces used in examples.

Editors:

Introduction

The Atom Publishing Protocol ([AtomPub]) provides a simple, extensible mechanism for the creation of Web Resources. The SWORD profile builds upon AtomPub, providing a set of extensions and constraint relaxations and enforcements of use when: -

Whilst it is possible to implement generic SWORD compliant clients and servers, the SWORD profile aims to provide a framework around which specific deposit systems can be built consistently and efficiently.

The SWORD profile relaxes a number of constraints of AtomPub, and adds a number of elements. It avoids overloading the elements of or changing the semantics of AtomPub. Consequently, SWORD compliance does not preclude AtomPub compliance; implementers wishing to support additional elements of AtomPub, such as update (PUT), DELETE, categories or POSTing [Atom] documents are free to do so. The section on Compliance explains the differences between AtomPub and SWORD in more detail.

Document conventions

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

Document Structure

The first part of this document describes the mechanisms that the SWORD profile adds to AtomPub. The second part follows the structure and numbering of the AtomPub specification, highlighting the ways in which the SWORD profile diverges from AtomPub.

SWORD Namespace

All SWORD extensions are defined within the namespace:

http://purl.org/net/sword/

This specification uses the prefix "sword:" for the namespace name. The prefix "app:" is used for "http://www.w3.org/2007/app" (the namespace name of the Atom Publishing Protocol [AtomPub]), and the prefix "atom:" is used for "http://www.w3.org/2005/Atom" (the namespace name of the Atom Syndication Format [Atom]). These namespace prefixes are not semantically significant.

Part A: SWORD features

1 Package support

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.

1.1 Package support in Service description

To this end, SWORD extends AtomPub, adding the sword:acceptPackaging element, which is used in a similar fashion to app:accept elements inside a app:collection element within a Service Document to indicate that a SWORD collection will accept deposits of a particular packaging format. The value SHOULD be a URI taken from the enumeration in SWORD Content Package Types [SWORD-TYPES].

Servers MAY also use a q attribute with a Quality Value (See [HTTP1.1] section 3.9) on the sword:acceptPackaging element in order to communicate that it has a preference between packaging formats. As described in [HTTP1.1], the q attribute MUST have a short floating-point numeric value between 0 and 1, where 0 indicates that the server will not handle the format (equivalent to omitting that sword:acceptPackaging element completely) and 1 indicates the strongest preference. If the q attribute is not given, clients MUST assume a default value of 1. Values of the q attribute MUST NOT have more than 3 digits after the decimal point. Note that q attribute values only have relative meaning within an app:collection element, and absolute values do not imply any particular support or treatment. Clients should refer to the sword:treatment description in the service document, or perform a No-Op deposit (see Part A Section 3.1) to find out the treatment for a particular packaging type.

<?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>1.3</sword:version>
 <workspace>

   <atom:title>Main Site</atom:title>
   <collection
       href="http://www.myrepository.ac.uk/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 q="1.0">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging>
     <sword:acceptPackaging q="0.8">http://purl.org/net/sword-types/bagit</sword:acceptPackaging>
   </collection>

 </workspace>
</service>

1.2 Package support during resource creation

When creating Media Resources (see Part B section 9), 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 X-Packaging HTTP header. This can take values from the list enumerated in [SWORD-TYPES] and SHOULD match one of values the server has advertised as acceptable for the collection in the manner described above.

If a server receives a POST with an unacceptable X-Packaging value, it SHOULD reject the POST by returning an HTTP with a status code of 415 (Unsupported Media Type).

1.3 Package description in entry documents

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

1.4 Example

  POST /geography-collection HTTP/1.1
  Host: www.myrepository.ac.uk
  Content-Type: application/zip
  Authorization: Basic ZGFmZnk6c2VjZXJldA==
  Content-Length: nnn
  Content-MD5: [md5-digest]
  Content-Disposition: filename=myDSpaceMETSItem.zip
  X-Packaging: http://purl.org/net/sword-types/mets/dspace
  User-Agent: MyJavaClient/0.1 Restlet/2.0
  HTTP/1.1 201 Created
  Date: Mon, 18 August 2008 14:27:11 GMT
  Content-Length: nnn
  Content-Type: application/atom+xml; charset="utf-8"
  Location: http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom

  <?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>
     <sword:userAgent>MyJavaClient/0.1 Restlet/2.0</sword:userAgent>
     <generator uri="http://www.myrepository.ac.uk/engine" version="1.0"/>

     <content type="application/zip"
        src="http://www.myrepository.ac.uk/geography-collection/deposit1.zip"/>	
     <sword:packaging>http://purl.org/net/sword-types/mets/dspace</sword:packaging>
     <link rel="edit"
        href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" />
  </entry>

2 Mediated Deposit

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 X-On-Behalf-Of which, if present SHOULD contain a user principle for the owner of the resource. It is also possible to use the 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].

2.1 Mediation In Service Description

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 (see Part B, section 8).

Clients SHOULD use the X-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 X-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:level>1</sword:level>
 <sword:verbose>true</sword:verbose>
 <sword:noOp>true</sword:noOp>  
 <workspace>

   <atom:title>Main Site</atom:title>
   <collection
       href="http://www.myrepository.ac.uk/atom/geography-collection" >
     <atom:title>My Repository : Geography Collection</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-types/bagit</sword:packaging>
   </collection>

 </workspace>
</service>

2.2 Metadata Interactions In Mediated Deposit

In all cases (mediated or not) where a user has authenticated to make a deposit, servers SHOULD use the user's identity for the value of the atom:author element of the Media Entry Document. In mediated deposit, the value given in the X-On-Behalf-Of header SHOULD be used for the value of the atom:contributor element.

2.3 Example

In this example, user 'jbloggs' is making a deposit on behalf of user 'fdibner'.

  
POST /app/geography-collection HTTP/1.1
Host: www.myrepository.ac.uk
Content-Type: application/zip
User-Agent: RepoGateway/1.2
Authorization: Basic [digested auth information for 'jbloggs']
Content-Length: nnn
X-On-Behalf-Of: fdibner   
[zipped data]
  
HTTP/1.1 201 Created
Date: Mon, 18 August 2008 14:27:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset="utf-8"
Location: http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom
<?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>
   <contributor><name>fdibner</name></contributor>

   <summary type="text">A summary</summary>
   <!-- In this case, the package has been placed on the workbench of the On-Behalf-Of user -->
   <content type="text/html"
        src="http://www.myrepository.ac.uk/fdibner/workbench/my_deposit"/>
   <link rel="edit-media"
        href="http://www.myrepository.ac.uk/geography/my_deposit.zip"/>
   <link rel="edit"
        href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" />
   
   <sword:userAgent>RepoGateway/1.2</sword:userAgent>
   <generator uri="http://www.myrepository.ac.uk/engine" version="1.0"/>
   <sword:treatment>Treatment description</sword:treatment>
</entry>

3 Developer Features

One of the aims of SWORD is to lower the cost of implementing and configuring clients and servers against each other. To this end, SWORD includes some recommended extensions to ease development.

3.1 No-Op (Dry Run)

This extension allows clients to test a server's implementation without actually creating a resource, by including X-No-Op HTTP header with a value of 'true' in a deposit POST. Servers MUST recognise this header and either handle the POST as a simulated deposit without creating a resource, or else return a status code of 400 Bad Request to indicate that they do not support this extension. When a server judges that the dry run would have proceeded successfully, it SHOULD return a status code of 200 Successful and include the Atom Entry Document it would have created in the response. The response SHOULD NOT include a Location header. Servers MAY indicate whether they support this feature by including a sword:noOp element with a value of 'true' or 'false' in Service Document representations.

3.2 Verbose Output

Servers can also support developers by providing detailed logging output on actions taken, flow control conditions etc. Clients MAY request such detailed output by sending an HTTP header X-Verbose with a value of 'true' with a deposit POST. Servers MAY advertise whether they support such detailed output by including a sword:verbose element containing a text node with value 'true' or 'false'. If a server has advertised support for verbose output and a client requests it using the X-Verbose header, the server SHOULD add a sword:verboseDescription element in Atom Entry document representations for the deposit.

3.3 Client and server identity

In order to assist in resolving interoperability problems between softwares, SWORD provides a mechanism for servers to record both server software identity and client software identity in Atom Entry Documents. SWORD RECOMMENDS that clients identify themselves using a User-Agent request-header, and that servers record this information in Atom Entry Documents using the sword:userAgent element. Servers SHOULD identify their software in an atom:generator element.

3.4 Development Features Example

POST /app/geography-collection HTTP/1.1
Host: www.myrepository.ac.uk
Content-Type: application/zip
User-Agent: RepoGateway/1.1 PythonLibHttp2/2.5
Authorization: Basic [digested auth information for 'jbloggs']
Content-Length: nnn
X-No-Op: true
X-Verbose: true
[zipped data]
HTTP/1.1 200 Created
Date: Mon, 18 August 2008 14:27:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset="utf-8"
<?xml version="1.0"?>
 <entry xmlns="http://www.w3.org/2005/Atom"
	 xmlns:sword="http://purl.org/net/sword/">
   <sword:noOp>true</sword:noOp>
   <sword:verboseDescription>
   Does collection exist? True.
   User authenticates? True.
   User: jbloggs
   User has rights to collection? True. 
   </sword:verboseDescription>
   <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>
   <content type="text/html"
        src="http://www.myrepository.ac.uk/fdibner/workbench/dummy_deposit"/>
   <link rel="edit-media"
        href="http://www.myrepository.ac.uk/geography/dummy_deposit.zip"/>
   <link rel="edit"
        href="http://www.myrepository.ac.uk/geography-collection/atom/dummy_deposit.atom" />
	
   <sword:userAgent>RepoGateway/1.1 PythonLibHttp2/2.5</sword:userAgent>
   <generator uri="http://www.myrepository.ac.uk/sword-plugin" version="1.0"/>
   <sword:treatment>Unpacked. JPEG contents converted to JPEG2000.</sword:treatment>
</entry>

4 Auto-discovery

AtomPub makes no recommendations on the discovery of Service Documents. SWORD RECOMMENDS that server implementations use an <html:link rel="sword" href="[Service Document URL]"/> element in the head of a relevant HTML document to assist with service discovery.

5 Error documents

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. If a server is reporting an error condition in response to a resource POST (see Part B Section 9), 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.

Error URI Usage notes
http://purl.org/net/sword/error/ErrorContent The supplied format is not the same as that identified in the X-Packaging header and/or that supported by the server
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.
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.
http://purl.org/net/sword/error/TargetOwnerUnknown Used in mediated deposit (see Part A Section 2) when the server does not know the identity of the X-On-Behalf-Of user.
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.

The sword:error element MAY contain any of the elements normally used in Entry Documents (See Part B Section 9.8), but does not to the meet the requirements of Entry Documents (e.g. an atom:id element is not required).

5.1 Error Document Example

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>

6 Nested Service Description

The number of collections in a server system is often so large that standard AtomPub Service Documents become problematically large. To alleviate this problem, SWORD adds a sword:service element as a child of app:collection AtomPub Service Documents, allowing servers to nest SWORD service definitions. Depending on the server implementation, this might indicate hierarchy in the structure of the collections. Information does not commute between nested services; servers MUST provide full information about each collection in every service document that describes it. There is no mechanism for data to be inherited by nested services.

6.1 Example

<?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>1.3</sword:version>
 <workspace>

   <atom:title>Main Site</atom:title>
   <collection
       href="http://www.myrepository.ac.uk/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 q="0.8">http://purl.org/net/sword-types/bagit</sword:acceptPackaging>
     <sword:service>http://www.myrepository.ac.uk/atom/geography-collection/service.atomsvc</sword:service>
   </collection>

 </workspace>
</service>

Part B: SWORD Profile of AtomPub

This section is organised according to the sections of the [AtomPub] document, highlighting where SWORD varies from AtomPub. If an AtomPub section or feature is omitted, implementations MUST behave as defined in AtomPub.

5. Protocol Operations

5.1 Retrieving a Service Document

GET to Service Document

In addition, SWORD defines an additional HTTP header X-On-Behalf-Of used to specify the username of a target user on whose behalf a deposit is being made.

GET to Service Document
X-On-Behalf-Of: [on-behalf-of-user]

This facilitates the SWORD requirement to support mediated deposits. See also the notes about Authentication below in Part B Section 14 (relating to AtomPub section 14). When a server that supports mediated deposit receives an X-On-Behalf-Of header, 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 extension element with a value of false.

5.2 Listing Collections

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.

5.3 Creating a Resource

SWORD supports the use of HTTP POST.

POST [URI of Collection] 
[Request entity]
201 Created 
Location: [Member Entry URI]
[Optional Atom Entry document]

See further refinements to the SWORD use of HTTP POST in Part B Section 9.

5.4 Editing a Resource

The SWORD profile does not require support for the AtomPub mechanisms for modification of resources once created, but does not prohibit it - see Part B Section 9.3.

5.5 Use of HTTP Response Codes

SWORD builds on the use of response codes specified in [AtomPub], by mandating the use of certain codes as described in the list below. As per HTTP, it is RECOMMENDED that a human-readable explanation is supplied along with any HTTP response code.

See Part A Section 5 for a description of how Error Documents can be used to provide more information about errors.

7. Category Documents

The SWORD profile does not require server support for Category Documents, and clients MUST NOT require them for deposit operation.

8. Service Documents

SWORD requires support for Service Documents as described in [AtomPub] section 8, and defines several new elements that extend the Service Document to allow servers to indicate their support for the various SWORD extensions. Some of these extensions apply to the service as a whole and are used as children of the app:service element, others relate to individual collections and are used as children of the app:collection element. The following elements apply to the service as a whole and are used as children of the app:service element: -

Element Allowed Values Usage
sword:version text SHOULD be included. Indicates the version of the specification against which the server was implemented. Whilst this profile aims to be back-compatible, this information may be useful for assessing compliance issues. For this spec the element should be 1.3.
sword:verbose 'true'|'false' MAY be included. Indicates whether the server supports the verbose developer feature as described in Part A Section 3.2
sword:noOp 'true'|'false' MAY be included. Indicates whether the server supports the No Op developer feature as described in Part A Section 3.1
sword:maxUploadSize integer MAY be included to indicate the maximum size (in kB) of package that can be uploaded to the SWORD service.

8.1 Workspaces

As in [AtomPub], in SWORD Workspaces are simply named groups of Collections.

For the SWORD profile, one or more app:collection elements SHOULD be present in an app:workspace element, unless the authenticated user does not have permission to deposit.

Within app:collection, the app:accept element MUST be used to specify accepted media-ranges. In many cases, such as when content is packaged in archive files, the MIME type does not adequately describe the content. In these cases, implementations SHOULD provide one or more sword:acceptPackaging elements to specify the packaging format within the archive file. The value for this element SHOULD be taken from the enumeration in SWORD Content Package Types [SWORD-TYPES].

SWORD defines the following extensions to the app:collection element:

Element Allowed Values Usage
sword:collectionPolicy text MAY be included. Used for a human-readable description of collection policy. Include either a text description or a URI.
sword:mediation 'true'|'false' SHOULD be included. Used to indicate if mediated deposit is allowed on the defined collection.
sword:treatment text MAY be included. Used for a human-readable statement about what treatment the deposited resource will receive.
sword:acceptPackaging q="[qvalue]" URI MAY be included. Used to identify the content packaging types supported by this collection. SHOULD be a URI from [SWORD-TYPES]. The q attribute MAY be used to indicate relative preferences between packaging formats (See Part A Section 1.1).
sword:service URI 0 or more MAY be included to direct clients to nested service definitions. If present, the value MUST be a URI that dereferences to another SWORD Service Document.

The use of a Dublin Core dcterms:abstract element containing a description of the Collection is RECOMMENDED.

9. Creating and Editing Resources

9.2 Creating resources with POST

SWORD uses HTTP headers to modify the behaviour of the creation of Media Resources using an HTTP POST request as defined in section 9.6 of the [AtomPub]. Clients use the following headers:

Header Allowed Values Usage
Content-MD5 MD5 Checksum of the contents Clients SHOULD use this header as defined in [HTTP1.1] section 14.15. Servers SHOULD check it against the request entity if present.
User-Agent Text Clients SHOULD include a User-Agent description header as specified in [HTTP1.1] section 14.43.
Content-Disposition:filename Text Clients MAY use the filename parameter with the Content-Disposition header as defined in [RFC2183] section 2.3 to provide a suggested filename for the POSTed entity. Server implementations MUST adopt the behaviour and requirements in [RFC2183].
X-On-Behalf-Of Text Clients MAY use the X-On-Behalf-Of as described in Part A Section 2. If the server does not support mediation, it SHOULD return a status code 400 Bad Request, with a human-readable explanation.
X-Verbose 'true'|'false' Clients MAY use this header to request verbose progress information on a deposition. If present, servers SHOULD respond by including a sword:verboseDescription element in the Atom Entry Document generated as a result of the POST. See Part A Section 3.2.
X-No-Op 'true'|'false' Clients MAY use this header as described in Part A Section 3.1. If present with a value of 'true', servers MUST either simulate the deposit or return a status code of 400 Bad Request.
X-Packaging URI Clients SHOULD use this header with a value taken from the enumeration in [SWORD-TYPES] (see also Part A Section 1.2). If the server cannot accept the format given in the header it MUST return a status code of 415 Unsupported Media Type.

9.3 Editing Resources with PUT, 9.4 Deleting Resources with DELETE

SWORD implementations MAY implement the AtomPub mechanisms to edit and delete Atom Entries and Media Resources. Where a server does not support these mechanisms, it SHOULD respond to requests with either code 405 (Method Not Allowed) or 501 (Not Implemented), as appropriate.

9.6 Media Resources and Media Link Entries

SWORD is primarily concerned with depositing binary files/packages of content as Media Resources rather than ATOM documents - implementers should pay particular attention to this section and to section 9.6 of [AtomPub]. The server MUST signal the media types it will accept using the app:accept element in the Service Document, as specified in [AtomPub] Section 8.3.4, and SHOULD signal the content package types it will accept using the sword:acceptPackaging element, as described in Part B Section 8.1 of this specification.

The Location: element of the HTTP header response MUST contain the URI of the Media Link Entry, as defined in ATOMPUB. The Media Link Entry URI MUST dereference, and MUST contain an atom:content element with a src attribute containing a URI. This URI SHOULD dereference to either the original deposited file or a machine readable description of the resources created as a result of the deposit (such as an OAI-ORE Resource Map serialization, see [ORE]). If the URI of the content changes over time, e.g. as the result of a workflow process, the server MUST reflect this change by changing the Media Entry Document content element, or by using HTTP features (e.g. redirection, Content-Location headers etc) to direct clients from the original content location.

Providing an edit-media link is OPTIONAL. If a server provides an edit-media link it SHOULD allow media resource updating with PUT as described in [AtomPub] sections 9.3 and 9.6.

As in [Atom], the atom:id element MUST contain a unique identifier for the deposit.

According to [AtomPub], an atom:link element SHOULD be supplied with a rel="edit-media" attribute and a href attribute containing a URI for the Media Resource. It is OPTIONAL that this URI be the same as that supplied as the src attribute of the atom:content element. SWORD makes no further recommendations about what this link element should resolve to; examples might include a representation which supplies metadata from the package and access to unpacked binary files. Alternatively, a repository might supply multiple atom:link elements to identify each unpacked resource. This is an implementation decision.

According to AtomPub, an atom:link element MAY be supplied with a rel="edit" attribute and a href attribute containing a URI for the Media Link Entry metadata. SWORD makes no further recommendations about what this link element should resolve to; examples might include a jump-off page, users private metadata or workflow management page. This link MAY allow authorized users to make further edits to the atom, or other, metadata.

Wherever practical, URIs SHOULD dereference to a logical location, SHOULD be unique and SHOULD persist. If an implementation does need to indicate that a Media Entry Document has been removed, it SHOULD return 410 Gone to future requests. In other circumstances where URIs do not dereference, a 501 Not Implemented HTTP error code SHOULD be returned, with a human-readable explanation.

9.8 The Atom Entry Document

On successfully accepting a POST (deposit), implementers MUST return an Atom Entry Document with the HTTP response. The Atom Entry Document will usually contain information about the 'deposit'; this is not the same as the metadata describing the file(s) within the package which SHOULD be supplied within the package itself. Implementers are free to extend their use of the atom:content element to carry additional metadata but this is beyond the scope of this profile.

Atom Entry Documents must contain elements as follows: -

Element Allowed Values Usage
atom:contributor Text SHOULD contain the value of the X-On-Behalf-Of header, if one was present in the POST request (See Part A Section 2)
atom:generator Text SHOULD contain the URI and version of the server software.
sword:userAgent Text Clients SHOULD provide a User-Agent request-header (as described in [HTTP1.1] section 14.43). If provided, servers SHOULD store the value in the sword:userAgent element.
sword:treatment Text MUST be present and contain either a human-readable statement describing treatment the deposited resource has received or a URI that dereferences to such a description.
sword:verboseDescription Text If the client made the POST request with an X-Verbose:true header, the server SHOULD supply a verbose description of the deposit process. See Part A Section 3.2
sword:noOp 'true'|'false' If the client made the POST request with an X-No-Op:true header, the server SHOULD reflect this by including a sword:noOp element with a value of "true' in the response. See Part A Section 3.1. Servers MAY use a value of 'false' to indicate that the deposit proceeded but MUST NOT use this element to signify an error.
sword:packaging URI If the POST request results in the creation of packaged resource, the server MAY use this element to declare the packaging type. If used it SHOULD take a value from [SWORD-TYPES].

10. Listing Collections

AtomPub states that "Collection Resources MUST provide representations in the form of Atom Feed elements whose Entries contain the IRIs of Members in the Collection". The SWORD profile does not require Collection lists, but implementers MAY wish to support this feature in order to be [AtomPub] compliant. As noted in Part B Section 5.2, clients MUST NOT rely on Collection Lists in order to make a SWORD deposit.

11. Atom Format

The SWORD Profile uses the "edit" and "edit-media" link relations. The SWORD profile does not currently support updates to deposited items, therefore a URI with an edit or edit-media link relation points to a Member Entry which MAY be editable, but is not required to be.

14. Securing the Atom Publishing Protocol

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

15. Security Considerations

Implementers should refer to this section of AtomPub.

References

[SWORD-TYPES] Allinson, J. et al, SWORD Content Package Types, September 2008. TODO updated publication date and link.

[Atom] Nottingham, M. and R. Sayre, "The Atom Syndication Format", RFC 4287, December 2005. http://www.ietf.org/rfc/rfc4287.txt (see also non-normative html version at http://APP.org/rfc4287.html)

[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)

[HTTP1.1] Fielding et al, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999 http://www.w3.org/Protocols/rfc2616/rfc2616.html

[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

[OAUTH] Atwood, A., Conlan, R. et al OAuth Core 1.0 http://oauth.net/core/1.0/, December 2007

[ORE] Lagoze, C., Van de Sompel, H et al, Open Archives Initiative Object Reuse and Exchange, http://www.openarchives.org/ore/, June 2008

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

[RFC2119] Bradner, S. "Key words for use in RFCs to Indicate Requirement Levels". http://www.ietf.org/rfc/rfc2119.txt, March 1997.