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: -
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.
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.
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.
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.
All SWORD extensions are defined within the namespace:
http://purl.org/net/sword/
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.
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.
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.
<?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="1.0">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging>
<sword:acceptPackaging q="0.8">http://purl.org/net/sword-types/bagit</sword:acceptPackaging>
</collection>
</workspace>
</service>
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.
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).
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.
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 X-Packaging: http://purl.org/net/sword-types/mets/dspace
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"/>
<sword:packaging>http://purl.org/net/sword-types/mets/dspace</sword:packaging>
<link rel="edit"
href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" />
</entry>
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.
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].
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).
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.
<?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>
<sword:mediation>true</sword:mediation>
<sword:treatment>treatment description</sword:treatment>
<sword:packaging>http://purl.org/net/sword-types/bagit</sword:packaging>
</collection>
</workspace>
</service>
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.
In this example, user 'jbloggs' is making a deposit on behalf of user 'fdibner'.
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 X-On-Behalf-Of: fdibner [zipped data]
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>
<!-- 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"/>
<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" />
<contributor><name>fdibner</name></contributor>
<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>
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.
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.
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.
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 X-No-Op: true X-Verbose: true [zipped data]
HTTP/1.1 200 Created
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/">
<sword:noOp>true</sword:noOp>
<sword:verboseDescription>
Does collection exist? True.
User authenticates? True.
User: jbloggs
User has rights to collection? True.
</sword:verboseDescription>
<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>
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.
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.
| Error URI | Usage notes |
|---|---|
| http://purl.org/net/sword/error/ErrorContent | The supplied format is not the same as that identified in the X-Packaging header and/or that supported by the server |
| http://purl.org/net/sword/error/ErrorChecksumMismatch | Checksum sent does not match the calculated checksum. The server MUST also return a status code of 412 Precondition Failed. |
| http://purl.org/net/sword/error/ErrorBadRequest | Some parameters sent with the POST were not understood. The server MUST also return a status code of 400 Bad Request. |
| http://purl.org/net/sword/error/TargetOwnerUnknown | Used in mediated deposit (see Part A Section 2) when the server does not know the identity of the X-On-Behalf-Of user. |
| http://purl.org/net/sword/error/MediationNotAllowed | 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. |
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).
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>
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.
<?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>
<sword:service>http://www.myrepository.ac.uk/atom/geography-collection/service.atomsvc</sword:service>
</collection>
</workspace>
</service>
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.
GET to Service Document
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.
GET to Service Document X-On-Behalf-Of: [on-behalf-of-user]
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.
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.
SWORD supports the use of HTTP POST.
POST [URI of Collection] [Request entity]
201 Created Location: [Member Entry URI] [Optional Atom Entry document]
See further refinements to the SWORD use of HTTP POST in Section 9.
The SWORD profile does not require support for the AtomPub mechanisms for modification of resources once created.
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.
See Part A Section 5 for a description of how Error Documents can be used to provide more information about errors.
The SWORD profile does not require server support for Category Documents, and clients MUST NOT require them for deposit operation.
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: -
| Element | Allowed Values | Usage |
|---|---|---|
| sword:version | text | 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. |
| sword:verbose | 'true'|'false' | MAY be included. Indicates whether the server supports the verbose developer feature as described in Part A Section 3.2 |
| sword:noOp | 'true'|'false' | MAY be included. Indicates whether the server supports the No Op developer feature as described in Part A Section 3.1 |
| sword:maxUploadSize | integer | MAY be included to indicate the maximum size (in kB) of package that can be uploaded to the SWORD service. |
As in AtomPub [AtomPub], in SWORD Workspaces are simply named groups of Collections.
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.
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].
SWORD defines the following extensions to the app:collection element:
| Element | Allowed Values | Usage |
|---|---|---|
| sword:collectionPolicy | text | MAY be included. Used for a human-readable description of collection policy. Include either a text description or a URI. |
| sword:mediation | 'true'|'false' | SHOULD be included. Used to indicate if mediated deposit is allowed on the defined collection. |
| sword:treatment | text | MAY be included. Used for a human-readable statement about what treatment the deposited resource will receive. |
| sword:acceptPackaging q="[qvalue]" | URI | 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). |
| sword:service | URI | 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. |
The use of a Dublin Core dcterms:abstract element containing a description of the Collection is RECOMMENDED.
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:
| Header | Allowed Values | Usage |
|---|---|---|
| Content-MD5 | MD5 Checksum of the contents | Clients SHOULD use this header as defined in [HTTP]. Servers SHOULD check it against the request entity if present. |
| Content-Disposition:filename | Text | 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. |
| X-On-Behalf-Of | Text | 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. |
| X-Verbose | 'true'|'false' | 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. |
| X-No-Op | 'true'|'false' | 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. |
| X-Packaging | URI | 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. |
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.
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.
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.
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.
As in Atom, the atom:id element MUST contain a unique identifier for the deposit.
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.
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.
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.
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.
Atom Entry Documents must contain elements as follows: -
| Element | Allowed Values | Usage |
|---|---|---|
| atom:contributor | Text | SHOULD contain the value of the X-On-Behalf-Of header, if one was present in the POST request (See Part A Section 2) |
| atom:generator | Text | SHOULD contain the URI and version of the client. 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. |
| sword:treatment | Text | 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. |
| sword:verboseDescription | Text | 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 |
| sword:noOp | 'true'|'false' | 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. |
| sword:packaging | URI | 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]. |
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.
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.
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]."
Implementers should refer to this section of AtomPub.
[SWORD-TYPES] Allinson, J. et al, SWORD Content Package Types, September 2008. TODO updated publication date and link.
[RFC4387] Nottingham, M. and R. Sayre, "The Atom Syndication Format", RFC 4287, December 2005. [RFC4287]. http://www.ietf.org/rfc/rfc4287.txt (see also non-normative html version at http://APP.org/rfc4287.html)
[AtomPub] Gregario, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, October 2007. http://www.ietf.org/rfc/rfc5023.txt (see also non-normative html version at http://bitworking.org/projects/atom/rfc5023.html)
[RFC2616] Fielding et al, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999 http://www.w3.org/Protocols/rfc2616/rfc2616.html
[RFC2616-10] "HTTP/1.1: Status Code Definitions", part of "Hypertext Transfer Protocol -- HTTP/1.1" RFC 2616 Fielding, et al. http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
[RFC3864] Klyne, G., Nottingham, M. and Mogul, J. "Registration Procedures for Message Header Fields", RFC 3864, September 2004 http://www.rfc-editor.org/rfc/rfc3864.txt
[RFC2183] Troost, R., Dorner, S. and Moore, K., "Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field", RFC 2183, August 1997 http://www.ietf.org/rfc/rfc2183.txt
[OAUTH] Atwood, A., Conlan, R. et al OAuth Core 1.0 http://oauth.net/core/1.0/, December 2007
[ORE] Lagoze, C., Van de Sompel, H et al, Open Archives Initiative Object Reuse and Exchange, http://www.openarchives.org/ore/, June 2008