SWORD APP Profile 0.1

From DigiRepWiki

SWORD Home | SWORD Wiki | SWORD Project Background


This profile has been replaced by the most recent version: http://purl.org/net/sword/


Contents

[edit]

SWORD Profile of the Atom Publishing Protocol

Version 0.1

[edit]

Introduction

This document is a profile of the Atom Publishing Protocol (APP) - an application-level protocol for publishing and editing Web resources. The APP is based on HTTP transfer of Atom-formatted representations. The 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 in-line with the extensions mechanism outlined in APP. APP also draws on the Atom Syndication Format (ATOM).

[edit]

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

[edit]

Compliance

SWORD identifies two levels of compliance, Level 0 requires implementation of a minimal set of mandatory elements. Full level 1 compliance requires implementation of the full set of elements outlined below, and compliance with APP where incated by the following profile. Partial level 1 compliance is also possible and is identified as 1-part. For partial compliance, implentations MUST implement beyond the mandatory elements required for Level 0, but are not REQUIRED to implement all of the elements specified for Level 1 compliance.

Levels:

  • 0
  • 1-part
  • 1
[edit]

Terminology

The following list of SWORD terms equate to the following APP terms

SWORD terminology APP Terminology
Explain Request GET to Service Document
Explain Response Service Document
Deposit POST to Collection URI
Receipt HTTP Response and ATOM entry document
[edit]

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 APP document

[edit]

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

5.4 Editing a Resource - NOT USED

5.5 use of HTTP Response Codes

{DEFINE CODES USED, RECOMMENDED TEXT}

[edit]

7. Category Documents - NOT USED

[edit]

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 will be used to specify accepted packaging formats.
  • 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, with 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:testing>
	<sword:verboseSupported> - true|false
	<noOpSupport> - true|false
<sword:checksumType> - id
<sword:format>
	<dc:format> - id
	<sword:formatNamespace> - uri
	<sword:formatSchema> - uri

8.3.5 - NOT USED

[edit]

9. Creating and Editing Resources

9.1 Member URIs

SWORD is in line with APP on Member URIs.

9.2 Creating resources with POST

SWORD is in line with APP on using POST to add new resources.

In addition, SWORD introduces an additional parameter ('onBehalfOf') to specify the username of a target user on whose behalf a deposit is being made.

{INVESTIGATE HOW VERBOSE, NOOP, CHECKSUM and FORMAT MIGHT APPEAR IN HTTP HEADER}

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 utilises this mechanism for posting media types other than appliation/atom+xml to a Collection. The limitation of this method is that information outside of the posted object can only be transported through the HTTP header, e.g. any request to the server about what it does with the posted object.

SWORD recommends that the returned Media Link Entry adheres to the APP protocol, with the following additional recommendations:

{NEED TO ADD RECOMMENDATIONS ABOUT USE OF LINKS and what they identify}

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:testing>
	<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>
<sword:format>
	<dc:format> - id

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

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 at 10, implementors MAY wish to use Collection partial lists.

10.2 The "app:edited" Element - NOT USED

[edit]

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 MAY be editable, but is not required to be editable.

It is expected that the edit link URI points to the location of a workflow management page, or similar jump-off page.

It is expected that the edit-media link URI points to the location of the deposited file. This location is not required to NOT persist beyond the return of receipt to the client.

[edit]

12. The Atom Format Type Parameter

The SWORD Profile uses the "entry" type parameter.

[edit]

13. Publishing Controls - NOT USED

[edit]

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.

[edit]

15. Security Considerations

The SWORD Profile recommends implementers refer to this section of APP.

[edit]

Level 0 compliance

Mandatory elements for Level 0 compliance are:

SWORD parameter APP element In
Collection ID ATOM URI as href in <app:collection> <app:collection> element </app:collection> 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

ATOM Media Entry
[edit]

Level 1 compliance

to add.

[edit]

Examples

[edit]

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
[edit]

Service Document 

<?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://example.org/reilly/main" >
     <atom:title>My Blog Entries</atom:title>
     <app:accept>text/xml,application/zip</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:testing>
         <sword:verboseSupport>true</sword:verboseSupport>
         <sword:noOpSupport>true</sword:noOpSupport>  
     </sword:testing>
     <sword:checksumType>mD5</sword:checksumType>
   </collection>
 </workspace>
</service>
[edit]

Deposit

POST binary (simple user) 

http://www.myrepository.ac.uk/atom/geography-collection

POST binary (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 /collection/ HTTP/1.1
   Host: www.myrepository.ac.uk
   Content-Type: application/zip
   Slug: My Deposit
   Authorization: Basic ZGFmZnk6c2VjZXJldA==
   Content-Length: nnn

{ADD onBehalfOf ?} {EXTENSIONS? SEE NOTE ABOVE} 

   ...binary data...
[edit]

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

{REFLECT POST HTTP PARAMETERS?} 

   <?xml version="1.0"?>
   <entry xmlns="http://www.w3.org/2005/Atom">
     <title>My Deposit</title>
     <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
     <updated>2007-05-14T14:27:08Z</updated>
     <author><name>Les Carr</name></author>
     <summary type="text" />
     <content type="application/zip"
        src="http://collection.myrepository.ac.uk/my_deposit.zip"/>
     <link rel="edit-media"
        href="http://collection.myrepository.ac.uk/edit/my_deposit.zip" />
     <link rel="edit"
        href="http://www.myrepository.ac.uk/collection/edit/my_deposit.atom" />
     <contributor><name>Martin Morrey</name></contributor>
     <source>
          <generator>Repository id</generator>
     </source>
     <sword:treatment>Treatment description</sword:treatment>
     <sword:testing>
	  <sword:verboseDescription></sword:verboseDescription>
          <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>
[edit]

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)

Retrieved from "/repositories/digirep/index/SWORD_APP_Profile_0.1.html"