SWORD APP Profile 0.2
From DigiRepWiki
This profile has been replaced by the most recent version: http://purl.org/net/sword/
SWORD Profile of the Atom Publishing Protocol
Version 0.2, created 22nd May 2007
Introduction
This document is a profile of the Atom Publishing Protocol (APP). APP is an application-level protocol for publishing and editing Web resources. The APP is based on HTTP transfer of Atom-formatted representations. This Profile specifies a subset of elements from the APP for use in depositing content into information systems, such as repositories. The Profile also specifies a number of element extensions to APP, defined with reference to the extensions mechanism outlined in APP. APP and this profile also draws on the Atom Syndication Format (ATOM).
This profile has been produced to support the work of the JISC-funded SWORD project.
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 (see APP).
SWORD Profile of APP elements
The following section identifies the elements of APP which are implemented by SWORD and those which are not. It also provides additional requirements and recommendations, and identifies SWORD extensions to APP, using elements from other namespaces and elements from the sword namespace.
The section is organised according to the sections of the APP document.
5. Protocol Operations
5.1 Retrieving a Service Document
SWORD supports the use of HTTP GET requests.
GET to Service Document request
In addition, SWORD introduces an additional URL encoded parameter ('onBehalfOf') to specify the username of a target user on whose behalf a deposit is being made.
GET to Service Document onBehalfOf TargetUser
This facilitates the SWORD requirement to support mediated deposits. See also the notes about Authentication below (relating to APP section 14). In this case, the returned Service Document SHOULD identify only those collections to which the target user is able to deposit. If the target repository 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 - NOT USED
5.3 Creating a Resource
SWORD supports the use of HTTP POST
POST to URI of Collection
201 Created Location: Member Entry URI
See further refinements to the SWORD use of HTTP POST in APP Section 9.
5.4 Editing a Resource - NOT USED
5.5 use of HTTP Response Codes
SWORD supports the use of the following HTTP response codes, along with the following human-readable explanations.
{DEFINE CODES USED, RECOMMENDED TEXT}
7. Category Documents - NOT USED
8. Service Documents
In line with APP, a service document (<app:service>) is identified with the "application/atomserv+xml" media type.
8.1 Workspaces
- The SWORD profile adheres fully to the APP definition of a Workspace.
- For this profile, a Workspace is defined as an arbitrary aggregation of collections of resources.
- The SWORD profile specifies that one or more <app:collection> elements SHOULD be present. The absence of any <app:collection> elements implies that the authenticated user does not have permission to deposit.
- The SWORD profile recommends that the <app:accept> element is used to specify accepted media-ranges. It is anticipated that these ranges MAY include application/atomsv+xml, Multipart/Related;type=application/atom+xml and media ranges relating to accepted packaging formats, e.g. application/zip, application/xml.
- The SWORD profile adheres fully to the element definitions identified at 8.3.1, 8.3.2, 8.3.2.1, 8.3.3, 8.3.3.2, 8.3.3.3, 8.3.4. SWORD defines the following extensions to the <app:collection> element:
<dcterms:accrualPolicy> - text/URI <dcterms:abstract> - text/URI <sword:mediation> - true|false <sword:defaultCollection> - true|false <sword:treatment> - text <sword:verbose> - true|false <sword:noOp> - true|false <sword:checksumType> - ID <sword:format> <dc:format> - ID <sword:formatNamespace> - URI <sword:formatSchema> - URI
Consult the SWORD extensions to the APP for further definitions and usage guidelines.
8.3.5 - NOT USED
9. Creating and Editing Resources
9.1 Member URIs
SWORD adheres to APP on Member URIs.
9.2 Creating resources with POST
SWORD specifies two mechanisms for using HTTP POST.
The first is allied to APP and uses a simple 'POST to URI of collection' as outlined by APP in section 9.6, with the optional additional URL encoded parameter of 'onBehalfOf' used to specify the username of a target user on whose behalf a deposit is being made. Where supplied, this SHOULD be included as a parameter of the collection URI, or it MAY be form part of the collection URI (see Deposit example 2).
The second method uses Multipart/Related (RFC2387) to support implementers wishing to supply additional parameters not supported by HTTP header. This method consists of an Atom Entry Document containing additional deposit parameters and a resource packaged in a Multipart/Related MIME structure (see Deposit example 3 and HTTP extensions to SWORD).
Implementers who do not support Multipart/Related SHOULD process the Multipart/Related as Multipart/Mixed.
The atom entry document MAY include any or all of the following extensions.
<atom:source>
<atom:generator> - id of the source repository
<sword:verbose> - true/false
<sword:noOp> - true/false
<sword:checksumType> - ID
<sword:checksum> - checksum
<sword:format>
<dc:format> - ID
Consult the SWORD extensions to the APP for further definitions and usage guidelines.
9.3 Updating Resources with PUT - NOT USED
9.4 Deleting Resources with DELETE - NOT USED
9.5 Caching and entity tags - NOT USED
9.6 Media Resources and Media Link Entries
SWORD uses this mechanism for posting media types other than appliation/atom+xml to a Collection. SWORD also specifies an optional method for using Multipart/Related to post additional parameters along with the binary data. See Section 9.1 and HTTP extensions to SWORD)).
SWORD recommends that the returned Media Link Entry adheres to the APP protocol, with the following additional recommendations:
- The Location: element of the HTTP header MUST contain a URI for the Media Link Entry. This SHOULD be a unique identifier for an Atom Entry Document created for the deposit and returned with the response.
- This Media Link Entry MUST contain an <atom:content> element with a src attribute containing a URI for the deposited Media Resource. It is recommended that this URI derefrences to the location of the deposited package.
- An <atom:link> element SHOULD be supplied with a rel="edit-media" attribute and a href containing a URI for the Media Resource. This MAY be the same as the URI supplied with the <atom:content> element. It is recommended that this URI derefrences to the location of the deposited package.
- An <atom:link> element SHOULD be supplied with a rel="edit" attribute and a href containing a URI for the deposit. This SHOULD be a public splash page or jump-off page, or a users private metadata or workflow management page. It MAY give users future access to an 'unpacked' deposit. If records are queued in a 'pending' workflow, this URI may not yet dereference.
URIs SHOULD be unique and wherever possible SHOULD persist, but this is not a requirement.
The ATOM Entry returned with the HTTP Response MAY contain the following extensions:
<atom:contributor> - mediator name (query - could use dcterms:mediator?)
<atom:source>
<atom:generator> - id of the source repository
<sword:treatment> - text
<sword:verboseDescription> - text
<sword:noOp> - true/false (true = no action has been taken; false = deposit has been made as requested)
<sword:checksumType> - id
<sword:checksum> - checksum
<sword:format>
<dc:format> - id
Consult the SWORD extensions to the APP for further definitions and usage guidelines.
9.7 The Slug: Header
- The SWORD Profile does not require the use of The Slug header. The Slug header MAY be used, but servers MAY choose to ignore the header or alter its value.
10. Listing Collections - Not Used
- APP states that "Collection Resources MUST provide representations in the form of Atom Feed couments 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 APP compliant.
10.1 Collection partial lists - NOT USED
- see notes above - implementers MAY wish to use Collection partial lists.
10.2 The "app:edited" Element - NOT USED
11. Atom Format
The SWORD Profile uses the "edit" and "edit-media" link relations. The SWORD profile does not currently support edits or modification of 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.
It is expected that the edit link URI points to the location of a workflow management page, or jump-off page.
It is expected that the edit-media link URI point to the location of the deposited file.
12. The Atom Format Type Parameter
The SWORD Profile uses the "entry" type parameter.
13. Publishing Controls - NOT USED
14. Securing the Atom Publishing Protocol
The SWORD Profile adheres to the statement: "At a minimum, client and server implementations MUST be capable of being configured to use HTTP Basic Authentication [RFC2617] in conjunction with a TLS connection as specified by [RFC2818]."
It is the responsibility of implementers to integrate existing authentication solutions.
15. Security Considerations
The SWORD Profile recommends implementers refer to this section of APP.
Compliance
SWORD identifies two levels of compliance.
Level 0 requires implementation of a minimal set of mandatory elements as defined [below].
Full level 1 compliance REQUIRES implementation of the full set of extension elements and compliance with APP as indicated by the [SWORD profile of APP] specified in this document.
Partial level 1 compliance REQUIRES implementation of some optional elements specified [below]. This may depend on local requirements. Partial level 1 compliance is identified as 1-part.
Level 0 compliance
Mandatory elements for Level 0 compliance are:
| SWORD parameter | APP element | In |
| Collection ID | <app:collection href=""> (atom uri) | Service Document |
| Deposit Status | HTTP Status Code | HTTP Response |
| Error Code | HTTP Status Code | HTTP Response |
| Error Description | in HTTP Response | HTTP Response |
| Treatment Description | <sword:treatment> extension in Service Document and ATOM Entry | Service Document and |
Level 1 compliance
These elements are mandatory for full level 1 compliance and optional for partial compliance.
| SWORD parameter | APP element / HTTP header | Extension | In |
| onBehalfOf TargetUser | ?onBehalfOf= | parameter of GET and POST | |
| Repository / Collection Name |
<collection> |
Service Document | |
| Repository / Collection Policy |
<dcterms:accrualPolicy> |
Service Document | |
| Collection Description |
<dcterms:abstract> |
Service Document | |
| Default Collection |
<sword:defaultCollection> |
ServiceDocument | |
| Format ID | Content-Type | <dc:format> | POST header (deposit) Atom Entry Document (deposit) |
| Format Accepted | Content-Type | <dc:format> | Service Document Atom Entry Document (response) |
| Format Description | |||
| Format Namespace |
<sword:namespace> |
Service Document | |
| Format Schema |
<sword:schema> |
Service Document | |
| Treatment Description |
<sword:treatment> |
Service Description Atom Entry Document (response) |
|
| Verbose Supported |
<sword:verbose> |
Service Description | |
| NoOp Supported |
<sword:noOp> |
Service Description | |
| Mediation Allowed |
<sword:mediation> |
Service Document | |
| Source Repository |
<atom:source> |
||
| Target Collection | POST to URI of Collection | ||
| Transaction ID |
Content-ID |
POST header (deposit) Atom Entry Document (deposit) |
|
| Verbose |
<sword:verbose> |
Service Document Atom Entry Document (deposit) |
|
| Verbose Description |
<sword:verboseDescription> |
Atom Entry Document (response) | |
| NoOp |
<sword:noOp> |
Service Document Atom Entry Document (deposit) |
|
| Checksum Type | Content-MD5 |
<sword:checksumType> |
POST header (deposit) Atom Entry Document (deposit) |
| Checksum | Content-MD5: md5-digest |
<sword:checksum> |
|
| Target Owner | <atom:author> | ?onBehalfOf= | Deposit POST |
| Identier (URI) |
<atom:content type="" src=""> |
Atom Entry Document (response) HTTP header (response> |
|
| Object URI |
<atom:link rel="edit-media" href""> |
Atom Entry Document (response) | |
| Display URI | <atom:link rel="edit" href""> | Atom Entry Document (response) |
SWORD Extensions to the APP
This section defines SWORD extensions to the APP, as used in this document.
Element extensions
SWORD defines the use of additional elements, as follows:
| Element | Namespace | APP / ATOM extension point | Usage notes |
| <dcterms:accrualPolicy> |
http://purl.org/dc/terms/ | <app:collection> (Service Document) | Use for a human-readable repository or collection
policy. Include either a text description or a URI. |
| <dcterms:abstract> | http://purl.org/dc/terms/ | <app:collection> (Service Document) | Use for a human-readable repository or collection description. Include either a text description or a URI. |
| <sword:mediation> | <app:collection> (Service Document) | Use to indicate if mediated deposit is allowed on the
defined collection. |
|
| <sword:defaultCollection> | <app:collection> (Service Document) | Use to indicate a default collection where multiple
collections are listed. If only one collection is specified
in the Service Document, this is assumed to be the default collection. |
|
| <sword:treatment> | <app:collection> (Service Document) | Use for a human-readable statement about what treatment
the deposited resource will receive. Include either a text description or a URI. |
|
| <sword:treatment> | <atom:entry> (Atom Entry Document (response)) | Use for a human-readable statement about what treatment
the deposited resource has received. Include either a text description or a URI. |
|
| <sword:verbose> | <app:collection> (Service Document) | Use to indicate if verbose descriptions are supported.
This extension is intended for use by developers for testing
implentation. |
|
| <sword:verbose> | <atom:entry> (Atom Entry
Document (deposit)) |
Use to request a verbose description with the response.
This extension
is intended for use by developers for testing implentation. |
|
| <sword:verboseDescription> | <atom:entry> (Atom Entry
Document (response)) |
Use to supply a verbose descriptions are supported.
This extension
is intended for use by developers for testing implentation.
Include either a text description or a URI. |
|
| <sword:noOp> | <app:collection> (Service Document) | Use 'true' to indicate if the server supports the noOp
facility. This extension
is intended for use by developers for testing implentation. |
|
| <sword:noOp> | <atom:entry> (Atom Entry
Document (deposit)) |
Use 'true' to indicate if the server should take no
action on receipt of this deposit. This extension
is intended for use by developers for testing implentation. |
|
| <sword:noOp> | <atom:entry> (Atom Entry
Document (response)) |
Use 'true' to indicate that the server has taken no
action on receipt of this deposit. This extension
is intended for use by developers for testing implentation. |
|
| <sword:checksumType> | <app:collection> (Service Document) | Use to supply an identifier for the checksum type
supported by the server. Absense of a checksumType indicates that checksums are not supported. |
|
| <sword:checksumType> | <atom:entry> (Atom Entry Document (deposit)) | Use to supply an identifier for the checksum type supplied with the deposit. | |
| <sword:checksumType> | Atom Entry Document (response) | Use to supply an identifier for the checksum type handled by the server. | |
| <sword:checksum> | <atom:entry> (Atom Entry Document (deposit) and Atom Entry Document (response)) | Use to supply a checksum with the deposit and to supply the checksum handled by the server in the response. | |
| <sword:format> | <app:collection> (Service Document) <atom:entry> (Atom Entry Document (deposit) and Atom Entry Document (response)) |
Wrapper for additional format elements. | |
| <dc:format> | http://purl.org/dc/terms/ | <app:collection> (Service Document) <atom:entry> (Atom Entry Document (deposit) and Atom Entry Document (response)) |
Used for an identifier for the particular packaging format supported, supplied or handled. |
| <sword:formatNamespace> | <app:collection> (Service Document) | Used to supply a URI for the format namespace. | |
| <sword:formatScema> | <app:collection> (Service Document) | Used to supply a URI for the format schema. | |
| <sword:level> | http://purl.org/sword/ | <app:service> (Service Document) | Used to indicate the compliance level supported by the
server. |
HTTP extensions
SWORD specifies the use of additional HTTP parameters, as follows:
- Content-Type: Multipart/Related SHOULD be used with level 1 compliant deposits to supply additional SWORD elements.
- The type parameter MUST be specified. Its value is the MIME media type of the "root" body part, which is taken to be the Atom Entry Document (application/atom+xml).
- The start parameter MAY be used to supply the content-ID of the compound object's "root". If not supplied, the default root is the first body part within the Multipart/Related body.
- Content-ID: MAY be used with Multipart/Related to supply a transaction id for the deposit. This SHOULD be the same as the <atom:id> supplied within the Atom Entry Document (deposit).
- Content-Transfer-Encoding: MAY be used to indicate the encoding of the resource.
- Content-MD5: MAY used to supply an md5-digest
Examples
Retrieve Service Document
GET to Service Document (simple user)
http://www.myrepository.ac.uk/atom/servicedocument
GET to Service Document onBehalfOf TargetUser (mediated user)
http://www.myrepository.ac.uk/atom/servicedocument?onBehalfOf=lcarr
Service Document
Example 1: level 0
<?xml version="1.0" encoding='utf-8'?> <service xmlns="http://purl.org/atom/app#" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/sword/"> <sword:level>0</sword:level> <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> </collection> </workspace> </service>
Example 2: level 1
<?xml version="1.0" encoding='utf-8'?> <service xmlns="http://purl.org/atom/app#" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/sword/" xmlns:dcterms="http://purl.org/dc/terms/"> <sword:level>1</sword:level> <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> <app:accept>application/xml, application/zip, application/atom+xml, Multipart/Related;type=application/atom+xml</app:accept> <dcterms:accrualPolicy>Collection Policy</dcterms:accrualPolicy> <dcterms:abstract>Collection description</dcterms:abstract> <sword:mediation>true</sword:mediation> <sword:defaultCollection>true</sword:defaultcollection> <sword:treatment>Treatment description</sword:treatment> <sword:format> <dc:format>agreed format identifier</dc:format> <sword:schema>uri</sword:schema> <sword:namespace>uri</sword:namespace> </sword:format> <sword:verbose>true</sword:verboseSupport> <sword:noOp>true</sword:noOpSupport> <sword:checksumType>mD5</sword:checksumType> </collection> </workspace> </service>
Deposit
Example 1: POST binary (level 0)
http://www.myrepository.ac.uk/atom/geography-collection
POST /geography-collection/ HTTP/1.1 Host: www.myrepository.ac.uk/atom Content-Type: application/zip Content-Length: nnn ...binary data...
Example 2: POST binary (level 1-part, mediated user)
mediated user (preferred) - http://www.myrepository.ac.uk/atom/geography-collection?onBehalfOf=lcarr mediated user (alternative) - http://www.myrepository.ac.uk/atom/geography-collection/lcarr mediated user (alternative) - http://www.myrepository.ac.uk/atom/users/lcarr/geography-collection
POST /geography-collection?onBehalfOf=lcarr HTTP/1.1 Host: www.myrepository.ac.uk/atom Content-Type: application/zip Slug: My Deposit Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Length: nnn ...binary data...
Example 3: POST multipart (level 1, mediated user)
POST /geography-collection?onBehalfOf=lcarr HTTP/1.1
Host: www.myrepository.ac.uk/atom
Content-Type: Multipart/Related; type=application/atom+xml;
start="deposit-id"; boundary="deposit"
Slug: My Deposit
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
Content-MD5: md5-digest
--deposit
Content-Type: application/atom+xml
Content-ID: deposit-id
<?xml version=2.0"?>
<entry xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<author><name>Les Carr</name></author>
<id>deposit-id</id>
<contributor><name>Martin Morrey</name></contributor>
<source>
<generator>Repository id</generator>
</source>
<sword:verbose>true</sword:verbose>
<sword:noOp>true</<sword:noOp>
<sword:checksumType>MD5</sword:checksumType>
<sword:checksum>xxxxxxxxxxxxxx<sword:checksum>
<sword:format>
<dc:format>Format ID</dc:format>
</sword:format>
</entry>
--deposit
Content-Type: application/zip
Content-ID: filename
Content-Transfer-Encoding: binary
...binary data...
--deposit--
Response
Example 1: level 0 response
HTTP/1.1 201 Created Date: Mon, 14 May 2007 14:27:11 GMT Content-Length: nnn Content-Type: application/atom+xml; charset="utf-8" Location: http://www.myrepository.ac.uk/collection/edit/my_deposit.atom
<?xml version="1.0"?> <entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/sword/" xmlns:dcterms="http://purl.org/dc/terms/"> <title>My Deposit</title> <id>deposit-id</id> <updated>2007-05-14T14:27:08Z</updated> <author><name>Les Carr</name></author> <summary type="text" /> <content type="application/zip" src="http://www.myrepository.ac.uk/my_deposit.zip"/> <link rel="edit-media" href="http://www.myrepository.ac.uk/my_deposit.zip" /> <link rel="edit" href="http://www.myrepository.ac.uk/lcarr/workflow/my_deposit.atom" /> <sword:treatment>Treatment description</sword:treatment> </entry>
Example 2: level 1-part response
HTTP/1.1 201 Created Date: Mon, 14 May 2007 14:27:11 GMT Content-Length: nnn Content-Type: application/atom+xml; charset="utf-8" Location: http://www.myrepository.ac.uk/collection/edit/my_deposit.atom
<?xml version="1.0"?> <entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/sword/"> <title>My Deposit</title> <id>deposit-id</id> <updated>2007-05-14T14:27:08Z</updated> <author><name>Les Carr</name></author> <summary type="text" /> <content type="application/zip" src="http://www.myrepository.ac.uk/my_deposit.zip"/> <link rel="edit-media" href="http://www.myrepository.ac.uk/my_deposit.zip" /> <link rel="edit" href="http://www.myrepository.ac.uk/lcarr/workflow/my_deposit.atom" /> <contributor><name>Martin Morrey</name></contributor> <source> <generator>Repository id</generator> </source> <sword:treatment>Treatment description</sword:treatment> </entry>
Example 3: level 1 response
HTTP/1.1 201 Created Date: Mon, 14 May 2007 14:27:11 GMT Content-Length: nnn Content-Type: application/atom+xml; charset="utf-8" Content-MD5: md5-digest Location: http://www.myrepository.ac.uk/collection/edit/my_deposit.atom
<?xml version="1.0"?> <entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/sword/" xmlns:dcterms="http://purl.org/dc/terms/"> <title>My Deposit</title> <id>deposit-id</id> <updated>2007-05-14T14:27:08Z</updated> <author><name>Les Carr</name></author> <summary type="text" /> <content type="application/zip" src="http://www.myrepository.ac.uk/my_deposit.zip"/> <link rel="edit-media" href="http://www.myrepository.ac.uk/my_deposit.zip" /> <link rel="edit" href="http://www.myrepository.ac.uk/lcarr/workflow/my_deposit.atom" /> <contributor><name>Martin Morrey</name></contributor> <source> <generator>Repository id</generator> </source> <sword:treatment>Treatment description</sword:treatment> <sword:verboseDescription>description</sword:verboseDescription> <sword:noOp>true</<sword:noOp> <sword:checksumType>MD5</sword:checksumType> <sword:checksum>md5-digest<sword:checksum> <sword:format> <dc:format>Format ID</dc:format> </sword:format> </entry>
References
Nottingham, M. and R. Sayre, "The Atom Syndication Format", RFC 4287, December 2005. [RFC4287]. http://www.ietf.org/rfc/rfc4287.txt (see also html version at http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html)
Gregario, J. and B. de hOra, "The Atom Publishing Protocol", Internet Draft, March 2007. http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-14.txt (see also html version at http://atompub.org/rfc4287.html)
Levinson, E., "The MIME Multipart/Related Content-type", RFC2387. http://www.ietf.org/rfc/rfc2387.txt
