Menu
▾
▴
sword-app-tech — Mailing list for discussion of SWORD implemenation and development.
You can subscribe to this list here.
| 2008 |
Jan
(22) |
Feb
(8) |
Mar
(9) |
Apr
(4) |
May
(17) |
Jun
(29) |
Jul
(11) |
Aug
(13) |
Sep
(17) |
Oct
(14) |
Nov
(41) |
Dec
(8) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2009 |
Jan
(17) |
Feb
(26) |
Mar
(18) |
Apr
(1) |
May
(11) |
Jun
(20) |
Jul
(5) |
Aug
|
Sep
|
Oct
|
Nov
(3) |
Dec
|
| 2010 |
Jan
(23) |
Feb
(7) |
Mar
(9) |
Apr
(13) |
May
(5) |
Jun
|
Jul
(3) |
Aug
(5) |
Sep
|
Oct
(1) |
Nov
(3) |
Dec
|
| 2011 |
Jan
(3) |
Feb
|
Mar
(2) |
Apr
(1) |
May
|
Jun
(14) |
Jul
(22) |
Aug
(1) |
Sep
(2) |
Oct
(11) |
Nov
(11) |
Dec
(35) |
| 2012 |
Jan
(17) |
Feb
(12) |
Mar
(41) |
Apr
(40) |
May
(41) |
Jun
(27) |
Jul
(9) |
Aug
(1) |
Sep
|
Oct
(6) |
Nov
|
Dec
(11) |
| 2013 |
Jan
|
Feb
(4) |
Mar
(2) |
Apr
(8) |
May
(1) |
Jun
(18) |
Jul
(10) |
Aug
(16) |
Sep
(2) |
Oct
(1) |
Nov
(14) |
Dec
(11) |
| 2014 |
Jan
(7) |
Feb
(2) |
Mar
|
Apr
|
May
(8) |
Jun
(1) |
Jul
(7) |
Aug
(10) |
Sep
(8) |
Oct
(8) |
Nov
|
Dec
|
| 2015 |
Jan
|
Feb
(2) |
Mar
(2) |
Apr
|
May
(2) |
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
| 2016 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
(4) |
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
| 2017 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
(6) |
Jul
|
Aug
|
Sep
|
Oct
(1) |
Nov
|
Dec
(4) |
| 2018 |
Jan
(2) |
Feb
|
Mar
|
Apr
|
May
|
Jun
(1) |
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
|
From: Scott Y. <sco...@an...> - 2008-09-10 02:09:45
|
Hi Jim, Re the open issue, I agree with addition of a new element rather than redefine use of atom:source. 1.1 typo: "numberic" 1.3/1.4 Does the server need to regurgitate the package type back to the client given the client is the one to specify this in the first place? I'm not sure I understand the context of this. The server response I would think is likely only to hold that information which the client needs to know post-deposit (e.g. identifiers of created objects, links to created objects, metadata allowing the client to map internal information to repository versions of objects, etc). There's nothing wrong in the example, I'm just not sure why this would be needed. In our journal example, we would only need to provide a response to OJS in order it can keep an audit trail as well as link to repository versions of a journal issue and its articles, for example see I still think some examples of complex object deposits would be useful however the statement in 9.8 regarding atom:content I think puts this out of scope for the 1.3 spec. Maybe these are better in an implementation guide that perhaps could be drafted as part of the eprints/Fedora/DSpace implementation deliverables? From an implementation point of view, I think it's important for any server implementation to be able to make Service Document and Deposit Responses pluggable/configurable. In real-world implementations this is going to be needed as there will be great variation across client application requirements and package-to-data-model mapping in repository deposit targets. For example, in DSpace it may be possible to instantiate different SWORD service document- and deposit response- handler classes based on a combination of Package Ingester configurations and User-Agents (or something like that) allowing for context-based deposits. Scott. > Message: 6 > Date: Tue, 9 Sep 2008 09:17:12 +0100 > From: "Jim Downing" <oj...@ca...> > Subject: [sword-app-tech] Fwd: SWORD 1.3 > To: swo...@li... > Message-ID: > <2ab...@ma...> > Content-Type: text/plain; charset="utf-8" > > Hi all, > > A second draft of the SWORD revision 1.3 is available at > http://sword-app.sourceforge.net/sword-1.3/sword-profile-1.3.html. A > summary of the changes since the first draft: - > > * typso fixed > * formatNamespace renamed > * A potential mechanism for preferred packaging added > * Error documents replace X-Error-Code. I was unhappy about returning an > atom:entry in precisely the situation where one isn't created, so error > documents are rooted at a new element. > * More explanation of the service nesting mechanism. > > Some of these changes break compatibility with 1.2. > > Open Issue: > * We can either overload atom:source to contain the User-Agent, or else > invent a new element to contain the information. Given the choice I'd > prefer > the latter, what does everyone else think? > > Best regards, > jim > > |
|
From: Jim D. <oj...@ca...> - 2008-09-09 08:17:16
|
Hi all, A second draft of the SWORD revision 1.3 is available at http://sword-app.sourceforge.net/sword-1.3/sword-profile-1.3.html. A summary of the changes since the first draft: - * typso fixed * formatNamespace renamed * A potential mechanism for preferred packaging added * Error documents replace X-Error-Code. I was unhappy about returning an atom:entry in precisely the situation where one isn't created, so error documents are rooted at a new element. * More explanation of the service nesting mechanism. Some of these changes break compatibility with 1.2. Open Issue: * We can either overload atom:source to contain the User-Agent, or else invent a new element to contain the information. Given the choice I'd prefer the latter, what does everyone else think? Best regards, jim |
|
From: Jim D. <oj...@ca...> - 2008-09-08 17:51:59
|
<!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 (Hewlett Packard)</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
as web resources.</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 describes 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. </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:acceptPackaging 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]. Servers MAY also use a q attribute on the sword:acceptPackaging
element in order to communicate that it has a preference between packaging
formats. The q attribute MUST have a short floating-point numberic value between
0 and 1, where 0 indicates no support (equivalent to omitting that
sword:acceptPackaging element completely) and 1 indicates full support. If the q
attribute is not given, clients MUST assume a default value of 1. Values of the
q attribute MUST NOT have more than 3 digits after the decimal point.</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:acceptPackaging q="1.0">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging></b>
<b><sword:acceptPackaging q="0.8">http://purl.org/net/sword-types/bagit</sword:acceptPackaging></b>
</collection>
</workspace>
</service>
</pre>
<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-Packaging 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-Packaging value, it SHOULD
reject the POST by returning an HTTP wth a status code of 415 (Unsupported Media
Type). </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:packaging 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-Packaging: 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:packaging>http://purl.org/net/sword-types/mets/dspace</sword:packaging></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. 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. </p>
<p>The mediation technique described by SWORD is not intrinsically secure - it
is assumed that trust between the owning user and the mediating user will be
established by extending SWORD, or outside the scope of a resource creation,
using a mechanism such as that described by OAuth [OAUTH]. </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:packaging>http://purl.org/net/sword-types/bagit</sword:packaging>
</collection>
</workspace>
</service>
</pre>
<h3>2.2 Metadata Interactions 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>3.3 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.myrepository.ac.uk/sword-plugin" version="1.0">
myrepository.ac.uk's SWORD plugin</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>
<h2>5 Error documents</h2>
<p>SWORD adds a new class of document to [AtomPub] that gives server
implementations the ability to describe error conditions more fully than HTTP
response codes allow. If a server is reporting an error condition in response to
a resource POST (see Part B Section 9), it SHOULD also return a document with a
root element of sword:error. The sword:error element SHOULD have an href
attribute containing a URI that identifies the error. Errors in the SWORD
namespace are reserved and legal values are enumerated below. Implementations
MAY define their own errors, but MUST use a different namespace to do so.</p>
<table>
<thead>
<tr>
<th>Error URI</th>
<th>Usage notes</th>
</tr>
</thead>
<tbody>
<tr>
<td style="white-space: nowrap;">http://purl.org/net/sword/error/ErrorContent</td>
<td>The supplied format is not the same as that identified in the X-Packaging
header and/or that supported by the server </td>
</tr>
<tr>
<td style="white-space: nowrap;">http://purl.org/net/sword/error/ErrorChecksumMismatch</td>
<td>Checksum sent does not match the calculated checksum. The server MUST also
return a status code of 412 Precondition Failed.</td>
</tr>
<tr>
<td style="white-space: nowrap;">http://purl.org/net/sword/error/ErrorBadRequest</td>
<td>Some parameters sent with the POST were not understood. The server MUST
also return a status code of 400 Bad Request.</td>
</tr>
<tr>
<td style="white-space: nowrap;">http://purl.org/net/sword/error/TargetOwnerUnknown</td>
<td>Used in mediated deposit (see Part A Section 2) when the server does not
know the identity of the X-On-Behalf-Of user.</td>
</tr>
<tr>
<td style="white-space: nowrap;">http://purl.org/net/sword/error/MediationNotAllowed</td>
<td>Used where a client has attempted a mediated deposit, but this is not
supported by the server. The server MUST also return a status code of 412
Precondition Failed.</td>
</tr>
</tbody>
</table>
<p>The sword:error element MAY contain any of the elements normally used in
Entry Documents (See Part B Section 9.8), but does not to the meet the
requirements of Entry Documents (e.g. an atom:id element is not required).</p>
<h3>5.1 Error Document Example</h3>
<pre>
HTTP 1.1 400 Bad Request
<?xml version="1.0" encoding="utf-8"?>
<<b>sword:error</b> xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/"
xmlns:arxiv="http://arxiv.org/schemas/atom"
<b>href="http://example.org/errors/BadManifest"</b>>
<author>
<name>Example repository</name>
</author>
<title>ERROR</title>
<updated>2008-02-19T09:34:27Z</updated>
<generator uri="https://example.org/sword-app/"
version="0.9">sw...@ex...</generator>
<summary>The manifest could be parsed, but was not valid -
no technical metadata was provided.</summary>
<sword:treatment>processing failed</sword:treatment>
<link rel="alternate" href="https://arxiv.org/help" type="text/html"/>
</sword:error>
</pre>
<h2>6 Nested Service Description</h2>
<p>The number of collections in a server system is often so large that standard
AtomPub Service Documents become problematically large. To alleviate this
problem, SWORD adds a sword:service element as a child of app:collection AtomPub
Service Documents, allowing servers to nest SWORD service definitions. Depending
on the server implementation, this might indicate hierarchy in the structure of
the collections. Information does not commute between nested services; servers
MUST provide full information about each collection in every service document
that describes it. There is no mechanism for data to be inherited by nested services.</p>
<h3>6.1 Example</h3>
<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>
<sword:acceptPackaging q="0.8">http://purl.org/net/sword-types/bagit</sword:acceptPackaging>
<b><sword:service>http://www.myrepository.ac.uk/atom/geography-collection/service.atomsvc</sword:service></b>
</collection>
</workspace>
</service>
</pre>
<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-Packaging header or the combination of the two is not accepted
by the server.</li>
</ul>
<p>See Part A Section 5 for a description of how Error Documents can be used to
provide more information about errors.</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>MAY 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>MAY 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: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:acceptPackaging 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:acceptPackaging q="[qvalue]"</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]. The q attribute MAY be used to
indicate relative preferences between packaging formats
(See Part A Section 1.1).</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-Packaging</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:acceptPackaging
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. If an implementation does need to indicate that a
Media Entry Document has been removed, it SHOULD return 410 Gone to future
requests. In other circumstances 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:packaging</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 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>
|
|
From: Jim D. <oj...@ca...> - 2008-09-05 15:06:28
|
Hi Julie, 2008/9/5 Julie Allinson <ja...@yo...> > It sounds like there's general agreement about most of your open > issues. Regarding the multi part question - I agree with Glen. I'd > like to see the SWORD profile extend beyond single files/packages. > Also, we had earlier discussion about depositing by-reference - is there > any support for that here? I'm not sure I see it. Like the incremental package update, it seems to be like you can do that with AtomPub. > Oh, and regarding backward compatibility - it sounds like most people > are willing to sacrifice this for current simplicity and the SWORD > implementation community is perhaps small enough to make that doable. I'll write in all the changes that have been suggested and remove compatibility between 1.2 level1 and 1.3. In the meantime I'll try to solicit some more feedback on the subject: we still haven't heard from any implementers outside SWORD2. Can we agree a timescale for finalising this document please? - I'm sure > the SWORD2 developers want to get implementing. Can I suggest all > comments by the end of Wednesday 10th September, with revised version > soon after that? I'll try to get the existing typos and errors corrected over the weekend, along with some proposed wording for edits and additions. Best regards, jim |
|
From: Jim D. <oj...@ca...> - 2008-09-05 15:01:18
|
Hi Glen, Thanks for your comments. 2008/9/4 Glen Robson <gle...@ll...> > The document looks great. The only issue I want to bring up is the > following from 5.4 and 9.3 : > > SWORD implementations MAY implement the AtomPub mechanisms to edit > > Should this be a SHOULD? I know we've discussed editing and deleting > in the meeting in London and I can't see a need for delete but I can > see the use cases for editing. Updating could also work for appending > to a collection if the entry is a collection level document. What do > others think? Will this cause problems with the workflow for deferred > deposits? I'm open to it being a SHOULD. It would bring SWORD closer to AtomPub which is a good thing. When it comes to incremental update, the way I see it being done is that on the original POST, the server creates a new AtomPub (or AtomPub/SWORD) Collection, and that you update by POSTing new resources to that. The reason I haven't put this in SWORD is that it's something that can be done without any extensions to AtomPub. I think it would be worth a user guide demonstrating how one might create an AtomPub collection as the result of a SWORD POST. I'm not sure it needs to be in the spec though. > Some other thoughts and votes below: > > On 26 Aug 2008, at 16:10, Jim Downing wrote: > > > 5/ Adopting the multipart proposal would solve some issues (e.g. the > > atom:generator issue above). It would mean a bit more complexity to > > the authentication / mediation section. Also, it seems premature to > > base SWORD on a draft RFC. Thoughts? > > > > Will multipart allow the upload of a directory of files to a single > deposit. If so I think this would be a useful addition as currently > the only way to submit multiple files is to zip them up then deposit > then. The multipart RFC as it stands just allows an Atom entry to be sent along with the same kind of payload as current Media Resource POSTs. So "no" in a word! Best regards, jim |
|
From: Julie A. <ja...@yo...> - 2008-09-05 10:28:42
|
Hi Jim, everyone, First off, the new version of the profile looks great - better structure and clearer layout than the previous version, so should help with SWORD advocacy and uptake. It sounds like there's general agreement about most of your open issues. Regarding the multi part question - I agree with Glen. I'd like to see the SWORD profile extend beyond single files/packages. Also, we had earlier discussion about depositing by-reference - is there any support for that here? I'm not sure I see it. I had wondering about upping support for the deposit of ATOM documents, alongside the emphasis on 9.6. Oh, and regarding backward compatibility - it sounds like most people are willing to sacrifice this for current simplicity and the SWORD implementation community is perhaps small enough to make that doable. Can we agree a timescale for finalising this document please? - I'm sure the SWORD2 developers want to get implementing. Can I suggest all comments by the end of Wednesday 10th September, with revised version soon after that? Cheers, Julie Glen Robson wrote: > Hi all, > > The document looks great. The only issue I want to bring up is the > following from 5.4 and 9.3 : > > SWORD implementations MAY implement the AtomPub mechanisms to edit > > Should this be a SHOULD? I know we've discussed editing and deleting > in the meeting in London and I can't see a need for delete but I can > see the use cases for editing. Updating could also work for appending > to a collection if the entry is a collection level document. What do > others think? Will this cause problems with the workflow for deferred > deposits? > > Some other thoughts and votes below: > > On 26 Aug 2008, at 16:10, Jim Downing wrote: > >> Hi all, >> >> In this e-mail some open issues, and some reasoning where I've made >> changes between 1.2 and 1.3. >> >> Open issues >> >> 1/ sword:formatNamespace and X-Formatnamespace aren't particularly >> well named; sword:acceptPackaging X-Packaging seem more appropriate. >> I erred on the side of not changing things. > > Sounds a good idea to me > >> >> 2/ It would be useful to have a user guide spelling out how to >> implement "deferred" resource creation, i.e. where the server >> responds 202 to the original POST. >> > > as above > >> 3/ How does the server obtain the identity of the client to use in >> the atom:generator element? There's no header for it. >> > > I agree with Stuart User-Agent HTTP header sounds good. > >> 4/ I'm ambivalent about whether the error-codes should be in headers >> or in a document. If we want to enforce back-compatibility the >> headers will have to be supported in either case. >> > > Both has got my vote. > >> 5/ Adopting the multipart proposal would solve some issues (e.g. the >> atom:generator issue above). It would mean a bit more complexity to >> the authentication / mediation section. Also, it seems premature to >> base SWORD on a draft RFC. Thoughts? >> > > Will multipart allow the upload of a directory of files to a single > deposit. If so I think this would be a useful addition as currently > the only way to submit multiple files is to zip them up then deposit > then. > >> 6/ Pablo at MS requested a "preferred format" feature in the >> collection element of the service document, or alternatively a >> @preference attribute containing an ordinal number. Would others find >> this useful? >> > > I can see the use for this, you may prefer to work with the source > format of a document but will take an access copy if supplied. > > > > - sword:level: Can we just dump this requirement? AFAIK there are no > real > > production users of SWORD yet who couldn't easily change their > tools, so > > shall we drop it while we can? If we're not dropping it, most other > service > > documents in the spec are missing it. > > I agree with Stuart if we can get away with removing it now it would > simplify the spec as we now have sword:level and sword:version which > may cause confusion. > > Thanks > > Glen > -- Julie Allinson <ja...@yo...> Digital Library Manager University Library & Archives, J.B. Morrell Library University of York, Heslington, York, YO10 5DD, UK tel: ++44 (0) 1904 434083 skype: j.allinson web: http://www.york.ac.uk/services/library/elibrary/digitallibrary.htm -- |
|
From: Glen R. <gle...@ll...> - 2008-09-04 11:01:51
|
Hi all, The document looks great. The only issue I want to bring up is the following from 5.4 and 9.3 : SWORD implementations MAY implement the AtomPub mechanisms to edit Should this be a SHOULD? I know we've discussed editing and deleting in the meeting in London and I can't see a need for delete but I can see the use cases for editing. Updating could also work for appending to a collection if the entry is a collection level document. What do others think? Will this cause problems with the workflow for deferred deposits? Some other thoughts and votes below: On 26 Aug 2008, at 16:10, Jim Downing wrote: > Hi all, > > In this e-mail some open issues, and some reasoning where I've made > changes between 1.2 and 1.3. > > Open issues > > 1/ sword:formatNamespace and X-Formatnamespace aren't particularly > well named; sword:acceptPackaging X-Packaging seem more appropriate. > I erred on the side of not changing things. Sounds a good idea to me > > 2/ It would be useful to have a user guide spelling out how to > implement "deferred" resource creation, i.e. where the server > responds 202 to the original POST. > as above > 3/ How does the server obtain the identity of the client to use in > the atom:generator element? There's no header for it. > I agree with Stuart User-Agent HTTP header sounds good. > 4/ I'm ambivalent about whether the error-codes should be in headers > or in a document. If we want to enforce back-compatibility the > headers will have to be supported in either case. > Both has got my vote. > 5/ Adopting the multipart proposal would solve some issues (e.g. the > atom:generator issue above). It would mean a bit more complexity to > the authentication / mediation section. Also, it seems premature to > base SWORD on a draft RFC. Thoughts? > Will multipart allow the upload of a directory of files to a single deposit. If so I think this would be a useful addition as currently the only way to submit multiple files is to zip them up then deposit then. > 6/ Pablo at MS requested a "preferred format" feature in the > collection element of the service document, or alternatively a > @preference attribute containing an ordinal number. Would others > find this useful? > I can see the use for this, you may prefer to work with the source format of a document but will take an access copy if supplied. > - sword:level: Can we just dump this requirement? AFAIK there are no real > production users of SWORD yet who couldn't easily change their tools, so > shall we drop it while we can? If we're not dropping it, most other service > documents in the spec are missing it. I agree with Stuart if we can get away with removing it now it would simplify the spec as we now have sword:level and sword:version which may cause confusion. Thanks Glen |
|
From: Antony C. [awc] <aw...@ab...> - 2008-08-29 08:29:26
|
Yes I think if it's seen as useful we need to know in what way. Expressing a preference where a less common schema/sip-package or format is partially supported isn't really a problem, however the danger is that a server might declare that it supports METS/SWAP but the outcome may not be clear. > > 6/ Pablo at MS requested a "preferred format" feature in the > collection > > element of the service document, or alternatively a @preference > attribute > > containing an ordinal number. Would others find this useful? > > I think it would be useful. Can we come up with some concrete > examples where > this is required or very useful in order to help justify it? > > Cheers, > > > Stuart > _________________________________________________________________ > > Gwasanaethau Gwybodaeth Information Services > Prifysgol Aberystwyth Aberystwyth University > > E-bost / E-mail: Stu...@ab... > Ffon / Tel: (01970) 622860 > _________________________________________________________________ > > > --------------------------------------------------------------------- > ---- > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > Build the coolest Linux based applications with Moblin SDK & win > great prizes > Grand prize is a trip for two to an Open Source event anywhere in the > world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > sword-app-tech mailing list > swo...@li... > https://lists.sourceforge.net/lists/listinfo/sword-app-tech |
|
From: Scott Y. <sco...@an...> - 2008-08-29 04:48:14
|
Hi Jim, I think if (referring to Stuart's mail) the User-Agent HTTP header was adopted as a means of allowing the server to identify the client, the formatNamespace/X-Packaging clarified, and examples of structured deposit responses added to the spec that provides much of what we need. It would be good to have provision additional context info but we may be able to work around that depending on the repository implementations, which leads to my next question... Is development for ePrints/Fedora/DSpace implementations of the APP 1.3 updates planned as part of SWORD 2? If so, I can help with some of the DSpace development if help is needed, else if the developer(s) assigned to DSpace could look at providing configurable/pluggable Service Document and Deposit Response generators that would go a long way to assisting our current and future use cases where the context of the deposit will govern these responses. (There are also some notes on other changes we would like to see changed in the current DSpace implementation at http://pilot.apsr.edu.au/wiki/index.php/SWORD_Report, mainly directed at the collection-centric implementation). Happy to help with some of the coding if needed. Scott. Jim Downing wrote: > Hi Scott, > > Thanks for the responses and questions. > > 2008/8/27 Scott Yeadon <sco...@an... > <mailto:sco...@an...>> > > "1/ sword:formatNamespace and X-Formatnamespace aren't > particularly well > named; sword:acceptPackaging X-Packaging seem more appropriate. I > erred on > the side of not changing things." > > I like your idea of changing the formatNamespace header/element to > X-Packaging/acceptPackaging, it's much clearer in its meaning. I > think it should be changed in the SWORD APP. > > > We'd have to either require 1.3 implementations to understand both > forms, or lose the forward compatibility. > > > "6/ Pablo at MS requested a "preferred format" feature in the > collection > element of the service document, or alternatively a @preference > attribute > containing an ordinal number. Would others find this useful?" > > I think support for a list of package formats and order of > preference may be a useful feature, I'd support its inclusion in > the spec. > > > I'll come up with a proposal for discussion unless anyone else wants to? > > > > In section 3.2 is there a typo with the source/generator - the > example represents a server response but the generator value still > points to the client; should the generator in the response be the > server? > > > Yes, it's an error. I'm not happy with the use of atom:source as in > 1.2: Atom uses this when entries are copied between feeds, not to > record user agent data. > > > > In section 14, there's a typo: "SHOULD MUST" > > > Noted, thanks. > > > > Some additional comments (others on the list feel free to offer > opinions!): > > We have run a pilot project which developed a SWORD plugin for OJS > for depositing journals to a repository (report at > http://pilot.apsr.edu.au/wiki/index.php/SWORD_Report). The issues > I see which are still unresolved in the 1.3 draft are: > > 1) A mechanism for communicating deposit contextual information in > SWORD requests. > To take our journal example - in order for a repository to expose > appropriate deposit targets in a service document it needs to know > the source application (OJS + version), the content type of the > packaged object (journal, issue, article, etc) and the package > format (particular flavour of METS). While X-Packaging can tell us > the package format I'd like guidance on the appropriate place to > indicate the source app (currently we are using the User-Agent > HTTP header) and content type (no workaround at the moment). > Implementors may also require further information which I suspect > would typically be satisfied by using key-value pairs within a > context header, e.g. X-Context-Object: type=custom;<key-value > pairs> where "type" specifies a URL or string representing the > class of context object and "<key-value pairs>" is a set of > implementation-dependent key/value pairings which may be used by a > SWORD Server implementation for purposes such as constructing more > targetted service documents. So in our OJS deposit we get, for > example, X-Content-Object: type=journal;source=Open Journal > Systems SWORD Plugin v2.2 build 0;content-type=issue > > For implementors the context information is also extremely useful > for assisting in decision-making in workflow paths as well as > low-level operations such as determining which ingestion/service > document/deposit classes to instantiate. So while I appreciate > workflows are outside the scope of the spec, I think there still > needs to be some mechanism to allow SWORD to integrate with > workflows and, at least for our purposes, provision of a context > header would go a long way in meeting this need. > > > My gut feeling is that this is a good candidate for an extension, > especially if we adopt the AtomPub multipart extension in this / a > future revision. > > > > > 2) Support (or maybe just guidance) on supporting structured > deposit responses. > By this I mean consideration of situations where the depositing > app and target repository need to communicate metadata such as the > ids/urls of the deposited material, especially where the deposit > resulted in a package being unpacked into multiple repository > objects. In our OJS example, when I archive a journal issue in > DSpace it is unpacked into a single DSpace collection consisting > of multiple DSpace items (the issue articles). OJS needs to know > what objects were created for auditing, avoiding duplicate > deposits and even linking back from the app to the repository > versions of the deposited material. The SWORD spec *could* > recommend by example a couple of ways of obtaining this > information on deposit. For example two sample responses, one > showing a single entry pointing to an OAI-ORE resource map (from > which the appropriate information could be derived/extracted) and > another showing a feed document containing entries for created > entities (e.g. http://pilot.apsr.edu.au/public/sword/atom.xml) may > satisfy this requirement. > > While technically this is probably outside the scope of the spec, > it gives implementors some guidance on how to achieve this in a > SWORD context and may provide some consistency in implementations. > > > I think a user guide on this would be very valuable. > > > > > 3) Is it worth considering explicit support for Collection Listings > I'm wondering if the issue in point 2) above could be addressed > through SWORD including aspects of section 10 (Listing > Collections) and section 5.2 (Listing Collection Members) of the > APP spec (http://www.ietf.org/rfc/rfc5023.txt). For example, if > after a deposit the requestor sent a List Collection Members GET > along with an atom:id, a repository (assuming they stored the > atom:id) could respond with a feed structure containing entries > representing created objects (e.g. see > http://pilot.apsr.edu.au/public/sword/atom.xml). This is a > slightly longer process than returning a feed structure or link to > aggregation resource direct from the deposit but could be an option. > > > I've strengthened the advice to SHOULD from MAY on this. The original > motivation for not requiring entry documents and collection listings > was to make server implementation as simple as possible. I don't know > how important that motivation is now. > > > 4) Governance of the SWORD Content Package Types (ownership, how > to get formats added/registered/etc). Again probably outside the > scope of the spec but worth considering. > > > Agree. > > Best regards, > jim > |
|
From: Jim D. <jim...@po...> - 2008-08-28 09:16:17
|
Hi Stuart, thanks for these. 2008/8/27 Stuart Lewis <sd...@ab...> > Here are some comments / issues with the document (nothing very big): > > = Editors > - Please cold you change Neil's and my affiliation to 'Aberystwyth > University'. Richard: Does yours need changing now too? > > = Document Structure > - Small typo: "this document describe the" needs an 's' on describe? Noted. > = 1.2 Package support during resource creation > - In the second paragraph you have that we SHOULD return a 400 (Bad > request). This is different from 1.2 of the spec which uses 415 > (Unsupported > Media Type) which seems a better fit, and is contradictory to the last > bullet point in 5.5 which says to use a 415. I agree - my notes don't make it clear why I didn't use 415 in both places. It's possible I was trying to signal a difference between Content-Type support and X-Format-Namespace support, but that kind of distinction can be made in the message. = 2 Mediated Deposit > - Is it a bit strong to say OAuth should be preferred by implementers? I really meant that in the sense that secure trust establishing standards should be preferred to relying solely on SWORD mediation. I'll reword the section. = 2.1 Mediation In Service Description > - In the example service document, you still list <sword:level>. More > about this later. > > = 2.2 Metadata Interractions In Mediated Deposit > - Typo in Interractions > - Why is the X-On-Behalf-Of listed as contributor, and the depositing user > as author? I can see why it is this way round, but it somehow feels wrong > as > the X-On-Behalf-Of-User is probably the author, and the depositing user is > just helping (contributing)? I'm glad you asked that question :-) I realized that there was a problem with the mediation specification in 1.2: a number of cases were described, and servers were expected to behave in a slightly different way for each, but didn't have any way of working out which of the cases applied for a particular deposit. Rather than having yet another header to represent this, it seemed easier to simplify it to a single, predictable behaviour. The second reason is that most of the time SWORD is conceptually creating a resource to represent the deposit action, and will link through to the payload resources, which can have the X-On-Behalf-Of user as the author. The only situation it seems a little skew for is where the user is mediated by a user agent. At least, though, the user agent knows that it performed this kind of mediation and the server's metadata is predictable. As an aside I'd note that this issue would disappear if multipart AtomPub is adopted in the future: clients could assert whatever author and contributor they felt appropriate. = 4 Auto-discovery > - Were we going to suggest that there can be a link rel on a collection > web page to a service document specifically for that collection? > - Should we recommend that the link rel of the master service document > appears on the repository home page if possible, as the 'relevant HTML > document'? It seems like useful guidance to have, and it's probably too brief to form a whole user guide on its own. I'll add this unless anyone objects? = 6 Service Documents > - sword:verbose and sword:noOp both say 'SHOULD be included'. This is > contradictory to section 3 (developer features) which specify 'MAY'. An error, but nonetheless a useful issue to discuss. I think MAY is more sensible, but SHOULD is required if we want compatibility. - sword:level: Can we just dump this requirement? AFAIK there are no real > production users of SWORD yet who couldn't easily change their tools, so > shall we drop it while we can? If we're not dropping it, most other service > documents in the spec are missing it. We need to make a decision on what level of back and forward compatibility we want between 1.2 and 1.3. There are a number of things that could be changed if compatibility is desired. I've started at a point of trying to make 1.3 compatible with AtomPub and 1.2, preferring AtomPub where 1.2 broke AtomPub. = 8.1 Workspaces > - I see the addition of sword:service. Have we discussed this (how it > would be implemented rather than should we have them), I don't remember? > Either way, I think it is a neat addition and would work well as specified. I don't think it has been discussed beyond being on the desiderata list for 1.3. It seemed like the simplest way. There needs to be a little more guidance on it: for example, you shouldn't be able to commute values for e.g. sword:noOp from a service document to a child service document. = 9.6 Media Resources and Media Link Entries > - Does the second paragraph need some clarification about what should be > returned by the location: element in the event of the deposited file having > been deleted (e.g. rejected during workflow)? Yes, I suppose that it SHOULD return 410 Gone. = 9.8 The Atom Entry Document > - atom:generator - Should we recommend the use of the standard > 'User-Agent' header? A lot easier than multiparting just for the sake of > it. As Scott pointed out, atom:generator is usually used for the feed generating software, i.e. it identifies the server software. As far as I can see AtomPub doesn't provide a mechanism for identifying the client. I don't think we should change the semantics of atom:source in the way specified in 1.2, so if we want client identification, we should probably add a sword:client that can contain an atom:generator element. Using User-Agent to populate this makes a lot of sense. And some responses to your questions: > > > 1/ sword:formatNamespace and X-Formatnamespace aren't particularly well > named; > > sword:acceptPackaging X-Packaging seem more appropriate. I erred on the > side > > of not changing things. > > +1 > > > I think we are still just about at the stage where we can get away with > these modifications. Just look at some of the big changes between minor > revision numbered APP docs... :) (e.g. what MIME type service documents > should have) Do we have a policy on how many votes constitutes a quorum? > > 3/ How does the server obtain the identity of the client to use in the > > atom:generator element? There's no header for it. > > As above - User-Agent header? > > > 4/ I'm ambivalent about whether the error-codes should be in headers or > in a > > document. If we want to enforce back-compatibility the headers will have > to be > > supported in either case. > > Maybe both? Codes in the header, descriptions in the document? Do you mean 'both' or 'either'. 'either' pushes the implementation effort to the client, so I'd prefer it to be 'both' or in just one place. > 5/ Adopting the multipart proposal would solve some issues (e.g. the > > atom:generator issue above). It would mean a bit more complexity to the > > authentication / mediation section. Also, it seems premature to base > SWORD on > > a draft RFC. Thoughts? > > Yes - perhaps a bit premature, but shows a lot of promise. Also not needed > so much if User-Agent is OK? True - although it's the potential to move all the X headers into an XML document that's probably the main goal. > > 6/ Pablo at MS requested a "preferred format" feature in the collection > > element of the service document, or alternatively a @preference attribute > > containing an ordinal number. Would others find this useful? > > I think it would be useful. Can we come up with some concrete examples > where > this is required or very useful in order to help justify it? I'll get in touch with Pablo to come up with an example and a proposed mechanism. Best regards, jim |
|
From: Stuart L. <sd...@ab...> - 2008-08-27 19:51:51
|
Hi Jim,
First off, thanks for writing this spec - it is a great document.
Here are some comments / issues with the document (nothing very big):
= Editors
- Please cold you change Neil's and my affiliation to 'Aberystwyth
University'. Richard: Does yours need changing now too?
= Document Structure
- Small typo: "this document describe the" needs an 's' on describe?
= 1.2 Package support during resource creation
- In the second paragraph you have that we SHOULD return a 400 (Bad
request). This is different from 1.2 of the spec which uses 415 (Unsupported
Media Type) which seems a better fit, and is contradictory to the last
bullet point in 5.5 which says to use a 415.
= 2 Mediated Deposit
- Is it a bit strong to say OAuth should be preferred by implementers?
= 2.1 Mediation In Service Description
- In the example service document, you still list <sword:level>. More
about this later.
= 2.2 Metadata Interractions In Mediated Deposit
- Typo in Interractions
- Why is the X-On-Behalf-Of listed as contributor, and the depositing user
as author? I can see why it is this way round, but it somehow feels wrong as
the X-On-Behalf-Of-User is probably the author, and the depositing user is
just helping (contributing)?
= 4 Auto-discovery
- Were we going to suggest that there can be a link rel on a collection
web page to a service document specifically for that collection?
- Should we recommend that the link rel of the master service document
appears on the repository home page if possible, as the 'relevant HTML
document'?
= 6 Service Documents
- sword:verbose and sword:noOp both say 'SHOULD be included'. This is
contradictory to section 3 (developer features) which specify 'MAY'.
- sword:level: Can we just dump this requirement? AFAIK there are no real
production users of SWORD yet who couldn't easily change their tools, so
shall we drop it while we can? If we're not dropping it, most other service
documents in the spec are missing it.
= 8.1 Workspaces
- I see the addition of sword:service. Have we discussed this (how it
would be implemented rather than should we have them), I don't remember?
Either way, I think it is a neat addition and would work well as specified.
= 9.6 Media Resources and Media Link Entries
- Does the second paragraph need some clarification about what should be
returned by the location: element in the event of the deposited file having
been deleted (e.g. rejected during workflow)?
= 9.8 The Atom Entry Document
- atom:generator - Should we recommend the use of the standard
'User-Agent' header? A lot easier than multiparting just for the sake of it.
And some responses to your questions:
> 1/ sword:formatNamespace and X-Formatnamespace aren't particularly well named;
> sword:acceptPackaging X-Packaging seem more appropriate. I erred on the side
> of not changing things.
+1
I think we are still just about at the stage where we can get away with
these modifications. Just look at some of the big changes between minor
revision numbered APP docs... :) (e.g. what MIME type service documents
should have)
> 3/ How does the server obtain the identity of the client to use in the
> atom:generator element? There's no header for it.
As above - User-Agent header?
> 4/ I'm ambivalent about whether the error-codes should be in headers or in a
> document. If we want to enforce back-compatibility the headers will have to be
> supported in either case.
Maybe both? Codes in the header, descriptions in the document?
> 5/ Adopting the multipart proposal would solve some issues (e.g. the
> atom:generator issue above). It would mean a bit more complexity to the
> authentication / mediation section. Also, it seems premature to base SWORD on
> a draft RFC. Thoughts?
Yes - perhaps a bit premature, but shows a lot of promise. Also not needed
so much if User-Agent is OK?
> 6/ Pablo at MS requested a "preferred format" feature in the collection
> element of the service document, or alternatively a @preference attribute
> containing an ordinal number. Would others find this useful?
I think it would be useful. Can we come up with some concrete examples where
this is required or very useful in order to help justify it?
Cheers,
Stuart
_________________________________________________________________
Gwasanaethau Gwybodaeth Information Services
Prifysgol Aberystwyth Aberystwyth University
E-bost / E-mail: Stu...@ab...
Ffon / Tel: (01970) 622860
_________________________________________________________________
|
|
From: Jim D. <oj...@ca...> - 2008-08-27 09:47:26
|
Hi Scott, Thanks for the responses and questions. 2008/8/27 Scott Yeadon <sco...@an...> > "1/ sword:formatNamespace and X-Formatnamespace aren't particularly well > named; sword:acceptPackaging X-Packaging seem more appropriate. I erred on > the side of not changing things." > > I like your idea of changing the formatNamespace header/element to > X-Packaging/acceptPackaging, it's much clearer in its meaning. I think it > should be changed in the SWORD APP. We'd have to either require 1.3 implementations to understand both forms, or lose the forward compatibility. > "6/ Pablo at MS requested a "preferred format" feature in the collection > element of the service document, or alternatively a @preference attribute > containing an ordinal number. Would others find this useful?" > > I think support for a list of package formats and order of preference may > be a useful feature, I'd support its inclusion in the spec. I'll come up with a proposal for discussion unless anyone else wants to? > > In section 3.2 is there a typo with the source/generator - the example > represents a server response but the generator value still points to the > client; should the generator in the response be the server? Yes, it's an error. I'm not happy with the use of atom:source as in 1.2: Atom uses this when entries are copied between feeds, not to record user agent data. > > In section 14, there's a typo: "SHOULD MUST" Noted, thanks. > > Some additional comments (others on the list feel free to offer opinions!): > > We have run a pilot project which developed a SWORD plugin for OJS for > depositing journals to a repository (report at > http://pilot.apsr.edu.au/wiki/index.php/SWORD_Report). The issues I see > which are still unresolved in the 1.3 draft are: > > 1) A mechanism for communicating deposit contextual information in SWORD > requests. > To take our journal example - in order for a repository to expose > appropriate deposit targets in a service document it needs to know the > source application (OJS + version), the content type of the packaged object > (journal, issue, article, etc) and the package format (particular flavour of > METS). While X-Packaging can tell us the package format I'd like guidance on > the appropriate place to indicate the source app (currently we are using the > User-Agent HTTP header) and content type (no workaround at the moment). > Implementors may also require further information which I suspect would > typically be satisfied by using key-value pairs within a context header, > e.g. X-Context-Object: type=custom;<key-value pairs> where "type" specifies > a URL or string representing the class of context object and "<key-value > pairs>" is a set of implementation-dependent key/value pairings which may be > used by a SWORD Server implementation for purposes such as constructing more > targetted service documents. So in our OJS deposit we get, for example, > X-Content-Object: type=journal;source=Open Journal Systems SWORD Plugin v2.2 > build 0;content-type=issue > > For implementors the context information is also extremely useful for > assisting in decision-making in workflow paths as well as low-level > operations such as determining which ingestion/service document/deposit > classes to instantiate. So while I appreciate workflows are outside the > scope of the spec, I think there still needs to be some mechanism to allow > SWORD to integrate with workflows and, at least for our purposes, provision > of a context header would go a long way in meeting this need. My gut feeling is that this is a good candidate for an extension, especially if we adopt the AtomPub multipart extension in this / a future revision. > > 2) Support (or maybe just guidance) on supporting structured deposit > responses. > By this I mean consideration of situations where the depositing app and > target repository need to communicate metadata such as the ids/urls of the > deposited material, especially where the deposit resulted in a package being > unpacked into multiple repository objects. In our OJS example, when I > archive a journal issue in DSpace it is unpacked into a single DSpace > collection consisting of multiple DSpace items (the issue articles). OJS > needs to know what objects were created for auditing, avoiding duplicate > deposits and even linking back from the app to the repository versions of > the deposited material. The SWORD spec *could* recommend by example a couple > of ways of obtaining this information on deposit. For example two sample > responses, one showing a single entry pointing to an OAI-ORE resource map > (from which the appropriate information could be derived/extracted) and > another showing a feed document containing entries for created entities > (e.g. http://pilot.apsr.edu.au/public/sword/atom.xml) may satisfy this > requirement. > > While technically this is probably outside the scope of the spec, it gives > implementors some guidance on how to achieve this in a SWORD context and may > provide some consistency in implementations. I think a user guide on this would be very valuable. > > > 3) Is it worth considering explicit support for Collection Listings > I'm wondering if the issue in point 2) above could be addressed through > SWORD including aspects of section 10 (Listing Collections) and section 5.2 > (Listing Collection Members) of the APP spec ( > http://www.ietf.org/rfc/rfc5023.txt). For example, if after a deposit the > requestor sent a List Collection Members GET along with an atom:id, a > repository (assuming they stored the atom:id) could respond with a feed > structure containing entries representing created objects (e.g. see > http://pilot.apsr.edu.au/public/sword/atom.xml). This is a slightly longer > process than returning a feed structure or link to aggregation resource > direct from the deposit but could be an option. I've strengthened the advice to SHOULD from MAY on this. The original motivation for not requiring entry documents and collection listings was to make server implementation as simple as possible. I don't know how important that motivation is now. 4) Governance of the SWORD Content Package Types (ownership, how to get > formats added/registered/etc). Again probably outside the scope of the spec > but worth considering. Agree. Best regards, jim |
|
From: Jim D. <oj...@ca...> - 2008-08-27 09:42:28
|
Hi Antony 2008/8/27 Antony Corfield [awc] <aw...@ab...> > 6/ Pablo at MS requested a "preferred format" feature in the collection > element of the service document, or alternatively a @preference attribute > containing an ordinal number. Would others find this useful? > > > > Wouldn't this confuse things, surely a format should either be supported or > not? How would a preference express it's self in real terms? Sounds like an > MS obfuscation J > Hopefully Pablo is on this list and can fill in some gaps. I think the idea was that you might have a good METS unpackager that e.g. understood full metadata records, and a bagit unpackager that could unbundle the files, but needed some human work afterwards to find the metadata files and help the system with identification and conversion. You'd really rather people used METS, but you could cope with bagit. In specification terms, I'd imagine it would be something like the q weightings in HTTP content negotiation; the server can advertise a weight betwen 0 and 1 for each format (with an implicit default of if it's not defined), and the client can use this information to decide what format to use itself. HTH, jim |
|
From: Antony C. [awc] <aw...@ab...> - 2008-08-27 08:51:12
|
6/ Pablo at MS requested a "preferred format" feature in the collection element of the service document, or alternatively a @preference attribute containing an ordinal number. Would others find this useful? Wouldn’t this confuse things, surely a format should either be supported or not? How would a preference express it’s self in real terms? Sounds like an MS obfuscation :-) Regards, Antony -- Antony Corfield ROAD Project http://road.aber.ac.uk tel. 01970 628724 From: swo...@li... [mailto:swo...@li...] On Behalf Of Jim Downing Sent: 26 August 2008 16:11 To: swo...@li... Cc: sword Subject: Re: [sword-app-tech] [sword] Fwd: SWORD 1.3 Hi all, In this e-mail some open issues, and some reasoning where I've made changes between 1.2 and 1.3. Open issues 1/ sword:formatNamespace and X-Formatnamespace aren't particularly well named; sword:acceptPackaging X-Packaging seem more appropriate. I erred on the side of not changing things. 2/ It would be useful to have a user guide spelling out how to implement "deferred" resource creation, i.e. where the server responds 202 to the original POST. 3/ How does the server obtain the identity of the client to use in the atom:generator element? There's no header for it. 4/ I'm ambivalent about whether the error-codes should be in headers or in a document. If we want to enforce back-compatibility the headers will have to be supported in either case. 5/ Adopting the multipart proposal would solve some issues (e.g. the atom:generator issue above). It would mean a bit more complexity to the authentication / mediation section. Also, it seems premature to base SWORD on a draft RFC. Thoughts? 6/ Pablo at MS requested a "preferred format" feature in the collection element of the service document, or alternatively a @preference attribute containing an ordinal number. Would others find this useful? Explanations * The formatNamespace types will be in a separate document with its own revisions. * The need for co-ordination between the service document and the deposit behaviour with the No-Op feature was potentially dangerous, so I've required all servers to understand X-No-Op even if they don't support it. * On reflection, the guidance on the Slug header wasn't prescriptive enough to be useful, and encouraging use of the Slug as the atom:id was a bad idea. * I streamlined the requirements for mediated deposit - it was impossible for servers to differentiate between the cases listed in 1.2, so I've just recommended a consistent approach that hopefully works for everybody. Thoughts / discussion on any of this very welcome: please direct discussion to the sword-app-tech list, since the ukoln list isn't open. Best regards, jim |
|
From: Scott Y. <sco...@an...> - 2008-08-27 04:38:06
|
Hi Jim, "1/ sword:formatNamespace and X-Formatnamespace aren't particularly well named; sword:acceptPackaging X-Packaging seem more appropriate. I erred on the side of not changing things." I like your idea of changing the formatNamespace header/element to X-Packaging/acceptPackaging, it's much clearer in its meaning. I think it should be changed in the SWORD APP. "6/ Pablo at MS requested a "preferred format" feature in the collection element of the service document, or alternatively a @preference attribute containing an ordinal number. Would others find this useful?" I think support for a list of package formats and order of preference may be a useful feature, I'd support its inclusion in the spec. In section 3.2 is there a typo with the source/generator - the example represents a server response but the generator value still points to the client; should the generator in the response be the server? In section 14, there's a typo: "SHOULD MUST" Some additional comments (others on the list feel free to offer opinions!): We have run a pilot project which developed a SWORD plugin for OJS for depositing journals to a repository (report at http://pilot.apsr.edu.au/wiki/index.php/SWORD_Report). The issues I see which are still unresolved in the 1.3 draft are: 1) A mechanism for communicating deposit contextual information in SWORD requests. To take our journal example - in order for a repository to expose appropriate deposit targets in a service document it needs to know the source application (OJS + version), the content type of the packaged object (journal, issue, article, etc) and the package format (particular flavour of METS). While X-Packaging can tell us the package format I'd like guidance on the appropriate place to indicate the source app (currently we are using the User-Agent HTTP header) and content type (no workaround at the moment). Implementors may also require further information which I suspect would typically be satisfied by using key-value pairs within a context header, e.g. X-Context-Object: type=custom;<key-value pairs> where "type" specifies a URL or string representing the class of context object and "<key-value pairs>" is a set of implementation-dependent key/value pairings which may be used by a SWORD Server implementation for purposes such as constructing more targetted service documents. So in our OJS deposit we get, for example, X-Content-Object: type=journal;source=Open Journal Systems SWORD Plugin v2.2 build 0;content-type=issue For implementors the context information is also extremely useful for assisting in decision-making in workflow paths as well as low-level operations such as determining which ingestion/service document/deposit classes to instantiate. So while I appreciate workflows are outside the scope of the spec, I think there still needs to be some mechanism to allow SWORD to integrate with workflows and, at least for our purposes, provision of a context header would go a long way in meeting this need. 2) Support (or maybe just guidance) on supporting structured deposit responses. By this I mean consideration of situations where the depositing app and target repository need to communicate metadata such as the ids/urls of the deposited material, especially where the deposit resulted in a package being unpacked into multiple repository objects. In our OJS example, when I archive a journal issue in DSpace it is unpacked into a single DSpace collection consisting of multiple DSpace items (the issue articles). OJS needs to know what objects were created for auditing, avoiding duplicate deposits and even linking back from the app to the repository versions of the deposited material. The SWORD spec *could* recommend by example a couple of ways of obtaining this information on deposit. For example two sample responses, one showing a single entry pointing to an OAI-ORE resource map (from which the appropriate information could be derived/extracted) and another showing a feed document containing entries for created entities (e.g. http://pilot.apsr.edu.au/public/sword/atom.xml) may satisfy this requirement. While technically this is probably outside the scope of the spec, it gives implementors some guidance on how to achieve this in a SWORD context and may provide some consistency in implementations. 3) Is it worth considering explicit support for Collection Listings I'm wondering if the issue in point 2) above could be addressed through SWORD including aspects of section 10 (Listing Collections) and section 5.2 (Listing Collection Members) of the APP spec (http://www.ietf.org/rfc/rfc5023.txt). For example, if after a deposit the requestor sent a List Collection Members GET along with an atom:id, a repository (assuming they stored the atom:id) could respond with a feed structure containing entries representing created objects (e.g. see http://pilot.apsr.edu.au/public/sword/atom.xml). This is a slightly longer process than returning a feed structure or link to aggregation resource direct from the deposit but could be an option. 4) Governance of the SWORD Content Package Types (ownership, how to get formats added/registered/etc). Again probably outside the scope of the spec but worth considering. Scott. |
|
From: Jim D. <jim...@po...> - 2008-08-26 15:10:51
|
Hi all, In this e-mail some open issues, and some reasoning where I've made changes between 1.2 and 1.3. Open issues 1/ sword:formatNamespace and X-Formatnamespace aren't particularly well named; sword:acceptPackaging X-Packaging seem more appropriate. I erred on the side of not changing things. 2/ It would be useful to have a user guide spelling out how to implement "deferred" resource creation, i.e. where the server responds 202 to the original POST. 3/ How does the server obtain the identity of the client to use in the atom:generator element? There's no header for it. 4/ I'm ambivalent about whether the error-codes should be in headers or in a document. If we want to enforce back-compatibility the headers will have to be supported in either case. 5/ Adopting the multipart proposal would solve some issues (e.g. the atom:generator issue above). It would mean a bit more complexity to the authentication / mediation section. Also, it seems premature to base SWORD on a draft RFC. Thoughts? 6/ Pablo at MS requested a "preferred format" feature in the collection element of the service document, or alternatively a @preference attribute containing an ordinal number. Would others find this useful? Explanations * The formatNamespace types will be in a separate document with its own revisions. * The need for co-ordination between the service document and the deposit behaviour with the No-Op feature was potentially dangerous, so I've required all servers to understand X-No-Op even if they don't support it. * On reflection, the guidance on the Slug header wasn't prescriptive enough to be useful, and encouraging use of the Slug as the atom:id was a bad idea. * I streamlined the requirements for mediated deposit - it was impossible for servers to differentiate between the cases listed in 1.2, so I've just recommended a consistent approach that hopefully works for everybody. Thoughts / discussion on any of this very welcome: please direct discussion to the sword-app-tech list, since the ukoln list isn't open. Best regards, jim |
|
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>
|
|
From: Julie A. <ja...@yo...> - 2008-08-08 08:12:52
|
Thanks Simeon, that's interesting, particular as we're looking to broaden SWORD so that rather than just focussing on accepting packages, it will be more aligned with APP in accepting deposit of single Atom Entry document or a mutlipart post, which would make accepting ATOM ORE Entry docs more straightforward. Cheers, Julie Simeon Warner wrote: > It occurs to me that an ongoing discussion to revise the Atom serialization of > OAI-ORE Aggregations is relevant to this list too. The discussion thread is > > http://groups.google.com/group/oai-ore/browse_thread/thread/95f7827f64156926 > > and the key idea is to change from using an Atom Feed to represent an > Aggregation and Atom Entries to describe the Aggregated Resources, to > using an Atom Entry to represent an Aggregation and the <link> > elements (perhaps with additional embedded triples) to describe the > Aggregated Resources. > > A benefit of this change would be much improved compatibility with > SWORD (and APP in general) because the "message unit" is an Atom Entry > and not a Feed. > > Something to watch and comments on the ORE list most welcome. > > Cheers, > Simeon > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > sword-app-tech mailing list > swo...@li... > https://lists.sourceforge.net/lists/listinfo/sword-app-tech > -- Julie Allinson <ja...@yo...> Digital Library Manager University Library & Archives, J.B. Morrell Library University of York, Heslington, York, YO10 5DD, UK tel: ++44 (0) 1904 434083 skype: j.allinson web: http://www.york.ac.uk/services/library/elibrary/digitallibrary.htm -- |
|
From: Simeon W. <si...@cs...> - 2008-08-07 19:05:41
|
It occurs to me that an ongoing discussion to revise the Atom serialization of OAI-ORE Aggregations is relevant to this list too. The discussion thread is http://groups.google.com/group/oai-ore/browse_thread/thread/95f7827f64156926 and the key idea is to change from using an Atom Feed to represent an Aggregation and Atom Entries to describe the Aggregated Resources, to using an Atom Entry to represent an Aggregation and the <link> elements (perhaps with additional embedded triples) to describe the Aggregated Resources. A benefit of this change would be much improved compatibility with SWORD (and APP in general) because the "message unit" is an Atom Entry and not a Feed. Something to watch and comments on the ORE list most welcome. Cheers, Simeon |
|
From: Scott Y. <sco...@an...> - 2008-08-07 06:18:07
|
Hi, Building on previous posts, to provide some better context for the SWORD-OJS deposit (http://pilot.apsr.edu.au/wiki/index.php/OJS/OCS_Repository_Deposit_Project), Chris Blackall from APSR has prepared a screencast available at http://www.apsr.edu.au/ore The screencast is pretty self-explanatory however provides better context around the basics of a deposit function in OJS (and OCS) we would like to provide via a SWORD client and server. As posted previously, in order to make this work we had to hack about with the DSpace SWORD Server and also came across what may be limitations in the SWORD API (see http://pilot.apsr.edu.au/wiki/index.php/SWORD_Report for details). We are interested in pursuing the recommendations in this report further within the SWORD 2 project if there is interest. Feel free to contact me on- or off-list with any further queries. Scott. |
|
From: Scott Y. <sco...@an...> - 2008-07-16 06:21:16
|
Hi, Further to the report posted yesterday, some screenshots available at http://pilot.apsr.edu.au/public/sword/sword-ojs.pdf Scott |
|
From: Scott Y. <sco...@an...> - 2008-07-15 06:22:36
|
Hi All, We're currently looking at converting an in-house repository submission workflow prototype to be more standards compliant. Part of this involves the use of SWORD for depositing to DSpace. We have just completed a brief experiment to try and replace an existing OJS-to-DSpace submission component with SWORD. Some background to the project can be found at http://pilot.apsr.edu.au/wiki/index.php/OJS/OCS_Repository_Deposit_Project, and hopefully of interest to the SWORD group and DSpace SWORD developers is a report (http://pilot.apsr.edu.au/wiki/index.php/SWORD_Report) on our experience with trying to utilise SWORD and existing DSpace SWORD server in the submission of OJS Journal Issues to DSpace. We are interested in pursuing the recommendations in this report further within the SWORD 2 project if there is interest. Feel free to contact me on- or off-list with any further queries. Scott. |
|
From: Ian W. <i.w...@st...> - 2008-07-10 12:37:54
|
APOLOGIES: there was an error in the download link in the previous announcement. Here is the correct one: -------------------------------------------------------- Those who attended the IntraLibrary Conference back in February may have seen the debut of our SRU-based search interface to the Learning Exchange, our social services repository running on IntraLibrary: http://www.iriss.ac.uk/openlx We are pleased to announce that the code is now freely available under an open source licence (GNU General Public Licence v3) Full details and download available at http://code.google.com/p/sruopensearch/ We're very keen exchange ideas on further developments, in particular an advanced search (ie words in title, authors etc) and also for a SWORD based deposit client. If you'd like to comment, add to the wish list or share your expertise, drop in to the discussion area http://groups.google.com/group/sru-open-search Regards Ian Watson Knowledge & Information Manager Learning Technology Team | The Institute for Research and Innovation in Social Services| University of Strathclyde | Room D001 | 76 Southbrae Drive | GLASGOW G13 1PP. i.w...@ir... | www.iriss.ac.uk | +44 (0)141 950 3082 | Mob 0779 180 3445 | Map: http://tinyurl.com/2pkdow The Institute for Research and Innovation in Social Services (IRISS) is a charitable company limited by guarantee. Registered in Scotland : No 313740. Scottish Charity No: SC037882. Registered Office: 9 Dudhope Terrace, Dundee, DD3 6HG |
|
From: Ian W. <i.w...@ir...> - 2008-07-10 12:13:07
|
Those who attended the IntraLibrary Conference back in February may have seen the debut of our SRU-based search interface to the Learning Exchange, our social services repository running on IntraLibrary: http://www.iriss.ac.uk/openlx We are pleased to announce that the code is now freely available under an open source licence (GNU General Public Licence v3 http://www.gnu.org/licenses/gpl.html) . Details and download available at http://www.gnu.org/licenses/gpl.htm/ We're very keen exchange ideas on further developments, in particular an advanced search (ie words in title, authors etc) and also for a SWORD based deposit client. If you'd like to comment, add to the wish list or share your expertise, drop in to the discussion area http://groups.google.com/group/sru-open-search . Ian Watson Knowledge & Information Manager Learning Technology Team | The Institute for Research and Innovation in Social Services| University of Strathclyde | Room D001 | 76 Southbrae Drive | GLASGOW G13 1PP. i.w...@ir... | www.iriss.ac.uk | +44 (0)141 950 3082 | Mob 0779 180 3445 | Map: http://tinyurl.com/2pkdow The Institute for Research and Innovation in Social Services (IRISS) is a charitable company limited by guarantee. Registered in Scotland : No 313740. Scottish Charity No: SC037882. Registered Office: 9 Dudhope Terrace, Dundee, DD3 6HG |
|
From: Stuart L. <sd...@ab...> - 2008-07-10 05:05:48
|
Hi! Some more examples following on from Jim's email: > 1. How do i install SWORD in DSpace 1.5 and how can i iteract with it? If you have curl on your machine, to deposit you can use: curl -v --data-binary @example.zip http://localhost:8080/sword/deposit/123456789/2 --user <dspace-username>:<password> An example package package you can deposit can be downloaded from http://www.ukoln.ac.uk/repositories/sword/example.zip Or you can use the Java client (GUI or command line) or you can use the online client but it will need to be able to access you DSpace server from the internet: http://sword.aber.ac.uk/sword/client For looking at the service document, you can just do that from your browser. Enter the relevant URL (something like /dspace-sword/servicedocument). Thanks, Stuart _________________________________________________________________ Gwasanaethau Gwybodaeth Information Services Prifysgol Aberystwyth Aberystwyth University E-bost / E-mail: Stu...@ab... Ffon / Tel: (01970) 622860 _________________________________________________________________ |
13 messages has been excluded from this view by a project administrator.
