SWORD 3.0 Protocol Behaviours

Version: SWORD 3.0

Last modified: 2021-09-01 09:54

This document provides details of the specific protocol requirements for every operation that SWORD 3.0 supports.

See also: SWORD 3.0 Specification from which this document of denormalised protocol operations is derived.

Each section describes the operation you can perform, and then the technical details of performing it, as follows:

1. Retrieve the Service Document

Request from the server a list of the Service-URLs that the client can deposit to. A Service-URL allows the server to support multiple different deposit conditions - each URL may have its own set of rules/workflows behind it; for example, Service-URLs may be subject-specific, organisational-specific, or process-specific. It is up to the client to determine which is the suitable URL for its deposit, based on the information provided by the server. The list of Service-URLs may vary depending on the authentication credentials supplied by the client.

This request can be made against a root Service-URL, which will describe the capabilities of the entire server, for information about the full list of Service-URLs, or can be made against an individual Service-URL for information just about that service.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

2. Creating New Objects

2.1. Creating Objects with no content

Create a new Object on the server with no metadata or binary content. That is, create a container into which you can subsequently send data. It is RECOMMENDED that when using this route you specify In-Progress: true.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

2.2. Creating Objects with only Metadata

Create a new Object on the server, sending only Metadata content (i.e. no Binary File content, and no By-Reference Files).

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

2.3. Creating Objects with only By-Reference Files

Create a new Object on the server, sending on By-Reference Files (i.e. no Binary Files and no Metadata)

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

2.4. Creating Objects with both Metadata and By-Reference Files

Create a new Object on the server, sending both Metadata content and By-Reference Files (i.e. no Binary File content)

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true; by-reference=true

2.5. Creating Objects with Binary Files

Create a new Object on the server, sending a single Binary File. The Binary File is an opaque bitstream which the server should not attempt to unpack.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

2.6. Creating Objects with Packaged Content

Create a new Object on the server, sending a single Binary File. The Binary File itself is specified as Packaged Content, which the server may understand how to unpack.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

2.7. Creating Objects with Segmented File Upload

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Creating Objects with only By-Reference Files

3. Retrieving all or part of Objects

3.1. Retrieving an Object's Status

For an Object where you have an Object-URL, you may request information about the current state of that resource, and receive the Status document in response.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

3.2. Retrieving the Metadata from an Object

Retrieve the descriptive Metadata document associated with the Object in the standard SWORD format. This operation is done against the Metadata-URL, which is the resource URL representing the Object’s metadata. When retrieved, this resource is serialised only as the standard SWORD format, content negotiation is not supported. If you want to retrieve the metadata for the Object in other formats, you can see a list of the available formats in the Status document, and the individual expressions of the metadata can then be retrieved directly by the appropriate URL.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

3.3. Retrieving a Binary File from an Object

Retrieve a single File from the Object; files available for retrieval are listed in the Status document. These single files could be actual individual files that make up the object, or:

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

3.4. Retrieving a Packaged Content representation of an Object

To retrieve the full Object packaged according to some Packaging format, the Status document contains all the files that the Object contains, and identifies those which allow you to retrieve the entire objects as a package. Use the Status document to obtain the URL for the format you wish to retrieve, and make a GET to that URL. See the section "Retrieving a Binary File from an Object" for the specification of this operation.

4. Appending to existing Objects

Metadata and Files may be added to existing Objects through a variety of mechanisms, which are listed in this section.

4.1. Appending Metadata to an Object

Append new metadata to an Object. Metadata provided in this way should be considered to extend existing metadata, such that any new metadata fields are added to the Object, and any existing metadata fields are kept as-is.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

4.2. Appending By-Reference Files to an Object

Append new files to an Object by sending one or more By-Reference files.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

4.3. Appending Metadata and By-Reference Files to an Object

Append new files and append/overlay Metadata at the same time.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true; by-reference=true

4.4. Appending a single Binary File to an Object

Append new File to the Object, in addition to existing content which it already contains. This File will be added as-is to the Object, without the server unpacking it as it would Packaged Content.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

4.5. Appending Packaged Content to an Object

Append new Files (via Packaged Content) to the Object, in addition to existing content which it already contains. The package may be unpacked by the server and new file resources added. Metadata may also be appended/selectively updated, if the package contains actionable metadata.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

4.6. Append of Binary Files to an Object via Segmented File Upload

Append a single Binary File to an Object which will be delivered via a Segmented File Upload.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Appending By-Reference Files to an Object

