Commits

Anonymous committed 2732fe7

Sliced core out of previous document.

Comments (0)

Files changed (6)

core-interaction/.#1-POST.txt

+ojd20@heresiar.local.2829

core-interaction/0-service.xml

+<?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/">
+
+ <!-- Retain version? -->
+ <sword:version>2.0</sword:version>
+ <workspace>
+
+   <atom:title>Main Site</atom:title>
+   <collection
+       href="http://www.myrepository.org/atom/geography-collection" >
+     <atom:title>My Repository : Geography Collection</atom:title>
+     <accept alternate="multipart-related">application/zip</accept>
+     <sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
+     <dcterms:abstract>Collection description</dcterms:abstract>
+     <sword:acceptPackaging q="1.0">METSDSpaceSIP</sword:acceptPackaging>
+     <sword:acceptPackaging q="0.8">bagit</sword:acceptPackaging>
+   </collection>
+ </workspace>
+</service>

core-interaction/1-POST.txt

+POST /atom/geography-collection HTTP/1.1
+Host: www.myrepository.org
+Content-Type: multipart/related;
+              boundary="===============1605871705==";
+              type="application/atom+xml"
+Authorization: Basic ZGFmZnk6c2VjZXJldA==
+Content-Length: nnn
+Content-MD5: [md5-digest]
+Content-Disposition: filename=myDSpaceMETSItem.zip
+Slug: My DSpace METS Item
+User-Agent: MyJavaClient/0.1 Restlet/2.0
+
+Media Post
+--===============1605871705==
+Content-Type: application/atom+xml; charset="utf-8"
+MIME-Version: 1.0
+
+<?xml version="1.0"?>
+<entry xmlns="http://www.w3.org/2005/Atom"
+       xmlns:sword="http://purl.org/net/sword/">
+   <title>My Deposit</title>
+   <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
+   <updated>2008-08-18T12:27:08Z</updated>
+   <author><name>jbloggs</name></author>
+   <summary type="text">A summary</summary>
+   <content type="application/zip"
+        src="cid:9797979797@client210.org"/>	
+   <sword:packaging>http://purl.org/net/sword-types/mets/dspace</sword:packaging>
+</entry>
+--===============1605871705==
+Content-Type: application/zip
+MIME-Version: 1.0
+Content-ID: <9797979797@client210.org>
+
+... binary zip data...
+
+Successful response: 
+
+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/myDSpaceMETSItem.zip"/>	
+   <sword:packaging>http://purl.org/net/sword-types/mets/dspace</sword:packaging>
+   <link rel="edit"
+        href="http://www.myrepository.org/geography-collection/atom/my_deposit.atom" />
+   <link rel="manifest"
+         type="application/rdf+ore"
+         href="http://www.myrepository.org/geography-collection/atom/my_deposit.ore.rdf.xml"/>
+</entry>
+
+Unsuccessful response:
+
+HTTP 1.1  400 Bad Request
+<?xml version="1.0" encoding="utf-8"?>
+<sword:error xmlns="http://www.w3.org/2005/Atom"
+       xmlns:sword="http://purl.org/net/sword/"
+       xmlns:arxiv="http://arxiv.org/schemas/atom"
+       href="http://example.org/errors/BadManifest">
+  <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">sword@example.org</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>

core-interaction/1-pwd

Empty file added.

ploughshare-1.0.html

