Menu
▾
▴
[sword-app-tech] SWORD 1.3
|
From: Jim D. <oj...@ca...> - 2008-08-25 16:44:51
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>SWORD APP Profile version 1.3</title>
<style type="text/css" title="Xml2Rfc (sans serif)">
a {
text-decoration: none;
}
a.smpl {
color: black;
}
a:hover {
text-decoration: underline;
}
a:active {
text-decoration: underline;
}
address {
margin-top: 1em;
margin-left: 2em;
font-style: normal;
}
body, table td, table th {
color: black;
font-family: verdana, helvetica, arial, sans-serif;
font-size: 10pt;
}
cite {
font-style: normal;
}
dd {
margin-right: 2em;
}
dl {
margin-left: 2em;
}
dl.empty dd {
margin-top: .5em;
}
dl p {
margin-left: 0em;
}
dt {
margin-top: .5em;
}
h1 {
font-size: 14pt;
line-height: 21pt;
page-break-after: avoid;
}
h1.np {
page-break-before: always;
}
h1 a {
color: #333333;
}
h2 {
font-size: 12pt;
line-height: 15pt;
page-break-after: avoid;
}
h2 a {
color: black;
}
h3 {
font-size: 10pt;
page-break-after: avoid;
}
h3 a {
color: black;
}
h4 {
font-size: 10pt;
page-break-after: avoid;
}
h4 a {
color: black;
}
h5 {
font-size: 10pt;
page-break-after: avoid;
}
h5 a {
color: black;
}
img {
margin-left: 3em;
}
li {
margin-left: 2em;
margin-right: 2em;
}
ol {
margin-left: 2em;
margin-right: 2em;
}
ol p {
margin-left: 0em;
}
p {
margin-left: 2em;
margin-right: 2em;
}
pre {
margin-left: 3em;
background-color: lightyellow;
padding: .25em;
}
pre.text2 {
border-style: dotted;
border-width: 1px;
background-color: #f0f0f0;
width: 69em;
}
pre.inline {
background-color: white;
padding: 0em;
}
pre.text {
border-style: dotted;
border-width: 1px;
background-color: #f8f8f8;
width: 69em;
}
pre.drawing {
border-style: solid;
border-width: 1px;
background-color: #f8f8f8;
padding: 2em;
}
table {
margin-left: 2em;
}
table.header {
width: 95%;
font-size: 10pt;
color: white;
}
td.top {
vertical-align: top;
}
td.topnowrap {
vertical-align: top;
white-space: nowrap;
}
td.header {
background-color: gray;
width: 50%;
}
td.reference {
vertical-align: top;
white-space: nowrap;
padding-right: 1em;
}
thead {
display:table-header-group;
}
ul.toc {
list-style: none;
margin-left: 1.5em;
margin-right: 0em;
padding-left: 0em;
}
li.tocline0 {
line-height: 150%;
font-weight: bold;
font-size: 10pt;
margin-left: 0em;
margin-right: 0em;
}
li.tocline1 {
line-height: normal;
font-weight: normal;
font-size: 9pt;
margin-left: 0em;
margin-right: 0em;
}
li.tocline2 {
font-size: 0pt;
}
ul p {
margin-left: 0em;
}
ul.ind {
list-style: none;
margin-left: 1.5em;
margin-right: 0em;
padding-left: 0em;
}
li.indline0 {
font-weight: bold;
line-height: 200%;
margin-left: 0em;
margin-right: 0em;
}
li.indline1 {
font-weight: normal;
line-height: 150%;
margin-left: 0em;
margin-right: 0em;
}
.bcp14 {
font-style: normal;
text-transform: lowercase;
font-variant: small-caps;
}
.comment {
background-color: yellow;
}
.center {
text-align: center;
}
.error {
color: red;
font-style: italic;
font-weight: bold;
}
.figure {
font-weight: bold;
text-align: center;
font-size: 9pt;
}
.filename {
color: #333333;
font-weight: bold;
font-size: 12pt;
line-height: 21pt;
text-align: center;
}
.fn {
font-weight: bold;
}
.hidden {
display: none;
}
.left {
text-align: left;
}
.right {
text-align: right;
}
.title {
color: #990000;
font-size: 18pt;
line-height: 18pt;
font-weight: bold;
text-align: center;
margin-top: 36pt;
}
.vcardline {
display: block;
}
.warning {
font-size: 14pt;
background-color: yellow;
}
@media print {
.noprint {
display: none;
}
a {
color: black;
text-decoration: none;
}
table.header {
width: 90%;
}
td.header {
width: 50%;
color: black;
background-color: white;
vertical-align: top;
font-size: 12pt;
}
ul.toc a::after {
content: leader('.') target-counter(attr(href), page);
}
a.iref {
content: target-counter(attr(href), page);
}
.print2col {
column-count: 2;
-moz-column-count: 2;
column-fill: auto;
}
}
@page {
@top-left {
content: "RFC 5023";
}
@top-right {
content: "October 2007";
}
@top-center {
content: "The Atom Publishing Protocol";
}
@bottom-left {
content: "Gregorio & de hOra";
}
@bottom-center {
content: "Standards Track";
}
@bottom-right {
content: "[Page " counter(page) "]";
}
}
@page:first {
@top-left {
content: normal;
}
@top-right {
content: normal;
}
@top-center {
content: normal;
}
}
</style>
</head>
<body>
<h1>SWORD AtomPub Profile version 1.3</h1>
<h2>Simple Webservice Offering Repository Deposit</h2>
<h3>Change control</h3>
<dl>
<dt>Version 1.3, published XXXX</dt>
<dd>Revised deviations from RFC XXX. Changed references to APP to refer
to AtomPub. Restructured document to include description of SWORD
specific extensions before comparison with AtomPub. Removed notion of
levels of compliance. Removed section on Slug headers; it didn't add
anything over Atom.</dd>
<dt>Version 1.2, created 22nd January 2008, revised 22 February
2008.</dt>
<dd>Changes from Version 1.1: corrections to namespaces used in
examples.</dd>
</dl>
<h3>Editors:</h3>
<ul>
<li>Julie Allinson (UKOLN/Univerity of York)</li>
<li>Les Carr (University of Southampton)</li>
<li>Jim Downing (University of Cambridge)</li>
<li>David F. Flanders (The Bloomsbury Colleges)</li>
<li>Sebastien Francois (University of Southampton)</li>
<li>Richard Jones (Imperial College London)</li>
<li>Stuart Lewis (University of Aberystwyth)</li>
<li>Martin Morrey (Intrallect Ltd.)</li>
<li>Glen Robson (National Library of Wales)</li>
<li>Neil Taylor (University of Aberystwyth)</li>
</ul>
<h1>Introduction</h1>
<p>The Atom Publishing Protocol (AtomPub [RFC5023]) provides a simple,
extensible mechanism for the creation of Web Resources. The SWORD profile builds
upon AtomPub, providing a set of extensions and constraint relaxations and
enforcements of use when: -</p>
<ul>
<li>Clients wish to create resources by sending compound
resources, such as archive files (tar, zip).</li>
<li>Both non-interactive and 3rd party mediated operation are
required.</li>
<li>A common server behaviour is for deposited resources to go
through a workflow involving manual stages, before becoming available
on the web.</li>
</ul>
<p>Whilst it is possible to implement generic SWORD compliant clients and
servers, the SWORD profile aims to provide a framework around which specific
deposit systems can be built consistently and efficiently.</p>
<p>The SWORD profile relaxes a number of constraints of AtomPub, and adds a
number of elements. It avoids overloading the elements of or changing the
semantics of AtomPub. Consequently, SWORD compliance does not preclude AtomPub
compliance; implementers wishing to support additional elements of AtomPub, such
as update (PUT), DELETE, categories or POSTing Atom [ATOM] documents are
free to do so. The section on Compliance explains the differences between
AtomPub and SWORD in more detail.</p>
<h1>Document conventions</h1>
<p>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.</p>
<h1>Document Structure</h1>
<p>The first part of this document describe the mechanisms that the SWORD
profile adds to AtomPub. The second part follows the structure and numbering of
the AtomPub specification, highlighting the ways in which the SWORD profile
diverges from AtomPub. The final part summarizes the SWORD extensions, their
application and level of requirement.</p>
<h2>SWORD Namespace</h2>
<p>All SWORD extensions are defined within the namespace:</p>
<pre>http://purl.org/net/sword/</pre>
<p>This specification uses the prefix "sword:" for the namespace name. The
prefix "app:" is used for "http://www.w3.org/2007/app" (the namespace name of
the Atom Publishing Protocol [AtomPub]), and the prefix "atom:" is used for
"http://www.w3.org/2005/Atom" (the namespace name of the Atom Syndication Format
[ATOM]). These namespace prefixes are not semantically significant.</p>
<h1>Part A: SWORD features</h1>
<h2>1 Package support</h2>
<p>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.</p>
<h3>1.1 Package support in Service description</h3>
<p>To this end, SWORD extends AtomPub, adding the sword:formatNamespace element,
which is used in a similar fashion to app:accept elements inside a
app:collection element within a Service Document to indicate that a SWORD
collection will accept deposits of a particular packaging format. The value
SHOULD be a URI taken from the enumeration in SWORD Content Package Types
[SWORD-TYPES]. </p>
<pre><?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<sword:version>1.3</sword:version>
<workspace>
<atom:title>Main Site</atom:title>
<collection
href="http://www.myrepository.ac.uk/atom/geography-collection" >
<atom:title>My Repository : Geography Collection</atom:title>
<accept>application/zip</accept>
<sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
<dcterms:abstract>Collection description</dcterms:abstract>
<b><sword:formatNamespace>http://purl.org/net/sword-types/bagit</sword:formatNamespace></b>
</collection>
</workspace>
</service>
</pre>
<p>TODO Do we need a feature to allow servers to express a preferred
formatNamespace and / or an order of preference? (Particularly requested by
Pablo at MS)</p>
<h3>1.2 Package support during resource creation</h3>
<p>When creating Media Resources (see Part B section 9), the client SHOULD
indicate the archive file MIME type using the HTTP "Content-Type" header, and
SHOULD also give information about content packaging using the
X-Format-Namespace HTTP header. This can take values from the list enumerated in
[SWORD-TYPES] and SHOULD match one of values the server has advertised as
acceptable for the collection in the manner described above.</p>
<p>If a server receives a POST with an unacceptable X-Format-Namespace value, it
SHOULD reject the POST by returning an HTTP wth a status code of 400 (Bad
request). </p>
<h3>1.3 Package description in entry documents</h3>
<p>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:formatNamespace elements to the entry.</p>
<h3>1.4 Example</h3>
<pre>
POST /geography-collection HTTP/1.1
Host: www.myrepository.ac.uk
Content-Type: application/zip
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
Content-MD5: [md5-digest]
Content-Disposition: filename=myDSpaceMETSItem.zip
<b>X-Format-Namespace: http://purl.org/net/sword-types/mets/dspace</b>
</pre>
<pre> HTTP/1.1 201 Created
Date: Mon, 18 August 2008 14:27:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset="utf-8"
Location: http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
<title>My Deposit</title>
<id>info:something:1</id>
<updated>2008-08-18T14:27:08Z</updated>
<author><name>jbloggs</name></author>
<summary type="text">A summary</summary>
<content type="application/zip"
src="http://www.myrepository.ac.uk/geography-collection/deposit1.zip"/>
<b><sword:formatNamespace>http://purl.org/net/sword-types/mets/dspace</sword:formatNamespace></b>
<link rel="edit"
href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" />
</entry>
</pre>
<h2>2 Mediated Deposit</h2>
<p>In a number of situations the authenticated user using a SWORD client is not
the owner of the deposited resource. SWORD provides a way of representing this
usage by allowing clients to set a HTTP header field X-On-Behalf-Of which, if
present SHOULD contain a user principle for the owner of the resource. This
mediation technique 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.</p>
<p>It is also possible to use the SWORD mediation mechanism for situations such
as non-interactive batch deposit in which the authenticated user is a software
acting on behalf of a user, although it is noted that OAuth [OAUTH] provides
a more secure approach to this problem and should be preferred by
implementers.</p>
<h3>2.1 Mediation In Service Description</h3>
<p>SWORD servers SHOULD indicate whether they support mediated deposit by
including a sword:mediation element containing a text element of either "true"
or "false" in app:collection elements in Service Documents (see Part B, section 8).</p>
<p>Clients SHOULD use the X-On-Behalf-Of header when retrieving Service
Documents if they intend to use the feature for resource creation. Servers MAY
use this header information along with authentication and any other information
in constructing the Service Document representation returned. For example, the
server might include only collections to which the X-On-Behalf-Of can
deposit.</p>
<pre>
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/"
xmlns:dcterms="http://purl.org/dc/terms/">
<sword:level>1</sword:level>
<sword:verbose>true</sword:verbose>
<sword:noOp>true</sword:noOp>
<workspace>
<atom:title>Main Site</atom:title>
<collection
href="http://www.myrepository.ac.uk/atom/geography-collection" >
<atom:title>My Repository : Geography Collection</atom:title>
<accept>application/xml</accept>
<accept>application/zip</accept>
<accept>application/atom+xml</accept>
<sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
<dcterms:abstract>Collection description</dcterms:abstract>
<b><sword:mediation>true</sword:mediation></b>
<sword:treatment>treatment description</sword:treatment>
<sword:formatNamespace>http://purl.org/net/sword-types/bagit</sword:formatNamespace>
</collection>
</workspace>
</service>
</pre>
<h3>2.2 Metadata Interractions In Mediated Deposit</h3>
<p>In all cases (mediated or not) where a user has authenticated to make a
deposit, servers SHOULD use the user's identity for the value of the atom:author
element of the Media Entry Document. In mediated deposit, the value given in the
X-On-Behalf-Of header SHOULD be used for the value of the atom:contributor
element.</p>
<h3>2.3 Example</h3>
<p>In this example, user 'jbloggs' is making a deposit on behalf of user 'fdibner'.</p>
<pre>
POST /app/geography-collection HTTP/1.1
Host: www.myrepository.ac.uk
Content-Type: application/zip
<b>Authorization: Basic [digested auth information for 'jbloggs']</b>
Content-Length: nnn
<b>X-On-Behalf-Of: fdibner </b>
[zipped data]
</pre>
<pre>
HTTP/1.1 201 Created
Date: Mon, 18 August 2008 14:27:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset="utf-8"
Location: http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
<title>My Deposit</title>
<id>info:something:1</id>
<updated>2008-08-18T14:27:08Z</updated>
<b><author><name>jbloggs</name></author></b>
<summary type="text">A summary</summary>
<b><!-- In this case, the package has been placed on the workbench of the On-Behalf-Of user -->
<content type="text/html"
src="http://www.myrepository.ac.uk/fdibner/workbench/my_deposit"/></b>
<link rel="edit-media"
href="http://www.myrepository.ac.uk/geography/my_deposit.zip"/>
<link rel="edit"
href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" />
<b><contributor><name>fdibner</name></contributor></b>
<source>
<generator uri="http://www.example.org/sword-client" version="1.0">
Example.org's SWORD client</generator>
</source>
<sword:treatment>Treatment description</sword:treatment>
</entry>
</pre>
<h2>3 Developer Features</h2>
<p>One of the aims of SWORD is to lower the cost of implementing and
configuring clients and servers against each other. To this end, SWORD
includes some recommended extensions to ease development.</p>
<h3>3.1 No-Op (Dry Run)</h3>
<p>This extension allows clients to test a server's implementation without
actually creating a resource, by including X-No-Op HTTP header with a value of
'true' in a deposit POST. Servers MUST recognise this header and either handle
the POST as a simulated deposit without creating a resource, or else return a
status code of 400 Bad Request (TODO - Is 412 Precondition Failed appropriate
here?) to indicate that they do not support this extension. When a server judges
that the dry run would have proceeded successfully, it SHOULD return a status
code of 200 Successful and include the Atom Entry Document it would have created
in the response. The response SHOULD NOT include a Location header. Servers MAY
indicate whether they support this feature by including a sword:noOp element
with a value of 'true' or 'false' in Service Document representations.</p>
<h3>3.2 Verbose Output</h3>
<p>Servers can also support developers by providing detailed logging output on
actions taken, flow control conditions etc. Clients MAY request such detailed
output by sending an HTTP header X-Verbose with a value of 'true' with a deposit
POST. Servers MAY advertise whether they support such detailed output by
including a sword:verbose element containing a text node with value 'true' or
'false'. If a server has advertised support for verbose output and a client
requests it using the X-Verbose header, the server SHOULD add a
sword:verboseDescription element in Atom Entry document representations for the
deposit.</p>
<h3>Development Features Example</h3>
<pre>POST /app/geography-collection HTTP/1.1
Host: www.myrepository.ac.uk
Content-Type: application/zip
Authorization: Basic [digested auth information for 'jbloggs']
Content-Length: nnn
<b>X-No-Op: true</b>
<b>X-Verbose: true</b>
[zipped data]
</pre>
<pre><b>HTTP/1.1 200 Created</b>
Date: Mon, 18 August 2008 14:27:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset="utf-8"
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
<b><sword:noOp>true</sword:noOp></b>
<b><sword:verboseDescription>
Does collection exist? True.
User authenticates? True.
User: jbloggs
User has rights to collection? True.
</sword:verboseDescription></b>
<title>My Deposit</title>
<id>info:something:1</id>
<updated>2008-08-18T14:27:08Z</updated>
<author><name>jbloggs</name></author>
<summary type="text">A summary</summary>
<content type="text/html"
src="http://www.myrepository.ac.uk/fdibner/workbench/dummy_deposit"/>
<link rel="edit-media"
href="http://www.myrepository.ac.uk/geography/dummy_deposit.zip"/>
<link rel="edit"
href="http://www.myrepository.ac.uk/geography-collection/atom/dummy_deposit.atom" />
<source>
<generator uri="http://www.example.org/sword-client" version="1.0">
Example.org's SWORD client</generator>
</source>
<sword:treatment>Unpacked. JPEG contents converted to JPEG2000.</sword:treatment>
</entry>
</pre>
<h2>4 Auto-discovery</h2>
<p>AtomPub makes no recommendations on the discovery of Service Documents. SWORD
RECOMMENDS that server implementations use an <html:link rel="sword"
href="[Service Document URL]"/> element in the head of a relevant HTML
document to assist with service discovery.</p>
<h1>Part B: SWORD Profile of AtomPub</h1>
<p>This section is organised according to the sections of the AtomPub [AtomPub]
document, highlighting where SWORD varies from AtomPub. If an AtomPub section or
feature is omitted, implementations MUST behave as defined in AtomPub.</p>
<h2>5. Protocol Operations</h2>
<h3>5.1 Retrieving a Service Document</h3>
<pre>GET to Service Document</pre>
<p>In addition, SWORD defines an additional HTTP header X-On-Behalf-Of
used to specify the username of a target user on whose behalf a deposit
is being made.</p>
<pre>
GET to Service Document
X-On-Behalf-Of: [on-behalf-of-user]</pre>
<p>This facilitates the SWORD requirement to support mediated deposits. See also
the notes about Authentication below (relating to AtomPub section 14). When a
server that supports mediated deposit receives an X-On-Behalf-Of
header, the returned Service Document SHOULD identify only those collections to
which the combination of mediated user and authenticated user might successfully
deposit. If the target server does not support mediated deposit, the returned
Service Document SHOULD contain a sword:mediation extension
element with a value of false.</p>
<h3>5.2 Listing Collections</h3>
<p>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. </p>
<h3>5.3 Creating a Resource</h3>
<p>SWORD supports the use of HTTP POST.</p>
<pre>POST [URI of Collection]
[Request entity]</pre>
<pre>201 Created
Location: [Member Entry URI]
[Optional Atom Entry document]</pre>
<p>See further refinements to the SWORD use of HTTP POST in Section 9. </p>
<h3>5.4 Editing a Resource</h3>
<p>The SWORD profile does not require support for the AtomPub mechanisms for
modification of resources once created. </p>
<h3>5.5 Use of HTTP Response Codes</h3>
<p>SWORD builds on the use of response codes specified in [AtomPub], by
mandating the use of certain codes as described in the list below. As per HTTP,
it is RECOMMENDED that a human-readable explanation is supplied along with any
HTTP response code.</p>
<ul>
<li>200 OK Used in response to successful GET operations and to Media
Resource Creation operations where X-No-Op is set to true and the server
supports this header.</li>
<li>201 Created, 202 Accepted - One of these MUST be used to indicate
that a deposit was successful. 202 Accepted is used when processing of
the data is not yet complete.</li>
<li>400 Bad Request - used to indicate that there is some problem with
the request where there is no more appropriate 4xx code. </li>
<li>401 Unauthorized - In addition to the usage described in HTTP,
servers that support mediated deposit SHOULD use this status code when
the server does not understand the value given in the X-Behalf-Of
header. In this case a human-readable explanation MUST be provided.
</li>
<li>403 Forbidden - indicates that there was a problem making the
deposit, it may be that the depositor is not authorised to deposit on
behalf of the target owner, or the target owner does not have
permission to deposit into the specified collection.</li>
<li>412 Precondition failed - MUST be returned by server
implementations if a calculated checksum does not match a value
provided by the client in the Content-MD5 header.</li>
<li>415 Unsupported Media Type - MUST be used to indicate that the
format supplied in either a Content-Type header or in an
X-Format-Namespace header or the combination of the two is not accepted
by the server.</li>
</ul>
<p>SWORD previously defined the X-Error-Code header to
be used in addition to the above error codes to supply additional error
detail. See SWORD Extensions to the AtomPub.</p>
<h2>7. Category Documents</h2>
<p>The SWORD profile does not require server support for Category Documents, and
clients MUST NOT require them for deposit operation.</p>
<h2>8. Service Documents</h2>
<p>SWORD requires support for Service Documents as described in ATOMPUB section
8, and defines several new elements that extend the Service Document to allow
servers to indicate their support for the various SWORD extensions. Some of
these extensions apply to the service as a whole and are used as children of the
app:service element, others relate to individual collections and are used as
children of the app:collection element. The following elements apply to the
service as a whole and are used as children of the app:service element: -</p>
<table>
<thead>
<tr>
<th>Element</th>
<th>Allowed Values</th>
<th>Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td>sword:version</td>
<td>text</td>
<td>SHOULD be included. Indicates the version of the
specification against which the server was implemented.
Whilst this profile aims to be back-compatible, this
information may be useful for assessing compliance
issues. For this spec the element should be 1.3.</td>
</tr>
<tr>
<td>sword:verbose</td>
<td>'true'|'false'</td>
<td>SHOULD be included. Indicates whether the server
supports the verbose developer feature as described in
Part A Section 3.2</td>
</tr>
<tr>
<td>sword:noOp</td>
<td>'true'|'false'</td>
<td>SHOULD be included. Indicates whether the server
supports the No Op developer feature as described in
Part A Section 3.1</td>
</tr>
<tr>
<td>sword:level</td>
<td>'1'</td>
<td>MUST be included and MUST have a value of '1' for
back compatibility. The idea of compliance levels has
been removed from the SWORD profile. Implementations
that meet the mandatory requirements of this
specification also meet the mandatory requirements of
SWORD 1.2 and earlier.</td>
</tr>
<tr>
<td>sword:maxUploadSize</td>
<td>integer</td>
<td>MAY be included to indicate the maximum size (in kB)
of package that can be uploaded to the SWORD
service.</td>
</tr>
</tbody>
</table>
<h3>8.1 Workspaces</h3>
<p>As in AtomPub [AtomPub], in SWORD Workspaces are simply named groups of
Collections.</p>
<p>For the SWORD profile, one or more app:collection elements SHOULD be present
in an app:workspace element, unless the authenticated user does not have
permission to deposit.</p>
<p>Within app:collection, the app:accept element MUST be used to specify
accepted media-ranges. In many cases, such as when content is packaged in
archive files, the MIME type does not adequately describe the content. In these
cases, implementations SHOULD provide one or more sword:formatNamespace elements
to specify the packaging format within the archive file. The value for this
element SHOULD be taken from the enumeration in SWORD Content Package Types
[SWORD-TYPES].</p>
<p>SWORD defines the following extensions to the app:collection element:</p>
<table>
<thead>
<tr>
<th>Element</th>
<th>Allowed Values</th>
<th>Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td>sword:collectionPolicy</td>
<td>text</td>
<td>MAY be included. Used for a human-readable
description of collection policy. Include either a text
description or a URI.</td>
</tr>
<tr>
<td>sword:mediation</td>
<td>'true'|'false'</td>
<td>SHOULD be included. Used to indicate if mediated
deposit is allowed on the defined collection.</td>
</tr>
<tr>
<td>sword:treatment</td>
<td>text</td>
<td>MAY be included. Used for a human-readable statement
about what treatment the deposited resource will
receive.</td>
</tr>
<tr>
<td>sword:formatNamespace</td>
<td>URI</td>
<td>MAY be included. Used to identify the content
packaging types supported by this collection. SHOULD be
a URI from [SWORD-TYPES]. </td>
</tr>
<tr> <td>sword:service</td> <td>URI</td> <td>0 or more MAY be
included to direct clients to nested service definitions. If
present, the value MUST be a URI that dereferences to another
SWORD Service Document.</td>
</tr>
</tbody>
</table>
<p>The use of a Dublin Core dcterms:abstract element containing a description of
the Collection is RECOMMENDED.</p>
<h1>9. Creating and Editing Resources</h1>
<h2>9.2 Creating resources with POST</h2>
<p>SWORD uses HTTP headers to modify the behaviour of the creation of Media
Resources using an HTTP POST request as defined in section 9.6 of the AtomPub
[AtomPub]. The following headers are used:</p>
<table>
<thead>
<tr>
<th>Header</th>
<th>Allowed Values</th>
<th>Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content-MD5</td>
<td>MD5 Checksum of the contents</td>
<td>Clients SHOULD use this header as defined in [HTTP].
Servers SHOULD check it against the request entity if
present.</td>
</tr>
<tr>
<td>Content-Disposition:filename</td>
<td>Text</td>
<td>Clients MAY use the filename parameter with the
Content-Disposition header as defined in [RFC2183]
section 2.3 to provide a suggested filename for the
POSTed entity. Server implementors MUST adopt the
behaviour and requirements in [RFC2183] SHOULD be used.
data.</td>
</tr>
<tr>
<td>X-On-Behalf-Of</td>
<td>Text</td>
<td>Clients MAY use the X-On-Behalf-Of as described in
Part A Section 2. If the server does not support
mediation, it SHOULD return a status code 400 Bad
Request, with a human-readable explanation. </td>
</tr>
<tr>
<td>X-Verbose</td>
<td>'true'|'false'</td>
<td>Clients MAY use this header to request verbose
progress information on a deposition. If present,
servers SHOULD respond by including a
sword:verboseDescription element in the Atom Entry
Document generated as a result of the POST. See Part A
Section 3.2.</td>
</tr>
<tr>
<td>X-No-Op</td>
<td>'true'|'false'</td>
<td>Clients MAY use this header as described in Part A
Section 1. If present with a value of 'true', servers
MUST either simulate the deposit or return a status code
of 400 Bad Request.</td>
</tr>
<tr>
<td>X-Format-Namespace</td>
<td>URI</td>
<td>Clients SHOULD use this header with a value taken
from the enumeration in [SWORD-TYPES]. If the server
cannot accept the format given in the header it MUST
return a status code of 415 Unsupported Media Type.</td>
</tr>
</tbody>
</table>
<h3>9.3 Editing Resources with PUT, 9.4 Deleting Resources with DELETE</h3>
<p>SWORD implementations MAY implement the AtomPub mechanisms to edit and delete
Atom Entries and Media Resources. Where a server does not support these
mechanisms, it SHOULD respond to requests with either code 405 (Method Not
Allowed) or 501 (Not Implemented), as appropriate. </p>
<h2>9.6 Media Resources and Media Link Entries</h2>
<p>SWORD is primarily concerned with depositing binary files/packages of content
as Media Resources rather than ATOM documents - implementers should pay
particular attention to this section and to section 9.6 of AtomPub [AtomPub].
The server MUST signal the media types it will accept using the app:accept
element in the Service Document, as specified in Section 8.3.4, and SHOULD
signal the content package types it will accept using the sword:formatNamespace
element, as described in Section 8.1 of this specification.</p>
<p>The Location: element of the HTTP header response MUST contain the URI of the
Media Link Entry, as defined in ATOMPUB. The Media Link Entry URI MUST
dereference, and MUST contain an atom:content element with a src attribute
containing a URI. This URI SHOULD dereference to either the original deposited
file or a machine readable description of the resources created as a result of
the deposit (such as an OAI-ORE Resource Map serialization, see [ORE]). If the
URI of the content changes over time, e.g. as the result of a workflow process,
the server MUST reflect this change by changing the Media Entry Document content
element, or by using HTTP features (e.g. redirection, Content-Location headers
etc) to direct clients from the original content location. </p>
<p>Providing an edit-media link is OPTIONAL. If a server provides an edit-media
link it SHOULD allow media resource updating with PUT as described in AtomPub
sections 9.3 and 9.6. </p>
<p>As in Atom, the atom:id element MUST contain a unique identifier for
the deposit.</p>
<p>According to AtomPub, an atom:link element SHOULD be
supplied with a rel="edit-media" attribute and a href attribute
containing a URI for the Media Resource. It is OPTIONAL that this URI be
the same as that supplied as the src attribute of the
atom:content element. SWORD makes no further recommendations
about what this link element should resolve to; examples might include a
representation which supplies metadata from the package and access to
unpacked binary files. Alternatively, a repository might supply multiple
atom:link elements to identify each unpacked resource. This is
an implementation decision.</p>
<p>According to AtomPub, an atom:link element MAY be
supplied with a rel="edit" attribute and a href attribute containing a
URI for the Media Link Entry metadata. SWORD makes no further
recommendations about what this link element should resolve to; examples
might include a jump-off page, users private metadata or workflow
management page. This link MAY allow authorized users to make further
edits to the atom, or other, metadata.</p>
<p>Wherever practical, URIs SHOULD dereference to a logical
location, SHOULD be unique and SHOULD persist.</p>
<p>Where URIs do not dereference a 501 Not Implemented HTTP error
code SHOULD be returned, with a human-readable explanation.</p>
<h2>9.8 The Atom Entry Document</h2>
<p>On successfully accepting a POST (deposit), implementers MUST return an Atom
Entry Document with the HTTP response. The Atom Entry Document will usually
contain information about the 'deposit'; this is not the same as the metadata
describing the file(s) within the package which SHOULD be supplied within the
package itself. Implementers are free to extend their use of the atom:content
element to carry additional metadata but this is beyond the scope of this
profile.</p>
<p>Atom Entry Documents must contain elements as follows: -</p>
<table>
<thead>
<tr>
<th>Element</th>
<th>Allowed Values</th>
<th>Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td>atom:contributor</td>
<td>Text</td>
<td>SHOULD contain the value of the X-On-Behalf-Of
header, if one was present in the POST request (See Part A Section 2)</td>
</tr>
<tr>
<td>atom:generator</td>
<td>Text</td>
<td>SHOULD contain the URI and version of the client.
<span class="todo">TODO How does this information reach
the server? There doesn't seem to be a header for it,
and unless we use multipart it won't go in the
body.</span></td>
</tr>
<tr>
<td>sword:treatment</td>
<td>Text</td>
<td>MUST be present and contain either a human-readable
statement describing treatment the deposited resource
has received or a URI that dereferences to such a
description.</td>
</tr>
<tr>
<td>sword:verboseDescription</td>
<td>Text</td>
<td>If the client made the POST request with an
X-Verbose:true header, the server SHOULD supply a
verbose description of the deposit process. See Part A Section 3.3</td>
</tr>
<tr>
<td>sword:noOp</td>
<td>'true'|'false'</td>
<td>If the client made the POST request with an
X-No-Op:true header, the server SHOULD reflect this by
including a sword:noOp element with a value of "true' in
the response. See Part A Section 3.3. Servers MAY use a
value of 'false' to indicate that the deposit proceeded
but MUST NOT use this element to signify an error.</td>
</tr>
<tr>
<td>sword:formatNamespace</td>
<td>'URI</td>
<td>If the POST request results in the creation of
packaged resource, the server MAY use this element to
declare the packaging type. If used it SHOULD take a
value from [SWORD-TYPES].</td>
</tr>
</tbody>
</table>
<h1>10. Listing Collections</h1>
<p>AtomPub states that "Collection Resources MUST provide representations in the
form of Atom Feed elements whose Entries contain the IRIs of Members in the
Collection". The SWORD profile does not require Collection lists, but
implementers MAY wish to support this feature in order to be AtomPub [AtomPub]
compliant. As noted in Part B Section 5.2, clients MUST NOT rely on Collection
Lists in order to make a SWORD deposit.</p>
<h1>11. Atom Format</h1>
<p>The SWORD Profile uses the "edit" and "edit-media" link
relations. The SWORD profile does not currently support updates to
deposited items, therefore a URI with an edit or edit-media link
relation points to a Member Entry which MAY be editable, but is not
required to be.</p>
<h1>14. Securing the Atom Publishing Protocol</h1>
<p>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
MUST be capable of being configured to use HTTP Basic Authentication
[RFC2617] in conjunction with a TLS connection as specified by
[RFC2818]."</p>
<h1>15. Security Considerations</h1>
<p>Implementers should refer to this section of AtomPub.</p>
<h2>References</h2>
<p>[SWORD-TYPES] Allinson, J. et al, SWORD Content Package
Types, September 2008. TODO updated publication date and link.</p>
<p>[RFC4387] Nottingham, M. and R. Sayre, "The Atom Syndication Format", <a
href="http://www.ietf.org/rfc/rfc4287.txt" class="external"
title="http://www.ietf.org/rfc/rfc4287.txt">RFC 4287</a>, December 2005.
[RFC4287]. <a href="http://www.ietf.org/rfc/rfc4287.txt" class="external free"
title="http://www.ietf.org/rfc/rfc4287.txt"
rel="nofollow">http://www.ietf.org/rfc/rfc4287.txt</a> (see also non-normative
html version at <a href="http://app.org/rfc4287.html" class="external free"
title="http://APP.org/rfc4287.html"
rel="nofollow">http://APP.org/rfc4287.html</a>)</p>
<p>[AtomPub] Gregario, J. and B. de hOra, "The Atom Publishing Protocol", <a
href="http://www.ietf.org/rfc/rfc5023.txt" class="external"
title="http://www.ietf.org/rfc/rfc5023.txt">RFC 5023</a>, October 2007. <a
href="http://www.ietf.org/rfc/rfc5023.txt" class="external free"
title="http://www.ietf.org/rfc/rfc5023.txt"
rel="nofollow">http://www.ietf.org/rfc/rfc5023.txt</a> (see also non-normative
html version at <a href="http://bitworking.org/projects/atom/rfc5023.html"
class="external free" title="http://bitworking.org/projects/atom/rfc5023.html"
rel="nofollow">http://bitworking.org/projects/atom/rfc5023.html</a>) </p>
<p>[RFC2616] Fielding et al, "Hypertext Transfer Protocol -- HTTP/1.1", <a
href="http://www.ietf.org/rfc/rfc2616.txt" class="external"
title="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>, June 1999 <a
href="http://www.w3.org/Protocols/rfc2616/rfc2616.html" class="external free"
title="http://www.w3.org/Protocols/rfc2616/rfc2616.html"
rel="nofollow">http://www.w3.org/Protocols/rfc2616/rfc2616.html</a> </p>
<p>[RFC2616-10] "HTTP/1.1: Status Code Definitions", part of "Hypertext Transfer
Protocol -- HTTP/1.1" <a href="http://www.ietf.org/rfc/rfc2616.txt"
class="external" title="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>
Fielding, et al. <a
href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" class="external
free" title="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
rel="nofollow">http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</a> </p>
<p>[RFC3864] Klyne, G., Nottingham, M. and Mogul, J. "Registration Procedures
for Message Header Fields", <a href="http://www.ietf.org/rfc/rfc3864.txt"
class="external" title="http://www.ietf.org/rfc/rfc3864.txt">RFC 3864</a>,
September 2004 <a href="http://www.rfc-editor.org/rfc/rfc3864.txt"
class="external free" title="http://www.rfc-editor.org/rfc/rfc3864.txt"
rel="nofollow">http://www.rfc-editor.org/rfc/rfc3864.txt</a></p>
<p>[RFC2183] Troost, R., Dorner, S. and Moore, K., "Communicating Presentation
Information in Internet Messages: The Content-Disposition Header Field", <a
href="http://www.ietf.org/rfc/rfc2183.txt" class="external"
title="http://www.ietf.org/rfc/rfc2183.txt">RFC 2183</a>, August 1997 <a
href="http://www.ietf.org/rfc/rfc2183.txt" class="external free"
title="http://www.ietf.org/rfc/rfc2183.txt"
rel="nofollow">http://www.ietf.org/rfc/rfc2183.txt</a></p>
<p>[OAUTH] Atwood, A., Conlan, R. et al OAuth Core 1.0 <a
href="http://oauth.net/core/1.0/">http://oauth.net/core/1.0/</a>, December
2007</p>
<p>[ORE] Lagoze, C., Van de Sompel, H et al, Open Archives Initiative Object
Reuse and Exchange, <a
href="http://www.openarchives.org/ore/">http://www.openarchives.org/ore/</a>,
June 2008</p>
</body>
</html>
|