4.7. Append of Packaged Content to an Object via Segmented File Upload

As Append of Binary Files to an Object via Segmented File Upload.

5. Replacing all or part of existing Objects

Metadata and Files may be replaced in existing Objects through a variety of mechanisms, which are listed in this section.

5.1. Replacing the Metadata of an Object

Replace in its entirety the Metadata associated with an Object.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

5.2. Replacing a single File in an Object

Replace an existing file in the Object with a new file. The server may keep the old version of the file available.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.3. Replacing a single File in an Object with a By-Reference File

Replace an existing file in the Object with a new file which the server retrieves as a By-Reference File. The server may keep the old version of the file available.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

5.4. Replacing a single File in an Object with a Segmented Upload

Replace an existing file in the Object with a new file, which the client will send in segments.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Replacing a single File in an Object with a By-Reference File

5.5. Replacing the FileSet of an Object with By-Reference Files

Replace all the files in the FileSet of an Object with one or more By-Reference Files. All previously existing files will be removed, and new ones will replace them. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

5.6. Replacing the FileSet of an Object with a single Binary File

Replace in its entirety the FileSet of the Object (i.e. not the Metadata), with a single Binary File. All previously existing files will be removed, and the new one will replace them. The server may or may not keep old versions of the content available, at its discretion.

Note that we can only send a single Binary File to replace the FileSet, we cannot send a package, as a package implies the presence of metadata which the FileSet-URL is not suitable to handle.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.7. Replacing the FileSet of an Object with a single Binary File via Segmented File Upload

Replace in its entirity the FileSet of the Object (i.e. not the Metadata), with a single Binary File, that is provided via Segmented File Upload. All previously existing files will be removed, and the new one will replace them. The server may or may not keep old versions of the content available, at its discretion.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Replacing the FileSet of an Object with By-Reference Files

5.8. Replacing an Object with Metadata only

Replace the entire Object, removing all previous files and metadata, and replace it with just the supplied Metadata. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

5.9. Replacing an Object with By-Reference Files only

Replace the entire Object, removing all previous files and metadata, and replace it with one or more files supplied via By-Reference upload. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

5.10. Replacing an Object with Metadata and By-Reference Files

Replace the entire Object, removing all previous files and metadata, and replace it with new Metadata and one or more files supplied via By-Reference upload. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true; by-reference=true

5.11. Replacing an Object with a single Binary File

Replace in its entirety the Object, including all Metadata and Files, with the single Binary File. All previous files and metadata will be removed, and new ones will replace them (the updated item will have no Metadata, though). The server may or may not keep old versions of the content available.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.12. Replacing an Object with Packaged Content

Replace in its entirety the Object, including all Metadata and Files, with the Metadata and Files contained in the Packaged Content. All previous files and metadata will be removed, and new ones will replace them. The server may or may not keep old versions of the content available.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.13. Replacing an Object with a single Binary File via Segmented File Upload

Replace in its entirety the Object, including all Metadata and Files, with a single Binary File, which will be delivered via Segmented File Upload. All previous files and metadata will be removed, and new ones will replace them. The server may or may not keep old versions of the content available.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Replacing an Object with By-Reference Files only

5.14. Replacing an Object with Packaged Content via Segmented File Upload

This operation is carried out exactly as per Replacing an Object with a single Binary File via Segmented File Upload.

6. Deleting all or part of Objects

6.1. Deleting an Object's Metadata

Delete all the metadata fields from the Object.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

6.2. Deleting a single Binary File from an Object

Delete a single File from the Object. The server may keep old versions of the file.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

6.3. Deleting all the Files from an Object

Remove all the Files from an object. This will leave the Object and its Metadata intact. The server may keep old versions of the files available.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

6.4. Deleting the entire Object

Delete the Object in its entirety from the server, along with all Metadata and Files.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

7. File Segments

7.1. Initialise a Segmented File Upload

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

7.2. Upload a File Segment

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

The Content-Disposition in this case would be:

Content-Disposition: segment; segment_number=[n]

7.3. Abort a Segmented File Upload

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

7.4. Retrieve information about a Segmented File Upload

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

8. Completing Previously In-Progress Deposits

Where you have previously carried out deposits and sent the object the In-Progress: true header, you will eventually need to tell the server that you have completed your additions or modifications to the Object, so that it can finalise your deposit.

Protocol Operation

Request Requirements

Server Requirements

Response Requirements

Error Responses

No Content-Disposition header is required in this request.