+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+<head>
+<title>Ploughshare AtomPub Profile version 1.0</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>Ploughshare AtomPub Profile version 1.0</h1>
+
+
+<h3>Change control</h3>
+
+<dl>
+	<dt>Version 1.0, published XXXX</dt>
+	
+	<dd>Created from SWORD version 1.3, with substantial revisions
+	to remove AtomPub breakages and take advantage of AtomPub
+	Multipart Extension (RFC XXXX). </dd>
+
+</dl>
+
+<h3>Authors:</h3>
+
+<ul>
+	<li>Jim Downing (University of Cambridge)</li>
+</ul>
+
+<h1>Introduction</h1>
+
+<p>The Atom Publishing Protocol (<a href="#atompub">[AtomPub]</a>)
+provides a simple, extensible mechanism for the creation of Web
+Resources. The Ploughshare profile builds upon AtomPub to support
+situations in which a package of content is deposited with the
+expectation that a number of web resources will be created as a result
+of the deposition. It requires and makes use of multipart/related MIME
+encoding in the creation as specified in
+draft-gregorio-atompub-multipart-04. </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 <a href="#rfc2119">[RFC2119]</a>.</p>
+
+<h1>Document Structure</h1> 
+
+<p>The first part of this document describes the mechanisms that the Ploughshare
+profile adds to AtomPub. The second part follows the structure and numbering of
+the AtomPub specification, highlighting the ways in which the Ploughshare profile
+diverges from AtomPub. </p>
+
+<h2>Ploughshare Namespace</h2>
+
+<p>Extensions in this documenta use the SWORD namespace for historical
+and back-compatibility purposes:</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 <a href="#atompub">[AtomPub]</a>), and the prefix "atom:" is used for
+"http://www.w3.org/2005/Atom" (the namespace name of the Atom Syndication Format
+<a href="#atom">[Atom]</a>). These namespace prefixes are not semantically significant.</p>
+
+
+<h1>Part A: Ploughshare features</h1>
+
+<h2><a id="a.1">1 Package support</a></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 id="a.1.1">1.1 Package support in Service description</h3>
+
+<p>To this end, Ploughshare 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 Ploughshare
+collection will accept deposits of a particular packaging format. The
+value is not defined in this specification. </p>
+
+<p>Servers MAY also use a q attribute with a Quality Value (See <a href="#http">[HTTP1.1]</a>
+section 3.9) on the sword:acceptPackaging element in order to communicate that
+it has a preference between packaging formats. As described in <a href="#http">[HTTP1.1]</a>, the q
+attribute MUST have a short floating-point numeric value between 0 and 1, where
+0 indicates that the server will not handle the format (equivalent to omitting
+that sword:acceptPackaging element completely) and 1 indicates the strongest
+preference. 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. Note that q attribute values only have relative meaning within an
+app:collection element, and absolute values do not imply any particular support
+or treatment. Clients should refer to the sword:treatment description in the
+service document, or perform a No-Op deposit (see <a href="#a.3.1">Part A Section 3.1</a>) to find
+out the treatment for a particular packaging type. </p>
+
+<pre>&lt;?xml version="1.0" encoding='utf-8'?&gt;
+&lt;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/"&gt;
+
+ &lt;sword:version&gt;1.3&lt;/sword:version&gt;
+ &lt;workspace&gt;
+
+   &lt;atom:title&gt;Main Site&lt;/atom:title&gt;
+   &lt;collection
+       href="http://www.myrepository.ac.uk/atom/geography-collection" &gt;
+     &lt;atom:title&gt;My Repository&nbsp;: Geography Collection&lt;/atom:title&gt;
+     &lt;accept alternate="multipart/related"&gt;application/zip&lt;/accept&gt;
+     &lt;sword:collectionPolicy&gt;Collection Policy&lt;/sword:collectionPolicy&gt;
+     &lt;dcterms:abstract&gt;Collection description&lt;/dcterms:abstract&gt;
+     <b>&lt;sword:acceptPackaging q="1.0"&gt;METSDSpaceSIP&lt;/sword:acceptPackaging&gt;</b>
+     <b>&lt;sword:acceptPackaging q="0.8"&gt;bagit&lt;/sword:acceptPackaging&gt;</b>
+   &lt;/collection&gt;
+
+ &lt;/workspace&gt;
+&lt;/service&gt;
+</pre>
+
+
+<h3 id="a.1.2">1.2 Package support during resource creation</h3>
+
+<p>When creating Media Resources (see <a href="#b.9">Part B section
+9</a>), the client SHOULD indicate the archive file MIME type using
+the HTTP "Content-Type" header in the Media part of the
+multipart/related request, and SHOULD also give information about
+content packaging using the sword:packaging element in Entry part of
+the request. This 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 sword:packaging value, it SHOULD
+reject the POST by returning an HTTP with a status code of 415 (Unsupported Media
+Type). </p>
+
+<h3 id="a.1.3">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 id="a.1.4">1.4 Example</h3>
+
+<pre>
+  POST /atom/geography-collection HTTP/1.1
+  Host: www.myrepository.ac.uk
+  <b>Content-Type: multipart/related;
+                boundary="===============1605871705==";
+                type="application/atom+xml"</b>
+  Authorization: Basic ZGFmZnk6c2VjZXJldA==
+  Content-Length: nnn
+  Content-MD5: [md5-digest]
+  Content-Disposition: filename=myDSpaceMETSItem.zip
+  Slug: My DSpace METS Item
+  User-Agent: MyJavaClient/0.1 Restlet/2.0
+
+  Media Post
+  --===============1605871705==
+  Content-Type: application/atom+xml; charset="utf-8"
+  MIME-Version: 1.0
+
+  &lt;?xml version="1.0"?&gt;
+
+   &lt;entry xmlns="http://www.w3.org/2005/Atom"
+	 xmlns:sword="http://purl.org/net/sword/"&gt;
+     &lt;title&gt;My Deposit&lt;/title&gt;
+     &lt;id&gt;urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a&lt;/id&gt;
+
+     &lt;updated&gt;2008-08-18T14:27:08Z&lt;/updated&gt;
+     &lt;author&gt;&lt;name&gt;jbloggs&lt;/name&gt;&lt;/author&gt;
+     &lt;summary type="text"&gt;A summary&lt;/summary&gt;
+     &lt;sword:userAgent&gt;MyJavaClient/0.1 Restlet/2.0&lt;/sword:userAgent&gt;
+     &lt;generator uri="http://www.myrepository.ac.uk/engine" version="1.0"/&gt;
+
+     <b><i>&lt;content type="application/zip"
+        src="cid:9797979797@client210.org"/&gt;</i></b>
+     <b>&lt;sword:packaging&gt;METSDSpaceSIP&lt;/sword:packaging&gt;</b>
+ &lt;/entry&gt;
+
+  --===============1605871705==
+  Content-Type: application/zip
+  MIME-Version: 1.0
+  Content-ID: &lt;<b>9797979797@client210.org</b>&gt;
+
+  ... binary zip 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
+
+  &lt;?xml version="1.0"?&gt;
+
+   &lt;entry xmlns="http://www.w3.org/2005/Atom"
+	 xmlns:sword="http://purl.org/net/sword/"&gt;
+     &lt;title&gt;My Deposit&lt;/title&gt;
+     <b>&lt;id&gt;info:something:1&lt;/id&gt;</b>
+
+     &lt;updated&gt;2008-08-18T14:27:08Z&lt;/updated&gt;
+     &lt;author&gt;&lt;name&gt;jbloggs&lt;/name&gt;&lt;/author&gt;
+     &lt;summary type="text"&gt;A summary&lt;/summary&gt;
+     &lt;sword:userAgent&gt;MyJavaClient/0.1 Restlet/2.0&lt;/sword:userAgent&gt;
+     &lt;generator uri="http://www.myrepository.ac.uk/engine" version="1.0"/&gt;
+
+     &lt;content <b><i>type="application/zip"</i></b>
+        src="http://www.myrepository.ac.uk/geography-collection/deposit1.zip"/&gt;	
+     <b>&lt;sword:packaging&gt;METSDSpaceSIP&lt;/sword:packaging&gt;</b>
+     &lt;link rel="edit"
+        href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" /&gt;
+  &lt;/entry&gt;
+</pre>
+
+<p>N.B. that the server is free to modify any of the contents of the
+POSTed entry document, including the atom:id element, as per AtomPub.
+
+<h2 id="a.5">5 Error documents</h2>
+
+<p>SWORD adds a new class of document to <a href="#atompub">[AtomPub]</a> 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 <a href="#a.2">Part A Section 2</a>) 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 <a href="#b.9.8">Part B Section 9.8</a>), but does not to
+the meet the requirements of Entry Documents (e.g. an atom:id element is not
+required).</p>
+
+<h3 id="a.5.1">5.1 Error Document Example</h3>
+
+<pre>
+HTTP 1.1  400 Bad Request
+&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
+&lt;<b>sword:error</b> xmlns=&quot;http://www.w3.org/2005/Atom&quot;
+       xmlns:sword=&quot;http://purl.org/net/sword/&quot;
+       xmlns:arxiv=&quot;http://arxiv.org/schemas/atom&quot;
+       <b>href="http://example.org/errors/BadManifest"</b>&gt;
+  &lt;author&gt;
+    &lt;name&gt;Example repository&lt;/name&gt;
+  &lt;/author&gt;
+  &lt;title&gt;ERROR&lt;/title&gt;
+  &lt;updated&gt;2008-02-19T09:34:27Z&lt;/updated&gt;
+
+  &lt;generator uri=&quot;https://example.org/sword-app/&quot;
+               version=&quot;0.9&quot;&gt;sword@example.org&lt;/generator&gt;
+
+  &lt;summary&gt;The manifest could be parsed, but was not valid - 
+  no technical metadata was provided.&lt;/summary&gt;
+  &lt;sword:treatment&gt;processing failed&lt;/sword:treatment&gt;
+  &lt;link rel=&quot;alternate&quot; href=&quot;https://arxiv.org/help&quot; type=&quot;text/html&quot;/&gt;
+
+&lt;/sword:error&gt;
+</pre>
+
+<h2 id="a.6">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 id="a.6.1">6.1 Example</h3>
+
+<pre>&lt;?xml version="1.0" encoding='utf-8'?&gt;
+&lt;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/"&gt;
+
+ &lt;sword:version&gt;1.3&lt;/sword:version&gt;
+ &lt;workspace&gt;
+
+   &lt;atom:title&gt;Main Site&lt;/atom:title&gt;
+   &lt;collection
+       href="http://www.myrepository.ac.uk/atom/geography-collection" &gt;
+     &lt;atom:title&gt;My Repository&nbsp;: Geography Collection&lt;/atom:title&gt;
+     &lt;accept alternate="multipart/related"&gt;application/zip&lt;/accept&gt;
+     &lt;sword:collectionPolicy&gt;Collection Policy&lt;/sword:collectionPolicy&gt;
+     &lt;dcterms:abstract&gt;Collection description&lt;/dcterms:abstract&gt;
+     &lt;sword:acceptPackaging q="0.8"&gt;http://purl.org/net/sword-types/bagit&lt;/sword:acceptPackaging&gt;
+     <b>&lt;sword:service&gt;http://www.myrepository.ac.uk/atom/geography-collection/service.atomsvc&lt;/sword:service&gt;</b>
+   &lt;/collection&gt;
+
+ &lt;/workspace&gt;
+&lt;/service&gt;
+</pre>
+
+
+<h1 id="b">Part B: SWORD Profile of AtomPub</h1>
+
+<p>This section is organised according to the sections of the <a href="#atompub">[AtomPub]</a>
+document, highlighting where SWORD varies from AtomPub. If an AtomPub section or
+feature is omitted, implementations MUST behave as defined in AtomPub.</p>
+
+<h2 id="b.5">5. Protocol Operations</h2>
+
+<h3 id="b.5.4">5.4 Editing a Resource</h3>
+
+<p>Informational: The SWORD profile does not require support for the AtomPub mechanisms for
+modification of resources once created, but does not prohibit it - see <a
+href="#b.9.3">Part B Section 9.3</a>. Servers might allow clients to
+GET, PUT and DELETE packaged media resources or not, as a detail of
+implementation. </p>
+
+<h3 id="b.5.5">5.5 Use of HTTP Response Codes</h3>
+
+<p>SWORD builds on the use of response codes specified in <a
+href="#atompub">[AtomPub]</a>, 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 <a href="#a.5">Part A Section 5</a> for a description of how Error
+Documents can be used to provide more information about errors.</p>
+
+<h2 id="b.7">7. Category Documents</h2>
+
+<p>Informational: Server support for Category Documents isn't
+required, and clients shouldn't require them for deposit
+operation.</p>
+
+<h2 id="b.8">8. Service Documents</h2>
+
+<p>Ploughshare 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: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 id="b.8.1">8.1 Workspaces</h3>
+
+<p>As in <a href="#atompub">[AtomPub]</a>, 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.</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.</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: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 <a href="#swordtypes">[SWORD-TYPES]</a>. The
+			q attribute MAY be used to indicate relative preferences
+			between packaging formats (See <a href="#a.1.1">Part A
+			Section 1.1</a>).</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 id="b.9">9. Creating and Editing Resources</h1>
+
+<h2 id="b.9.2">9.2 Creating resources with POST</h2>
+
+<p>Informational: As well as any other headers that might be useful,
+clients are recommended to use some particular HTTP headers as
+follows: -</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 <a
+			href="#http">[HTTP1.1]</a> section 14.15. Servers SHOULD
+			check it against the request entity if present.</td>
+			
+		</tr>
+		<tr>
+			<td>User-Agent</td>
+			<td>Text</td>
+			
+			<td>Clients SHOULD include a User-Agent description
+			header as specified in <a href="#http">[HTTP1.1]</a>
+			section 14.43.</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 <a
+			href="#rfc2183">[RFC2183]</a> section 2.3 to provide a
+			suggested filename for the POSTed entity. Server
+			implementations MUST adopt the behaviour and requirements
+			in <a href="#rfc2183">[RFC2183]</a>.</td>
+			
+		</tr>
+
+	</tbody>
+</table>
+
+<h3 id="b.9.3">9.3 Editing Resources with PUT, 9.4 Deleting Resources with DELETE</h3>
+
+<p>Informational: Server 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 id="b.9.6">9.6 Media Resources and Media Link Entries</h2>
+
+<p>This specification 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 <a href="#atompub">[AtomPub]</a>. The
+server MUST signal the media types it will accept using the app:accept
+element in the Service Document, as specified in <a
+ href="#atompub">[AtomPub]</a> Section 8.3.4, and use the
+alternate="multipart/related" attribute as specified in XXX. Servers
+SHOULD also signal the content package types it will accept using the
+sword:acceptPackaging element, as described in <a href="#b.8.1">Part B
+Section 8.1</a> of this specification.</p>
+
+XXX work here!
+<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 <a
+href="#ore">[ORE]</a>). 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 <a
+href="#atompub">[AtomPub]</a> sections 9.3 and 9.6. </p>
+
+<p>As in <a href="#atom">[Atom]</a>, the atom:id element MUST contain a unique
+identifier for the deposit.</p>
+
+<p>According to <a href="#atompub">[AtomPub]</a>, 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 id="b.9.8">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 <a
+			href="#a.2">Part A Section 2</a>)</td>
+			
+		</tr>
+		<tr>
+			<td>atom:generator</td>
+			<td>Text</td>
+			
+			<td>SHOULD contain the URI and version of the server software.</td>
+			
+		</tr>
+		<tr>
+			<td>sword:userAgent</td>
+			<td>Text</td>
+			
+			<td>Clients SHOULD provide a User-Agent request-header
+			(as described in <a href="#http">[HTTP1.1]</a> section 14.43). If provided,
+			servers SHOULD store the value in the sword:userAgent
+			element.</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 <a
+			href="#a.3.2">Part A Section 3.2</a></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 <a href="#a.3.1">Part A Section
+			3.1</a>. 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 <a href="#swordtypes">[SWORD-TYPES]</a>.</td>
+			
+		</tr>
+		
+	</tbody>
+</table>
+
+<h1 id="b.10">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 <a
+href="#atompub">[AtomPub]</a> compliant. As noted in <a href="#b.5.2">Part B
+Section 5.2</a>, clients MUST NOT rely on Collection Lists in order to make a
+SWORD deposit.</p>
+
+<h1 id="b.11">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 id="b.14">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 <a href="#rfc2617">[RFC2617]</a> in
+conjunction with a TLS connection as specified by <a
+href="#rfc2818">[RFC2818]</a>."</p>
+
+<h1 id="b.15">15. Security Considerations</h1>
+<p>Implementers should refer to this section of AtomPub.</p>
+
+<h2>References</h2> 
+
+<p id="swordtypes">[SWORD-TYPES] Allinson, J. et al, SWORD Content
+Package Types, September 2008. TODO updated publication date and link.</p>
+
+<p id="atom">[Atom] 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. <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 id="atompub">[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 id="http">[HTTP1.1] 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 id="rfc2183">[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 id="oauth">[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 id="ore">[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>
+	
+<p id="rfc2617">[RFC2617] Franks, J. et al, "HTTP Authentication: Basic and
+Digest Access Authentication". <a
+href="http://www.ietf.org/rfc/rfc2617.txt">http://www.ietf.org/rfc/rfc2617.txt</a>
+, June 1999 </p>
+
+<p id="rfc2818">[RFC2818] Rescorla, E. "HTTP over TLS". <a
+href="http://www.ietf.org/rfc/rfc2818.txt">http://www.ietf.org/rfc/rfc2818.txt</a>,
+May 2000.</p>
+
+<p id="rfc2119">[RFC2119] Bradner, S. "Key words for use in RFCs to Indicate
+Requirement Levels". <a
+href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>,
+March 1997.</p>
+
+</body> </html>
+

ploughshare-notes.txt

+Removing requirement for acceptPackaging values to be URIs as a number of the putative schemes for these identifiers are not URIs. 
+
+Adding use of AtomPub Multipart/related (draft-gregorio-atompub-multipart-04) e.g. to service document examples. 
+
+Removing references to SWORD types document so that this can stand as a spec in its own right. 
+
+Leaving in error documents and nested service docs. 
+
+service doc. sword:verbose removed - should be a server implementation detail. 
+sword:noOp - removed with other dev extensions. 
+