SWORD 2.0 Profile

Note that although there are 7 IRIs defined above, only 2 of them are added by SWORD: State-IRI and SE-IRI, the rest are replicated from [AtomPub] and are labelled here for convenience. Furthermore, the SE-IRI MAY be the same as the Edit-IRI. Meanwhile the EM-IRI may be the same as the Cont-IRI, so implementers can implement the entire specification with only 5 differentiable IRIs.

4. Namespaces

4.1. SWORD Namespaces

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 "zip" and "binary":

Root namespace for any Error documents which SWORD can produce:

Root namespace for any State terms that SWORD wishes to provide:

4.2. Referenced Namespaces

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

5. IRIs

The packaging format which represents a binary file which should not be unpacked by the server

The primitive SWORD packaging format, which represents a plain ZIP file during resource creation or update, and in Atom Multipart [AtomMultipart] deposit indicates that the Media Part is a plain ZIP file.

6. Protocol Operations

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]

6.1. Retrieving a Service Document

1. The client sends a GET request to the IRI of the Service Document.
2. The server responds with a Service Document enumerating the IRIs of a group of Collections and the capabilities of those Collections supported by the server. The content of this document can vary based on aspects of the client request, including, but not limited to, authentication credentials.

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-IRI 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]:

• The SWORD server MUST specify the sword:version element with a value of 2.0 [SWORD003]
as a child of the app:service element.
• The SWORD server MAY specify the sword:maxUploadSize (in kB) of content that can be uploaded in one request [SWORD003] as a child of the app:service element. If provided this MUST contain an integer.
• The SWORD server MUST specify the app:accept element for the app:collection element. If the Collection can take any format content type, it should specify */* as its value [AtomPub]. It MUST also specify an app:accept element with an alternate attribute set to multipart-related as required by [AtomMultipart]. The formats specified by app:accept and app:accept@alternate="multipart-related" are RECOMMENDED to be the same.
• The SWORD server MAY include one sword:collectionPolicy [SWORD003] as a child of the app:collection element
• The SWORD server SHOULD include one sword:mediation element as a child of the app:collection element with a value of true or false [SWORD002]
• The SWORD server MAY include one sword:treatment element [SWORD003]as a child of the app:collection element
• The SWORD server MAY include zero or more sword:acceptPackaging elements [SWORD002] as a children of the app:collection element. The value SHOULD be a IRI for a known packaging format (where such IRIs exist)
• The SWORD server MAY include zero or more sword:service [SWORD003] elements as children of the app:collection element containing references to nested service descriptions

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-iri/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/SimpleZip</sword:acceptPackaging>
            <sword:acceptPackaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:acceptPackaging>
            <sword:service>http://swordapp.org/sd-iri/e4</sword:service>
        </collection>
    </workspace>
</service>

The following requirements are placed on the client in receipt of a service document:

• If no sword:maxUploadSize is specified, the client MUST assume that no size limit exists, but this specification RECOMMENDS that clients limit themselves to reasonably small file sizes unless special arrangements with the server have been made.
• If no sword:mediation element is specified, the client MUST assume a value of false.
• If no sword:acceptPackaging element is specified, the client MUST assume that the server will not formally support packaging formats (see Section 5: IRIs and Section 7: Packaging for more details).
• The client SHOULD NOT attempt to deposit files with a packaging format that is not in the sword:acceptPackaging elements, although the client MAY specify the binary package format (see Section 5: IRIs and Section 7: Packaging for more details) in order to deposit opaquely packaged content

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

6.3. Creating a Resource

6.3.1. Creating a Resource with a Binary File Deposit

The client can create a resource by POSTing the binary content as the body of an HTTP request to the Col-IRI, with the Content-Type, Content-Disposition, and Packaging headers, with the following requirements:

• The client SHOULD supply a Content-Type header
• The client MUST supply a Content-Disposition header with a filename parameter
• The client SHOULD supply a Content-MD5 header with the MD5 checksum hex encoded for the binary content
• The client SHOULD supply a Packaging header [SWORD001] providing the IRI (or other allowed) of the packaging format used. See Section 7: Packaging for more details.
• The client MAY provide an In-Progress header with a value of true or false [SWORD001]. See Section 9: Continued Deposit for more details.
• The client MAY provide an On-Behalf-Of header [SWORD001]. See Section 8: Authentication and Mediated Deposit for more details.
• The client MAY supply a Slug header providing a suggested identifier for the deposited content

POST Col-IRI 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
Slug: [suggested identifier]

[request entity]

The requirements placed on the server here are:

• If no Content-Type header is supplied the server MUST behave as per Section 7.2.1 in [RFC2616]
• The server SHOULD verify the Content-MD5 header against the content. If the check fails, the server MUST respond with 412 Precondition Failed. See Section 12: Error Documents.
• Server implementations MUST adopt the behaviour and requirements in [RFC2183] with respect to the Content-Disposition header.
• If there is no Packaging header, the server SHOULD assume that it is the binary packaging format (See Section 5: IRIs
• Server implementations MUST adopt the behaviour and requirements in Section 9.7 of [AtomPub] with respect to the Slug header.
• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit
• The server MUST carry out authentication and mediated deposit as described in Section 8: Authentication and Mediated Deposit
• The server MUST create a new resource containing content equivalent to or derived from the deposited content, or return an error document.

Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 10: Deposit Receipt with the HTTP status code 201 (Created). The Deposit Receipt MUST be available under the Edit-IRI (Member Entry IRI), as supplied in the Location header.

For example:

201 Created
Location: [Edit-IRI]

[optional Deposit Receipt]

6.3.2. Creating a Resource with a Multipart Deposit

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 package (possibly a simple ZIP) with a set of Dublin Core metadata terms [DublinCore] embedded in an Atom Entry.

The SWORD server is not required to support packaging formats, but this profile RECOMMENDS that the server be able to accept a ZIP file as the Media Part of an Atom Multipart request (See Section 5: IRIs and Section 7: Packaging for more details).

The client can create a resource by POSTing a multipart mime message to the Col-IRI 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:

• The client MUST comply with the rules laid out in [AtomMultipart]
• The client MUST supply a Content-Disposition header of type attachment on the Entry Part with a name parameter set to atom [SWORD004]
• The client MUST supply a Content-Disposition header of type attachment on the Media Part with a name parameter set to payload and a filename parameter [SWORD004]
• The client SHOULD supply a Content-MD5 header with the MD5 checksum hex encoded for the binary content on the Media Part
• The client SHOULD supply a Packaging header [SWORD001] providing the IRI (or other allowed) of the packaging format used on the Media Part
• The client MAY provide an In-Progress header with a value of true or false [SWORD001] on the main HTTP header
• The client MAY provide an On-Behalf-Of header [SWORD001] on the main HTTP header
• The client MAY supply a Slug header providing a suggested identifier for the deposited content on the main HTTP header
• The client SHOULD add Dublin Core [DublinCore] terms to the Atom Entry as foreign markup (if appropriate); the terms MUST be embedded as direct children of the atom:entry element, if present.
• The client MAY add any other metadata formats or foreign markup to the atom:entry element

For example:

POST Col-IRI 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
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/SimpleZip
Content-MD5: [md5-digest]
MIME-Version: 1.0

[...binary package data...]
--===============1605871705==--

The requirements placed on the server here are:

• The server SHOULD verify the Content-MD5 header against the Media Part. If the check fails, the server MUST respond with 412 Precondition Failed. See Section 12: Error Documents.
• Server implementations MUST adopt the behaviour and requirements in [RFC2183] with respect to the Content-Disposition header for the Media Part
• If there is no Packaging header on the Media Part, the server SHOULD assume that it is the binary packaging format (See Section 5: IRIs)
• Server implementations MUST adopt the behaviour and requirements in Section 9.7 of [AtomPub] with respect to the Slug header
• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit
• The server MUST create a new resource containing content equivalent to or derived from the deposited content, or return an error document.
• The server MUST be able to record and later reflect the Dublin Core [DublinCore] foreign markup in the atom:entry element, but MAY NOT understand any other embedded formats.

Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 10: Deposit Receipt with the HTTP status code 201 (Created). The Deposit Receipt MUST be available under the Edit-IRI (Member Entry IRI), as supplied in the Location header.

For example:

201 Created
Location: [Edit-IRI]

[optional Deposit Receipt]

6.3.3. Creating a Resource with an Atom Entry

Clients can create a container within a SWORD server and optionally provide it with metadata without adding any binary content to it. This is done by POSTing an Atom Entry to the Col-IRI with the following requirements:

• The client SHOULD supply a Content-Type header with the value application/atom+xml;type=entry
• The client MAY provide an In-Progress header with a value of true or false [SWORD001]. See Section 9: Continued Deposit for more details.
• The client MAY provide an On-Behalf-Of header [SWORD001]. See Section 8: Authentication and Mediated Deposit for more details.
• The client MAY supply a Slug header providing a suggested identifier for the deposited content
• The client SHOULD add Dublin Core [DublinCore] terms to the Atom Entry as foreign markup (if appropriate); the terms MUST be embedded as direct children of the atom:entry element, if present.
• The client MAY add any other metadata formats or foreign markup to the atom:entry element

For example:

POST Col-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: application/atom+xml;type=entry
In-Progress: true
On-Behalf-Of: jbloggs
Slug: [suggested identifier]

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

The requirements placed on the server here are:

• Server implementations MUST adopt the behaviour and requirements in Section 9.7 of [AtomPub] with respect to the Slug header
• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit
• The server MUST create a new resource, or return an error document.
• The server MUST be able to record and later reflect the Dublin Core [DublinCore] foreign markup in the atom:entry element, but MAY NOT understand any other embedded formats.
• The server MUST supply an EM-IRI for the client to use in future update operations, even though this EM-IRI may at this stage not return any content under HTTP GET.

Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 10: Deposit Receipt with the HTTP status code 201 (Created). The Deposit Receipt MUST be available under the Edit-IRI (Member Entry IRI), as supplied in the Location header.

For example:

201 Created
Location: [Edit-IRI]

[optional Deposit Receipt]

6.4. Retrieving the content

The Deposit Receipt contains two IRIs which can be used to retrieve content from the server: Cont-IRI and EM-IRI. 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-IRI, while all operations are permitted on the EM-IRI. It is acceptable, but not required, that both IRIs to be the same, and in this section we refer only to the EM-IRI but in all cases it can be substituted for the Cont-IRI.

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-IRI/43/my_deposit"/>
    <link rel="edit-media" href="http://swordapp.org/em-IRI/43/my_deposit"/>

    <sword:packaging>http://purl.org/net/sword/package/SimpleZip</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>

Requests to retrieve the Media Resource here refer to the Media Resource as a whole, as per [AtomPub], and not to any of the component parts of a complex Media Resource. That is, the response to a request for the Media Resource should be considered a representation of the entire content of the object on the server, and it is not permissable to attempt to content negotiate for a particular part of the Media Resource. Implementers who wish to access the parts of a Media Resource should see Section 6.4.1. Atom Feed Representations of Media Resources below.

To retrieve the content in the desired packaging format, the client makes an HTTP GET request to the EM-IRI and MAY supply an Accept-Packaging header [SWORD001] with the IRI from one of the sword:packaging elements.

If the content is not in a publicly available space on the server, the user agent may be required to authenticate. In these cases the client MAY supply the On-Behalf-Of header [SWORD001] for informational purposes.

The server will respond in different ways depending on a number of conditions:

1. If the Accept-Packaging header is not supplied, the server SHOULD assume a simple ZIP packaging format (see Section 5: IRIs), but MAY elect another format if it wishes. The server MUST then supply the client with a package which meets these specifications, and SHOULD provide the SimpleZip IRI in a Packaging header on the response.
2. If the Accept-Packaging header is supplied, and contains the IRI (or other allowed value) of a format that the server supports, the server MUST then supply the client with a package which meets these specifications, and SHOULD provide an IRI (or other allowed value) of the format being returned in a Packaging header on the response.
3. If the Accept-Packaging header is supplied but contains a IRI (or other allowed value) for a format that the server does not support, the server MUST respond with 406 Not Acceptable and MAY include an error document as per Section 12: Error Documents.

Upon receiving a successful response, if no Packaging header is provided in the response the client SHOULD assume that it is a SimpleZip.

For more details about the packaging process, see Section 7: Packaging

6.4.1. Atom Feed Representations of Media Resources

It is RECOMMENDED that implementations provide an EM-IRI in the Deposit Receipt with a type of application/atom+xml;type=feed in addition to any other types available.

For example:

<entry xmlns="http://www.w3.org/2005/Atom"
        xmlns:sword="http://purl.org/net/sword/">

    [...]

    <link rel="edit-media" href="http://swordapp.org/em-IRI/43/my_deposit"/>
    <link rel="edit-media" type="application/atom+xml;type=feed" href="http://swordapp.org/em-IRI/43/my_deposit.feed"/>

    [...]
        
</entry>

The exact contents of the Feed representation are unspecified, but it is RECOMMENDED that this is a list of atom:entry elements which represent the individual media items which together form the Media Resource.

NOTE that this is not the same as the Statement, which is a representation of the entire object on the server, not just the Media Resource. See Section 11: The SWORD Statement for details

6.5. Replacing the Content of a Resource

6.5.1. Replacing the File Content of a Resource

The client can replace the existing content of a resource by performing an HTTP PUT of some new binary content to the EM-IRI, with the following requirements:

• The client SHOULD supply a Content-Type header
• The client MUST supply a Content-Disposition header with a filename parameter
• The client SHOULD supply a Content-MD5 header with the MD5 checksum hex encoded for the binary content
• The client SHOULD supply a Packaging header [SWORD001] providing the IRI (or other allowed) of the packaging format used
• The client MAY provide an On-Behalf-Of header [SWORD001]

For example:

PUT EM-IRI 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
On-Behalf-Of: jbloggs

[request entity]

The requirements placed on the server here are:

• The server SHOULD verify the Content-MD5 header against the content. If the check fails, the server MUST respond with 412 Precondition Failed. See Section 12: Error Documents.
• Server implementations MUST adopt the behaviour and requirements in [RFC2183] with respect to the Content-Disposition header
• If there is no Packaging header, the server SHOULD assume that it is the binary packaging format (See Section 5: IRIs)
• If the container to which the deposit is being made has been previously marked as "in progress", the server SHOULD continue to respect that assertion as per Section 9: Continued Deposit.
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server MUST effectively replace all the existing content in the item (subject to the rules associated with Metadata Handling), although implementations may choose to provide versioning or some other mechanism for retaining the overwritten content.

Once the server has processed the request it MUST return an HTTP status code 200 (OK), or an appropriate error code.

6.5.2. Replacing the Metadata of a Resource

The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. The client can only be sure that the server will support this process when using the default format supported by SWORD: Qualified Dublin Core XML embedded directly in the atom:entry. Other metadata formats MAY be supported by a particular server, but this is not covered by the SWORD profile.

• The client SHOULD supply a Content-Type header with the value application/atom+xml
• The client MAY provide an On-Behalf-Of header [SWORD001]
• The client MAY provide an In-Progress header with a value of true or false [SWORD001]. See Section 9: Continued Deposit for more details.

For example:

PUT Edit-IRI HTTP/1.1
Host: example.org
Content-Type: application/atom+xml
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
On-Behalf-Of: jbloggs

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

The requirements placed on the server here are:

• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server MUST effectively replace all the existing metadata in the item, although implementations may choose to provide versioning or some other mechanism for retaining the overwritten metadata.

Once the server has processed the request it MUST return an HTTP status code 200 (OK) or 204 (No Content), or an appropriate error code.

6.5.3. The Metadata and File Content of a Resource

The client can replace both the metadata and content of a resource by performing an HTTP PUT on the Edit-IRI with a multipart mime message, as per Section 6.3.2. Creating a Resource with a Multipart Deposit

• The client MUST comply with the rules laid out in [AtomMultipart]
• The client MUST supply a Content-Disposition header of type attachment" on the Entry Part with a name parameter set to atom [SWORD004]
• The client MUST supply a Content-Disposition header of type attachment on the Media Part with a name parameter set to payload and a filename parameter [SWORD004]
• The client SHOULD supply a Content-MD5 header with the MD5 checksum hex encoded for the binary content on the Media Part
• The client SHOULD supply a Packaging header [SWORD001] providing the IRI (or other allowed) of the packaging format used on the Media Part
• The client MAY provide an In-Progress header with a value of true or false [SWORD001] on the main HTTP header
• The client MAY provide an On-Behalf-Of header [SWORD001] on the main HTTP header
• The client SHOULD add Dublin Core [DublinCore] terms to the Atom Entry as foreign markup (if appropriate); the terms MUST be embedded as direct children of the atom:entry element, if present.
• The client MAY add any other metadata formats or foreign markup to the atom:entry element

For example:

PUT Edit-IRI 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
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/SimpleZip
Content-MD5: [md5-digest]
MIME-Version: 1.0

[...binary package data...]
--===============1605871705==--

The requirements placed on the server here are:

• The server SHOULD verify the Content-MD5 header against the Media Part. If the check fails, the server MUST respond with 412 Precondition Failed. See Section 12: Error Documents.
• Server implementations MUST adopt the behaviour and requirements in [RFC2183] with respect to the Content-Disposition header for the Media Part
• If there is no Packaging header on the Media Part, the server SHOULD assume that it is the binary packaging format (See Section 5: IRIs)
• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit
• The server MUST overwrite the existing metadata and content with metadata and content equivalent to or derived from the deposited content, or return an error document. Servers may choose to implement versioning to retain previous copies of the content.
• The server MUST be able to record and later reflect the Dublin Core [DublinCore] foreign markup in the atom:entry element, but MAY NOT understand any other embedded formats.

Once the server has processed the request it MUST return an HTTP status code 200 (OK) or 204 (No Content), or an appropriate error code.

6.6. Deleting the Content of a Resource

The client can remove all the content of a resource without removing the resource itself by issuing an HTTP DELETE request on the EM-IRI, with the following requirements:

• The client MAY provide an On-Behalf-Of header [SWORD001]

For example:

DELETE EM-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
On-Behalf-Of: jbloggs

The requirements placed on the server here are:

• If the container to which the deposit is being made has been previously marked as "in progress", the server SHOULD continue to respect that assertion as per Section 9: Continued Deposit.
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server MUST effectively delete all the existing content in the item (subject to the rules associated with Metadata Handling), although implementations may choose to provide versioning or some other mechanism for retaining the deleted content.

Once the server has processed the request it MUST return an HTTP status code 200 (OK) or 204 (No Content), or an appropriate error code.

6.7. Adding Content to a Resource

6.7.1. Adding New Packages or Files to a Container

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 SE-IRI, with the following requirements:

• The client SHOULD supply a Content-Type header
• The client MUST supply a Content-Disposition header with a filename parameter
• The client SHOULD supply a Content-MD5 header with the MD5 checksum hex encoded for the binary content
• The client SHOULD supply a Packaging header [SWORD001] providing the IRI (or other allowed) of the packaging format used
• The client MAY provide an In-Progress header with a value of true or false [SWORD001]
• The client MAY provide an On-Behalf-Of header [SWORD001]

POST SE-IRI 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

[request entity]

The requirements placed on the server here are:

• The server SHOULD verify the Content-MD5 header against the content. If the check fails, the server MUST respond with 412 Precondition Failed. See Section 12: Error Documents.
• Server implementations MUST adopt the behaviour and requirements in [RFC2183] with respect to the Content-Disposition header
• If there is no Packaging header, the server SHOULD assume that it is the binary packaging format (See Section 5: IRIs)
• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit.
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server SHOULD NOT overwrite any existing content, and MUST add content equivalent to or derived from the deposited content to the existing container or respond with an error document.

Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 10: Deposit Receipt with the HTTP status code 200 (OK). The Deposit Receipt MUST be available under the Edit-IRI (Member Entry IRI), which the server MAY supply in the Location header.

For example:

200 OK
Location: [Edit-IRI]

[optional Deposit Receipt]

6.7.2. Adding New Metadata to a Container

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, to the SE-IRI:

• The client MUST supply a Content-Type header with the value application/atom+xml or application/atom+xml;type=entry
• The client MAY provide an In-Progress header with a value of true or false [SWORD001]
• The client MAY provide an On-Behalf-Of header [SWORD001].
• The client MAY add Dublin Core [DublinCore] terms to the Entry as foreign markup; the terms MUST be embedded as direct children of the atom:entry element.
• The client MAY add any other metadata format or foreign markup to the atom:entry element

POST SE-IRI 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

[entry document]

The requirements placed on the server here are:

• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit.
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server MUST be able to interpret and later reflect the Dublin Core [DublinCore] foreign markup in the atom:entry element, but MAY NOT understand any other embedded formats, but MUST NOT generate an error on the presence of not-understood markup.
• The server SHOULD only add metadata and not overwrite any existing metadata, but exact implementation will depend on the functions of the server.

Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 10: Deposit Receipt with the HTTP status code 200 (OK). The Deposit Receipt MUST be available under the Edit-IRI (Member Entry IRI), which the server MAY supply in the Location header.

For example:

200 OK
Location: [Edit-IRI]

[optional Deposit Receipt]

6.7.3. Adding New Metadata and Packages or Files to a Container with Multipart

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 SE-IRI:

• The client MUST comply with the rules laid out in [AtomMultipart]
• The client MUST supply a Content-Disposition header of type attachment on the Entry Part with a name parameter set to atom [SWORD004]
• The client MUST supply a Content-Disposition header of type attachment on the Media Part with a name parameter set to payload and a filename parameter [SWORD004]
• The client SHOULD supply a Content-MD5 header with the MD5 checksum hex encoded for the binary content on the Media Part
• The client SHOULD supply a Packaging header [SWORD001] providing the IRI (or other allowed) of the packaging format used on the Media Part
• The client MAY provide an In-Progress header with a value of true or false [SWORD001] on the main HTTP header
• The client MAY provide an On-Behalf-Of header [SWORD001] on the main HTTP header
• The client MAY add Dublin Core [DublinCore] terms to the Entry as foreign markup; the terms MUST be embedded as direct children of the atom:entry element.
• The client MAY add any other metadata format to the atom:entry element

For example:

POST SE-IRI 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
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/SimpleZip
Content-MD5: [md5-digest]
MIME-Version: 1.0

...binary package data...
--===============1605871705==--

The requirements placed on the server here are:

• The server SHOULD verify the Content-MD5 header against the Media Part. If the check fails, the server MUST respond with 412 Precondition Failed. See Section 12: Error Documents.
• Server implementations MUST adopt the behaviour and requirements in [RFC2183] with respect to the Content-Disposition header for the Media Part.
• If there is no Packaging header on the Media Part, the server SHOULD assume that it is the binary packaging format (See Section 5: IRIs)
• Server implementations MUST adopt the behaviour and requirements in Section 9.7 of [AtomPub] with respect to the Slug header
• If there is no In-Progress header, the server MUST assume that it is false, and MUST behave as described in Section 9: Continued Deposit.
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server MUST be able to interpret the Dublin Core [DublinCore] foreign markup in the atom:entry element, but MAY NOT understand any other embedded formats, but MUST NOT generate an error on encountering not-understood foreign markup.

Once the server has processed the request it SHOULD return a Deposit Receipt as described in Section 10: Deposit Receipt with the HTTP status code 201 (Created). The Deposit Receipt MUST be available under the Edit-IRI (Member Entry IRI), which the server MAY supply in the Location header.

For example:

201 Created
Location: [Edit-IRI]

[optional Deposit Receipt]

6.7.4. Adding Files to the Media Resource

The client can add more content to the Media Resource itself by performing an HTTP POST request on the EM-IRI. This has the effect of placing new files into the Media Resource itself.

This feature is for use when clients wish to send individual files to the server and to receive back the IRI for the created resource. POSTing to the SE-IRI will not give back the location of the deposited resource in the HTTP Location header, so in cases where the server does not provide the (optional) Deposit Receipt, it is not possible for the client to ascertain the location of the file actually deposited - the Location header in that operation is the Edit-IRI. By POSTing to the EM-IRI, the Location header will return the IRI of the deposited file itself, rather than that of the container.

As the EM-IRI represents the Media Resource itself, rather than the Container, this operation will not formally support metadata handling, and therefore also offers no explicit support for packaging either since packages may be both content and metadata. Nonetheless, for files which may contain extractable metadata, there is a Metadata-Relevant header which can be defined to indicate whether the deposit can be used to augment the metadata of the container.

When depositing packages, the best approach is to POST to the SE-IRI (See Sections 6.7.1, 6.7.2, 6.7.3), as POST to EM-IRI.

When carrying out this operation, the requirements for the client are:

• The client SHOULD supply a Content-Type header
• The client MUST supply a Content-Disposition header with a filename parameter
• The client SHOULD supply a Content-MD5 header with the MD5 checksum hex encoded for the binary content
• The client MAY provide an On-Behalf-Of header [SWORD001]
• The client MAY provide a Metadata-Relevant header, with the value true or false. This should be set to true if the server should consider the file a potential source of metadata extraction, or false if the server should not attempt to extract any metadata from the deposit.

POST EM-IRI HTTP/1.1
Host: example.org
Content-Type: application/pdf
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-MD5: [md5-digest]
Content-Disposition: attachment; filename=[filename]
On-Behalf-Of: jbloggs

[request entity]

The requirements placed on the server here are:

• The server SHOULD verify the Content-MD5 header against the content. If the check fails, the server MUST respond with 412 Precondition Failed, and MAY return a SWORD Error document. See Section 12: Error Documents.
• Server implementations MUST adopt the behaviour and requirements in [RFC2183] with respect to the Content-Disposition header
• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server SHOULD NOT overwrite any existing content, and MUST add content equivalent to or derived from the deposited content to the existing container or respond with an error document.
• If there is no Metadata-Relevant header, the server MAY assume that it is true and MAY attempt to extract metadata from the deposit. If the Metadata-Relevant is false the server SHOULD NOT attempt to extract metadata from the deposit.

Once the server has processed the request it is RECOMMENDED that it returns a Deposit Receipt as described in Section 10: Deposit Receipt with the HTTP status code 201 (Created). The server MAY, though, return any response which it feels appropriate, and this profile does not limit the response types in any way. Nonetheless, the server MUST include an HTTP Location header with the IRI of the created resource.

For example:

201 Created
Location: [File-IRI]

[optional Deposit Receipt]

6.8. Deleting the Container

The client can delete the entire object on the server by issuing an HTTP DELETE request on the Edit-IRI, with the following requirements:

• The client MAY provide an On-Behalf-Of header [SWORD001]

DELETE Edit-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
On-Behalf-Of: jbloggs

The requirements placed on the server here are:

• If there is an On-Behalf-Of header, the server MUST behave as described in Section 8: Authentication and Mediated Deposit.
• The server MUST effectively remove the Container and all its content, although implementations may choose to provide versioning or some other mechanism for retaining the deleted content.
• The Edit-IRI MUST return a 404 Not Found on any future requests.

Once the server has processed the request is MUST respond with an HTTP status code 204 (No Content) and leave the response body empty.

6.9. Retrieving the Statement

The Statement can be found either embedded as foreign markup inside the Deposit Receipt, or can be retrieved by requesting the IRI 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-IRI. 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 11: The SWORD Statement.

6.10. Use of SWORD with arbitrary IRIs

During normal operation the SWORD server may respond to requests by the client with documents (such as the Statement) which contain IRIs for resources which are not formally covered by this profile. For example, the Statement may include IRIs to files unpacked from an original deposit package and made available independently. Or an implementation of a content management protocol such as CMIS [CMIS] or GData [GData] may provide IRIs for resources or collections of resources.

The following headers MAY be used by the client under the following conditions on any IRI outside of the scope of this profile, where the meanings of the headers are as defined in [SWORD001]:

The client MUST NOT assume that a SWORD server will support these headers for arbitrary IRIs. It is likely that the use of these headers by the client will be through explicit agreement between client and server implementation pairs that these headers will be supported alongside any content management API implemented in addition to SWORD.

7. Packaging

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.

7.1. Package support in Service description

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 IRI (as per [SWORD002]), but MAY be identified by an arbitrary string.

If no sword:acceptPackaging element is supplied the client MUST assume that the server does not formally support any package formats, and should expect everything to be treated as per the server's policies with regard to the mimetype as per the app:accept element.

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

7.2. Package support during resource creation

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

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

If the server does not supply any sword:packaging elements, the client MUST assume that the server only supports a simple zip file packaging format (See Section 5: IRIs).

<?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-IRI/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-IRI/43/my_deposit.atom" />
</entry>

7.4. Registering packaging types under the SWORD namespace

Clients and servers SHOULD use IRIs to communicate about package types, and MAY use IRIs registered under the SWORD namespace. To register a new IRI in the SWORD namespace, please contact the SWORD team at the contact details at the bottom of this document. Registration of package IRIs under the SWORD namespace is strictly OPTIONAL.

8. Authentication and Mediated Deposit

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

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

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-IRI/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>

8.2. Recording Depositing Users

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 11: The SWORD Statement for details of the serialisation.

9. Continued Deposit

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.

An example use case for this is that the client may be embedded into a system which uses the SWORD server as a storage layer, but which cannot acquire all of the content for a "finished" item in one deposit operation. Consider a user-facing system which encourages users to upload files one at a time through some web interface, which causes each file to be directly deposited onto the SWORD server. In each case, the client would assert the deposit is still In-Progress until the user confirms that they have uploaded all the relevant files, or navigates away from the page. At that stage, the client can issue a blank HTTP POST request to the SWORD server, with In-Progress: false to complete the deposit.

9.1. Deposit Complete

If In-Progress is false, the server MUST assume that it can carry on processing the deposit or deletion as it sees fit.

9.2. Deposit Incomplete

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.

9.3. Completing a Previously Incomplete Deposit

The client can assert that a deposit process has completed by issuing an HTTP POST to the SE-IRI with a blank message body and with the In-Progress header set to false (it may simply omit the header altogether too, as this is treated as In-Progress: false by the server).

POST SE-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: 0
User-Agent: MyJavaClient/0.1 Restlet/2.0
In-Progress: false

If In-Progress is false, the server MUST assume that it can carry on processing the deposit or deletion as it sees fit.

Deposit Receipt

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: