-
Notifications
You must be signed in to change notification settings - Fork 0
/
SWORDProfile.html
2534 lines (2007 loc) · 145 KB
/
SWORDProfile.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<title>SWORD 2.0 Profile</title>
<style type="text/css">
body {
font-family: sans-serif;
font-size: 12pt;
}
.toc {
font-size: 10pt;
}
.code {
font-family: monospace;
background: #ffffaa;
padding-left: 15px;
padding-right: 15px;
padding-top: 5px;
padding-bottom: 5px;
margin-top: 5px;
margin-bottom: 5px;
font-size: 10pt;
}
.code_inline {
font-family: monospace;
background: #ffffaa;
padding-right: 5px;
padding-left: 5px;
padding-top: 3px;
padding-bottom: 3px;
font-size: 10pt;
}
</style>
</head>
<body>
<h1>SWORD 2.0 Profile</h1>
<table cellspacing="20" class="toc">
<tr><td valign="top">
<strong><a href="#introduction">1. Introduction</a><br/></strong>
<strong><a href="#notationalconventions">2. Notational Conventions</a></strong><br/>
<strong><a href="#terminology">3. Terminology</a></strong><br/>
<strong><a href="#namespaces">4. Namespaces</a></strong><br/>
<a href="#namespaces_sword">4.1. SWORD Namespaces</a><br/>
<a href="#namespaces_referenced">4.2. Referenced Namespaces</a><br/>
<strong><a href="#iris">5. IRIs</a></strong><br/>
<strong><a href="#protocoloperations">6. Protocol Operations</a></strong><br/>
<a href="#protocoloperations_retreivingservicedocument">6.1. Retrieving a Service Document</a><br/>
<a href="#protocoloperations_listingcollections">6.2. Listing Collections</a><br/>
<a href="#protocoloperations_creatingresource">6.3. Creating a Resource</a><br/>
<a href="#protocoloperations_creatingresource_binary">6.3.1. Creating a Resource with a Binary File Deposit</a><br/>
<a href="#protocoloperations_creatingresource_multipart">6.3.2. Creating a Resource with a Multipart Deposit</a><br/>
<a href="#protocoloperations_creatingresource_entry">6.3.3. Creating a Resource with an Atom Entry</a><br/>
<a href="#protocoloperations_retrievingcontent">6.4. Retrieving the content</a><br/>
<a href="#protocoloperations_retrievingcontent_feed">6.4.1. Atom Feed Representations of Media Resources</a><br/>
<a href="#protocoloperations_editingcontent">6.5. Replacing the Content of a Resource</a><br/>
<a href="#protocoloperations_editingcontent_binary">6.5.1. Replacing the File Content of a Resource</a><br/>
<a href="#protocoloperations_editingcontent_metadata">6.5.2. Replacing the Metadata of a Resource</a><br/>
<a href="#protocoloperations_editingcontent_multipart">6.5.3. Replacing the Metadata and File Content of a Resource</a><br/>
<a href="#protocoloperations_deletingcontent">6.6. Deleting the Content of a Resource</a><br/>
<a href="#protocoloperations_addingcontent">6.7. Adding Content to a Resource</a><br/>
<a href="#protocoloperations_addingcontent_mediaresource">6.7.1. Adding Content to the Media Resource</a><br/>
<a href="#protocoloperations_addingcontent_metadata">6.7.2. Adding New Metadata to a Container</a><br/>
<a href="#protocoloperations_addingcontent_multipart">6.7.3. Adding New Metadata and Packages or Files to a Resource with Multipart</a><br/>
<a href="#protocoloperations_deleteconteiner">6.8. Deleting the Container</a><br/>
<a href="#protocoloperations_statement">6.9. Retrieving the Statement</a><br/>
<a href="#protocoloperations_swordactionableiris">6.10. SWORD Actionable IRIs</a><br/>
<a href="#protocoloperations_arbitrary">6.11. Use of SWORD with arbitrary IRIs</a><br/>
<strong><a href="#packaging">7. Packaging</a></strong><br/>
<a href="#packaging_servicedescription">7.1. Package support in Service description</a><br/>
<a href="#packaging_creation">7.2. Package support during resource creation</a><br/>
<a href="#packaging_entrydocuments">7.3. Package description in Entry documents</a><br/>
<a href="#packaging_negotiation">7.4. Negotiating for package formats</a><br/>
</td><td valign="top">
<strong><a href="#authenticationmediateddeposit">8. Authentication and Mediated Deposit</a></strong><br/>
<a href="#authenticationmediateddeposit_servicedescription">8.1. Mediation In Service Description</a><br/>
<a href="#authenticatedmediateddeposit_recordingusers">8.2. Recording Depositing Users</a><br/>
<strong><a href="#continueddeposit">9. Continued Deposit</a></strong><br/>
<a href="#continueddeposit_complete">9.1. Deposit Complete</a><br/>
<a href="#continueddeposit_incomplete">9.2. Deposit Incomplete</a><br/>
<a href="#continueddeposit_complete">9.3. Completing a Previously Incomplete Deposit</a><br/>
<strong><a href="#depositreceipt">10. Deposit Receipt</a></strong><br/>
<strong><a href="#statement">11. The SWORD Statement</a></strong><br/>
<a href="#statement_predicates">11.1. Predicates used by the Statement</a><br/>
<a href="#statement_predicates_originaldeposit">11.1.1. sword:originalDeposit</a><br/>
<a href="#statement_predicates_state">11.1.2. sword:state</a><br/>
<a href="#statement_predicates_packaging">11.1.3. sword:packaging</a><br/>
<a href="#statement_predicates_depositedon">11.1.4. sword:depositedOn</a><br/>
<a href="#statement_predicates_depositedby">11.1.5. sword:depositedBy</a><br/>
<a href="#statement_predicates_obo">11.1.6. sword:depositedOnBehalfOf</a><br/>
<a href="#statement_predicates_description">11.1.7. sword:stateDescription</a><br/>
<a href="#statement_requirements">11.2. Statement Requirements</a><br/>
<a href="#statement_oaiore">11.3. OAI-ORE Serialisation</a><br/>
<a href="#statement_atom">11.4. Atom Serialisation</a><br/>
<strong><a href="#errordocuments">12. Error Documents</a></strong><br/>
<a href="#errordocuments_uris">12.1. Error URIs</a><br/>
<a href="#errordocuments_uris_content">12.1.1. sword:ErrorContent</a><br/>
<a href="#errordocuments_uris_checksum">12.1.2. sword:ErrorChecksumMismatch</a><br/>
<a href="#errordocuments_uris_badrequest">12.1.3. sword:ErrorBadRequest</a><br/>
<a href="#errordocuments_uris_unknown">12.1.4. sword:TargetOwnerUnknown</a><br/>
<a href="#errordocuments_uris_mediation">12.1.5. sword:MediationNotAllowed</a><br/>
<a href="#errordocuments_uris_notallowed">12.1.6. sword:MethodNotAllowed</a><br/>
<a href="#errordocuments_example">12.2. Error Document Example</a><br/>
<strong><a href="#autodiscovery">13. Auto-Discovery</a></strong><br/>
<a href="#autodiscovery_servicedocuments">13.1. For Service Documents</a><br/>
<a href="#autodiscovery_deposit">13.2. For Deposit Endpoints</a><br/>
<a href="#autodiscovery_resources">13.3. For Resources</a><br/>
<strong><a href="#references">14. References</a></strong>
</td></tr></table>
<h2>Credits</h2>
<p>
<strong>SWORD 2.0 Technical Lead</strong>: Richard Jones, Cottage Labs
</p>
<p>
<strong>SWORD 2.0 Community Manager</strong>: Stuart Lewis, University of Auckland
</p>
<p>
<strong>SWORD 2.0 Technical Advisory Group</strong><br/>
Julie Allinson, University of York<br/>
Tim Brody, University of Southampton<br/>
David Flanders, JISC<br/>
Graham Klyne, University of Oxford<br/>
Alister Miles, University of Oxford<br/>
Ben O'Steen, Cottage Labs<br/>
Mark MacGillivray, Cottage Labs<br/>
Rob Sanderson, LANL<br/>
Nick Sheppard, Leeds Metropolitan University<br/>
Eddie Shin, MediaShelf<br/>
Ian Stuart, University of Edinburgh<br/>
Ed Summers, Library of Congress<br/>
David Tarrant, University of Southampton<br/>
Graham Triggs, BioMed Central<br/>
Scott Wilson, University of Bolton<br/>
</p>
<p>
<strong>Further acknowledgements of input</strong><br/>
Aaron Birkland (Cornell University), Tim Donohue (DuraSpace), Jim Downing (University of Cambridge), Ross Gardler (OSS Watch), Steve Midgley (US Department of Education), Glen Robson (National Library of Wales), Peter Sefton (University Of Southern Queensland), Adrian Stevenson (UKOLN), Paul Walk (UKOLN), Nigel Ward (University of Queensland)
</p>
<h2><a name="introduction">1. Introduction</a></h2>
<p>
The Atom Publishing Protocol ([<a href="#atompub">AtomPub</a>]) provides a simple, extensible mechanism for the creation of Web Resources.
The first major version of SWORD [<a href="#sword13">SWORD 1.3</a>] built upon the Resouce creation aspects of AtomPub to enable package deposit onto a server.
</p>
<p>
This approach of fire-and-forget deposit, where the depositor has no further interaction with the server is of significant value in certain use cases, but there are others where this is insufficient. Consider, for example, that the depositor wishes to construct a digital artifact file by file over a period of time before deciding that it is time to archive it. In these cases, a higher level of interactivity between the participating systems is required, and this is the role that SWORD 2.0 is intended to fulfil.
</p>
<p>
The SWORD 2.0 profile continues to build upon AtomPub and HTTP ([<a href="#rfc2616">RFC2616</a>]) through the inclusion of the Create, Retrieve, Update and Delete (CRUD) operations of AtomPub, in order to enable the following kinds of interactions:
</p>
<ul>
<li>Clients may 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>Workflows which may or may not include manual stages before deposited resources become available as web resources, are acknowledged and supported</li>
<li>Clients may update or delete the compound resources or associated metadata</li>
</ul>
<p>
The role that SWORD aims to fulfil is that of a thin integration layer between any two scholarly systems aiming to exchange content, but not to provide tight integration between them. For standards to integrate detailed content management operations it is recommended to look at OASIS CMIS [<a href="#cmis">CMIS</a>], or the GData API [<a href="#gdata">GData</a>]. In contrast to these, SWORD is a deposit lifecycle standard, which supports the users and the participating systems in effectively exchanging content. Most of the enhancements in SWORD 2.0 over SWORD 1.3 are around closing the deposit loop to give the client software the opportunity to provider a richer environment to the user.
</p>
<p>
The scope of SWORD v2 will be limited to the deposit process between any two scholarly systems or between a user facing system and a service provider. This deposit process is only a portion of the full content lifecycle and does not attempt to provide support for collaborative or distributed authoring environments or policy management; it is focused entirely on the process of moving content from one location to another.
</p>
<p>
The deposit lifecycle encompasses the process of delivering content to a SWORD server which may have an ingest workflow in place. The content that has been deposited is then considered to be in the deposit process for the duration of that ingest workflow, during which time the client system may wish to interact with the submission. It may be that the client needs to make changes to the submission during the workflow process, either autonomously or when prompted for additional input by the server. Or it may be that the client wants to track the progress of the submission, at its leisure. Eventually the content will be formally accepted into the system and the client needs a way to know that this is happened and a route to follow to locate the deposited content.
</p>
<p>
The practical details of the extensions used in the SWORD Profile are provided in the following Internet Drafts:
</p>
<ol>
<li>Packaged Content Delivery over HTTP [<a href="#sword001">SWORD001</a>]</li>
<li>AtomPub Extensions for Packaged Content [<a href="#sword002">SWORD002</a>]</li>
<li>AtomPub Extensions for Scholarly Systems [<a href="#sword003">SWORD003</a>]</li>
<li>Atom Multipart Extensions for Packaged Content [<a href="#sword004">SWORD004</a>]</li>
</ol>
<h2><a name="notationalconventions">2. Notational Conventions</a></h2>
<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>
<h2><a name="terminology">3. Terminology</a></h2>
<p>
Throughout this document we will regularly refer to identifiers which are used by SWORD. The following IRIs are part of the specification:
</p>
<dl>
<dt><strong>SD-IRI</strong></dt>
<dd>The <strong>Service Document IRI</strong>. This is the IRI from which the root service document can be located. If the server supports nesting of service documents, then these sub-service documents are also subject to the same rules as <strong>SD-IRI</strong> and should be considered the same.</dd>
<dt><strong>Col-IRI</strong></dt>
<dd>The IRI of a <strong>SWORD Collection</strong>. This is the IRI to which the initial deposit will take place, and which are listed in the <strong>Service Document</strong>.</dd>
<dt><strong>Cont-IRI</strong><dt>
<dd>The <strong>Content IRI</strong>. This is the IRI from which the client will be able to retrieve representations of the object as it resides in the SWORD server (which representation is returned will be through package format negotiation, as discussed later).</dd>
<dt><strong>EM-IRI</strong></dt>
<dd>The <strong>Atom Edit Media IRI</strong>. This is almost always going to be the same as the <strong>Cont-IRI</strong>, but the Atom spec requires that these identifiers be allowed to differ [<a href="#atompub">AtomPub</a>]. Throughout this document we will mostly refer to the <strong>EM-IRI</strong>. An important thing to note about the <strong>EM-IRI</strong> and the <strong>Cont-IRI</strong> is that they do not refer to the resource as deposited by the client (e.g. the original zip), but to all the content stored in the item on the server, and the format that this IRI returns is obtained by content negotiation. This will be discussed in more detail in <a href="#depositreceipt">Section 10. Deposit Receipt</a>.</dd>
<dt><strong>Edit-IRI</strong></dt>
<dd>The <strong>Atom Entry Edit IRI</strong>. This is the IRI of the Atom Entry of the object, and therefore also of the container within the SWORD server.</dd>
<dt><strong>SE-IRI</strong></dt>
<dd>The <strong>SWORD Edit IRI</strong>. This is the IRI to which clients may POST additional content to an Atom Entry Resource. This MAY be the same as the <strong>Edit-IRI</strong>, but is defined separately as it supports HTTP POST explicitly while the <strong>Edit-IRI</strong> is defined by [<a href="#atompub">AtomPub</a>] as limited to GET, PUT and DELETE operations.</dd>
<dt><strong>State-IRI</strong></dt>
<dd>The <strong>SWORD Statement IRI</strong>. This is one of the IRIs which can be used to retrieve a description of the object from the sword server, including the structure of the object and its state. This may be the same as the IRI used for content management operations that the server implements beyond the behaviours defined by SWORD. See <a href="#statement">Setion 11: The SWORD Statement</a> for more details.</dd>
</dl>
<p>
Note that although there are 7 IRIs defined above, only 2 of them are added by SWORD: <strong>State-IRI</strong> and <strong>SE-IRI</strong>, the rest are replicated from [<a href="#atompub">AtomPub</a>] and are labelled here for convenience. Furthermore, the <strong>SE-IRI</strong> MAY be the same as the <strong>Edit-IRI</strong>. Meanwhile the <strong>EM-IRI</strong> may be the same as the <strong>Cont-IRI</strong>, so implementers can implement the entire specification with only 5 differentiable IRIs.
</p>
<h2><a name="namespaces">4. Namespaces</a></h2>
<h3><a name="namespaces_sword">4.1. SWORD Namespaces</a></h3>
<p>
All SWORD extensions are defined within the namespace:
</p>
<div class="code">
http://purl.org/net/sword/
</div>
<p>
Beneath this URI, we use the following extensions for the various parts of the standard:
</p>
<p>
For all predicates associated with SWORD:
</p>
<div class="code">
http://purl.org/net/sword/terms/
</div>
<p>
This document uses the prefix <strong>sword</strong> for this namespace name; for example <strong>sword:originalDeposit</strong>
</p>
<p>
Root registry for any SWORD recognised package formats including "zip" and "binary":
</p>
<div class="code">
http://purl.org/net/sword/package/
</div>
<p>
Root namespace for any Error documents which SWORD can produce:
</p>
<div class="code">
http://purl.org/net/sword/error/
</div>
<p>
Root namespace for any State terms that SWORD wishes to provide:
</p>
<div class="code">
http://purl.org/net/sword/state/
</div>
<h3><a name="namespaces_referenced">4.2. Referenced Namespaces</a></h3>
<p>
The AtomPub [<a href="#atompub">AtomPub</a>] namespace is:
</p>
<div class="code">
http://www.w3.org/2007/app
</div>
<p>
This document uses the prefix <strong>app</strong> for the namespace name; for example <strong>app:collection</strong>.
</p>
<p>
The Atom Syndication Format [<a href="#atom">Atom</a>] namespace is:
</p>
<div class="code">
http://www.w3.org/2005/Atom
</div>
<p>
This document uses the prefix <strong>atom</strong> for the namespace name; for example <strong>atom:feed</strong>
</p>
<p>
The DCMI Terms [<a href="#dublincore">DublinCore</a>] namespace is:
</p>
<div class="code">
http://purl.org/dc/terms/
</div>
<p>
This document uses the prefix <strong>dcterms</strong> for the namespace name; for example <strong>dcterms:title</strong>
</p>
<p>
The RDF [<a href="#rdf">RDF</a>] namespace is:
</p>
<div class="code">
http://www.w3.org/1999/02/22-rdf-syntax-ns#
</div>
<p>
This document uses the prefix <strong>rdf</strong> for the namespace name; for example <strong>rdf:Description</strong>
</p>
<p>
The OAI-ORE [<a href="#oaiore">OAIORE</a>] namespace is:
</p>
<div class="code">
http://www.openarchives.org/ore/terms/
</div>
<p>
This document uses the prefix <strong>ore</strong> for the namespace name; for example <strong>ore:aggregates</strong>
</p>
<h2><a name="iris">5. IRIs</a></h2>
<p>
The packaging format which represents a binary file which should not be unpacked by the server
</p>
<div class="code">
http://purl.org/net/sword/package/Binary
</div>
<p>
The primitive SWORD packaging format, which represents a plain ZIP file during resource creation or update, and in Atom Multipart [<a href="#atommultipart">AtomMultipart</a>] deposit indicates that the Media Part is a plain ZIP file.
</p>
<div class="code">
http://purl.org/net/sword/package/SimpleZip
</div>
<h2><a name="protocoloperations">6. Protocol Operations</a></h2>
<p>
While specific HTTP status codes are used below, a SWORD client should be prepared to handle any status code as per the HTTP status code definitions [<a href="#rfc2616">RFC2616</a>]
</p>
<h3><a name="protocoloperations_retreivingservicedocument">6.1. Retrieving a Service Document</a></h3>
<em>See Sections 5.1 and 8 of [<a href="#atompub">AtomPub</a>], for details.</em>
<ol>
<li>The client sends a GET request to the IRI of the Service Document.</li>
<li>The server responds with a Service Document enumerating the IRIs of a group of Collections and the capabilities of those Collections supported by the server. The content of this document can vary based on aspects of the client request, including, but not limited to, authentication credentials.</li>
</ol>
<p>
The client may also supply the <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>] to provide the username of a target user on whose behalf a deposit will be made. See <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a> for more details.
</p>
<div class="code">
<pre>
GET SD-IRI HTTP/1.1
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Host: example.org
<strong>On-Behalf-Of: [username]</strong>
</pre>
</div>
<p>
When a server that supports mediated deposit receives an <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>], 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 <span class="code_inline">sword:mediation</span> [<a href="#sword002">SWORD002</a>] extension element with a value of <span class="code_inline">false</span>.
</p>
<p>
The service document supplied in response MUST meet the following criteria in addition to those specified in [<a href="#atompub">AtomPub</a>]:
</p>
<ul>
<li>The SWORD server MUST specify the <span class="code_inline">sword:version</span> element with a value of <span class="code_inline">2.0</span> [<a href="#sword003">SWORD003</a>]</li> as a child of the <span class="code_inline">app:service</span> element.
<li>The SWORD server MAY specify the <span class="code_inline">sword:maxUploadSize</span> (in kB) of content that can be uploaded in one request [<a href="#sword003">SWORD003</a>] as a child of the <span class="code_inline">app:service</span> element. If provided this MUST contain an integer.</li>
<li>The SWORD server MUST specify the <span class="code_inline">app:accept</span> element for the <span class="code_inline">app:collection</span> element. If the Collection can take any format content type, it should specify <span class="code_inline">*/*</span> as its value [<a href="#atompub">AtomPub</a>]. It MUST also specify an <span class="code_inline">app:accept</span> element with an <span class="code_inline">alternate</span> attribute set to <span class="code_inline">multipart-related</span> as required by [<a href="#atommultipart">AtomMultipart</a>]. The formats specified by <span class="code_inline">app:accept</span> and <span class="code_inline">app:accept@alternate="multipart-related"</span> are RECOMMENDED to be the same.</li>
<li>The SWORD server MAY include one <span class="code_inline">sword:collectionPolicy</span> [<a href="#sword003">SWORD003</a>] as a child of the <span class="code_inline">app:collection</span> element</li>
<li>The SWORD server SHOULD include one <span class="code_inline">sword:mediation</span> element as a child of the <span class="code_inline">app:collection</span> element with a value of <span class="code_inline">true</span> or <span class="code_inline">false</span> [<a href="#sword002">SWORD002</a>]</li>
<li>The SWORD server MAY include one <span class="code_inline">sword:treatment</span> element [<a href="#sword003">SWORD003</a>]as a child of the <span class="code_inline">app:collection</span> element</li>
<li>The SWORD server MAY include zero or more <span class="code_inline">sword:acceptPackaging</span> elements [<a href="#sword002">SWORD002</a>] as a children of the <span class="code_inline">app:collection</span> element. The value SHOULD be a IRI for a known packaging format (where such IRIs exist)</li>
<li>The SWORD server MAY include zero or more <span class="code_inline">sword:service</span> [<a href="#sword003">SWORD003</a>] elements as children of the <span class="code_inline">app:collection</span> element containing references to nested service descriptions</li>
</ul>
<p>
Example:
</p>
<div class="code">
<pre>
HTTP 1.1 200 OK
Content-Type: application/atomserv+xml
<?xml version="1.0" ?>
<service xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:sword="http://purl.org/net/sword/terms/"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://www.w3.org/2007/app">
<sword:version>2.0</sword:version>
<sword:maxUploadSize>16777216</sword:maxUploadSize>
<workspace>
<atom:title>Main Site</atom:title>
<collection href="http://swordapp.org/col-iri/43">
<atom:title>Collection 43</atom:title>
<accept>*/*</accept>
<accept alternate="multipart-related">*/*</accept>
<sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
<dcterms:abstract>Collection Description</dcterms:abstract>
<sword:mediation>false</sword:mediation>
<sword:treatment>Treatment description</sword:treatment>
<sword:acceptPackaging>http://purl.org/net/sword/package/SimpleZip</sword:acceptPackaging>
<sword:acceptPackaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:acceptPackaging>
<sword:service>http://swordapp.org/sd-iri/e4</sword:service>
</collection>
</workspace>
</service>
</pre>
</div>
<p>
The following requirements are placed on the client in receipt of a service document:
</p>
<ul>
<li>If no <span class="code_inline">sword:maxUploadSize</span> is specified, the client MUST assume that no size limit exists, but this specification RECOMMENDS that clients limit themselves to reasonably small file sizes unless special arrangements with the server have been made.</li>
<li>If no <span class="code_inline">sword:mediation</span> element is specified, the client MUST assume a value of <span class="code_inline">false</span>.
<li>If no <span class="code_inline">sword:acceptPackaging</span> element is specified, the client MUST assume that the server will not formally support packaging formats (see <a href="#iris">Section 5: IRIs</a> and <a href="#packaging">Section 7: Packaging</a> for more details).</li>
<li>The client SHOULD NOT attempt to deposit files with a packaging format that is not in the <span class="code_inline">sword:acceptPackaging</span> elements, although the client MAY specify the binary package format (see <a href="#iris">Section 5: IRIs</a> and <a href="#packaging">Section 7: Packaging</a> for more details) in order to deposit opaquely packaged content</li>
</ul>
<h3><a name="protocoloperations_listingcollections">6.2 Listing Collections</a></h3>
<em>See Section 5.2 of [<a href="#atompub">AtomPub</a>] for details.</em>
<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><a name="protocoloperations_creatingresource">6.3. Creating a Resource</a></h3>
<h4><a name="protocoloperations_creatingresource_binary">6.3.1. Creating a Resource with a Binary File Deposit</a></h4>
<em>See Sections 5.3 and 9.2 of [<a href="#atompub">AtomPub</a>] for details.</em>
<p>
The client can create a resource by POSTing the binary content as the body of an HTTP request to the <strong>Col-IRI</strong>, with the <span class="code_inline">Content-Type</span>, <span class="code_inline">Content-Disposition</span>, and <span class="code_inline">Packaging</span> headers, with the following requirements:
</p>
<ul>
<li>The client SHOULD supply a <span class="code_inline">Content-Type</span> header</li>
<li>The client MUST supply a <span class="code_inline">Content-Disposition</span> header with a <span class="code_inline">filename</span> parameter (note that this requires the filename be expressed in ASCII).</li>
<li>The client SHOULD supply a <span class="code_inline">Content-MD5</span> header with the MD5 checksum hex encoded for the binary content</li>
<li>The client SHOULD supply a <span class="code_inline">Packaging</span> header [<a href="#sword001">SWORD001</a>] providing the IRI (or other allowed) of the packaging format used. See <a href="#packaging">Section 7: Packaging</a> for more details.</li>
<li>The client MAY provide an <span class="code_inline">In-Progress</span> header with a value of <span class="code_inline">true</span> or <span class="code_inline">false</span> [<a href="#sword001">SWORD001</a>]. See <a href="#continueddeposit">Section 9: Continued Deposit</a> for more details.</li>
<li>The client MAY provide an <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>]. See <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a> for more details.</li>
<li>The client MAY supply a <span class="code_inline">Slug</span> header providing a suggested identifier for the deposited content</li>
</ul>
<div class="code">
<pre>
POST Col-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/zip
Content-Length: [content length]
Content-MD5: [md5-digest]
Content-Disposition: attachment; filename=[filename]
Packaging: http://purl.org/net/sword/package/METSDSpaceSIP
In-Progress: true
On-Behalf-Of: jbloggs
Slug: [suggested identifier]
[request entity]
</pre>
</div>
<p>
The requirements placed on the server here are:
</p>
<ul>
<li>If no <span class="code_inline">Content-Type</span> header is supplied the server MUST behave as per Section 7.2.1 in [<a href="#rfc2616">RFC2616</a>]</li>
<li>The server SHOULD verify the <span class="code_inline">Content-MD5</span> header against the content. If the check fails, the server MUST respond with 412 Precondition Failed. See <a href="#errordocuments">Section 12: Error Documents</a>.</li>
<li>Server implementations MUST adopt the behaviour and requirements in [<a href="#rfc2183">RFC2183</a>] with respect to the <span class="code_inline">Content-Disposition</span> header.</li>
<li>If there is no <span class="code_inline">Packaging</span> header, the server SHOULD assume that it is the binary packaging format (See <a href="#iris">Section 5: IRIs<a/></li>
<li>Server implementations MUST adopt the behaviour and requirements in Section 9.7 of [<a href="#atompub">AtomPub</a>] with respect to the <span class="code_inline">Slug</span> header.</li>
<li>If there is no <span class="code_inline">In-Progress</span> header, the server MUST assume that it is <span class="code_inline">false</span>, and MUST behave as described in <a href="#continueddeposit">Section 9: Continued Deposit</a></li>
<li>The server MUST carry out authentication and mediated deposit as described in <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a></li>
<li>The server MUST create a new resource containing content equivalent to or derived from the deposited content, or return an error document.</li>
</ul>
<p>
Once the server has processed the request it SHOULD return a Deposit Receipt as described in <a href="#depositreceipt">Section 10: Deposit Receipt</a> with the HTTP status code <span class="code_inline">201 (Created)</span>. The Deposit Receipt MUST be available under the <strong>Edit-IRI</strong> (Member Entry IRI), as supplied in the <span class="code_inline">Location</span> header.
</p>
<p>
For example:
</p>
<div class="code">
<pre>
201 Created
Location: [Edit-IRI]
[optional Deposit Receipt]
</pre>
</div>
<h4><a name="protocoloperations_creatingresource_multipart">6.3.2. Creating a Resource with a Multipart Deposit</a></h4>
<em>See [<a href="#atommultipart">AtomMultipart</a>] for details.</em>
<p>
In order to ensure that all SWORD clients and servers can exchange a full range of file content and metadata, the use of Atom Multipart [<a href="#atommultipart">AtomMultipart</a>] is permitted to combine a package (possibly a simple ZIP) with a set of Dublin Core metadata terms [<a href="#dublincore">DublinCore</a>] embedded in an Atom Entry.
</p>
<p>
The SWORD server is not required to support packaging formats, but this profile RECOMMENDS that the server be able to accept a ZIP file as the Media Part of an Atom Multipart request (See <a href="#iris">Section 5: IRIs</a> and <a href="#packaging">Section 7: Packaging</a> for more details).
<p>
The client can create a resource by POSTing a multipart mime message to the <strong>Col-IRI</strong> with two parts: An Atom Entry containing the metadata for the deposit (known as the <strong>Entry Part</strong>), and the binary content as the second part (known as the <strong>Media Part</strong>), with the following requirements:
</p>
<ul>
<li>The client MUST comply with the rules laid out in [<a href="#atommultipart">AtomMultipart</a>]</li>
<li>The client MUST supply a <span class="code_inline">Content-Disposition</span> header of type <span class="code_inline">attachment</span> on the Entry Part with a <span class="code_inline">name</span> parameter set to <span class="code_inline">atom</span> [<a href="#sword004">SWORD004</a>]</li>
<li>The client MUST supply a <span class="code_inline">Content-Disposition</span> header of type <span class="code_inline">attachment</span> on the Media Part with a <span class="code_inline">name</span> parameter set to <span class="code_inline">payload</span> and a <span class="code_inline">filename</span> parameter [<a href="#sword004">SWORD004</a>] (note that this requires the filename be expressed in ASCII).</li>
<li>The client SHOULD supply a <span class="code_inline">Content-MD5</span> header with the MD5 checksum hex encoded for the binary content on the Media Part</span>
<li>The client SHOULD supply a <span class="code_inline">Packaging</span> header [<a href="#sword001">SWORD001</a>] providing the IRI (or other allowed) of the packaging format used on the Media Part</li>
<li>The client MAY provide an <span class="code_inline">In-Progress</span> header with a value of <span class="code_inline">true</span> or <span class="code_inline">false</span> [<a href="#sword001">SWORD001</a>] on the main HTTP header</li>
<li>The client MAY provide an <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>] on the main HTTP header</li>
<li>The client MAY supply a <span class="code_inline">Slug</span> header providing a suggested identifier for the deposited content on the main HTTP header</li>
<li>The client SHOULD add Dublin Core [<a href="#dublincore">DublinCore</a>] terms to the Atom Entry as foreign markup (if appropriate); the terms MUST be embedded as direct children of the <span class="code_inline">atom:entry</span> element, if present.</li>
<li>The client MAY add any other metadata formats or foreign markup to the <span class="code_inline">atom:entry</span> element</li>
</ul>
<p>
For example:
</p>
<div class="code">
<pre>
POST Col-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: multipart/related;
boundary="===============1605871705==";
type="application/atom+xml"
In-Progress: true
On-Behalf-Of: jbloggs
Slug: [suggested identifier]
MIME-Version: 1.0
Media Post
--===============1605871705==
Content-Type: application/atom+xml; charset="utf-8"
Content-Disposition: attachment; name="atom"
MIME-Version: 1.0
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:dcterms="http://purl.org/dc/terms/">
<title>Title</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Contributor</name></author>
<summary type="text">The abstract</summary>
<!-- some embedded metadata -->
<dcterms:abstract>The abstract</dcterms:abstract>
<dcterms:accessRights>Access Rights</dcterms:accessRights>
<dcterms:alternative>Alternative Title</dcterms:alternative>
<dcterms:available>Date Available</dcterms:available>
<dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
<dcterms:contributor>Contributor</dcterms:contributor>
<dcterms:description>Description</dcterms:description>
<dcterms:hasPart>Has Part</dcterms:hasPart>
<dcterms:hasVersion>Has Version</dcterms:hasVersion>
<dcterms:identifier>Identifier</dcterms:identifier>
<dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
<dcterms:publisher>Publisher</dcterms:publisher>
<dcterms:references>References</dcterms:references>
<dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
<dcterms:source>Source</dcterms:source>
<dcterms:title>Title</dcterms:title>
<dcterms:type>Type</dcterms:type>
</entry>
--===============1605871705==
Content-Type: application/zip
Content-Disposition: attachment; name=payload; filename=[filename]
Packaging: http://purl.org/net/sword/package/SimpleZip
Content-MD5: [md5-digest]
MIME-Version: 1.0
[...binary package data...]
--===============1605871705==--
</pre>
</div>
<p>
The requirements placed on the server here are:
</p>
<ul>
<li>The server SHOULD verify the <span class="code_inline">Content-MD5</span> header against the Media Part. If the check fails, the server MUST respond with 412 Precondition Failed. See <a href="#errordocuments">Section 12: Error Documents</a>.</li>
<li>Server implementations MUST adopt the behaviour and requirements in [<a href="#rfc2183">RFC2183</a>] with respect to the <span class="code_inline">Content-Disposition</span> header for the Media Part</li>
<li>If there is no <span class="code_inline">Packaging</span> header on the Media Part, the server SHOULD assume that it is the binary packaging format (See <a href="#iris">Section 5: IRIs</a>)</li>
<li>Server implementations MUST adopt the behaviour and requirements in Section 9.7 of [<a href="#atompub">AtomPub</a>] with respect to the <span class="code_inline">Slug</span> header</li>
<li>If there is no <span class="code_inline">In-Progress</span> header, the server MUST assume that it is <span class="code_inline">false</span>, and MUST behave as described in <a href="#continueddeposit">Section 9: Continued Deposit</a></li>
<li>If there is an <span class="code_inline">On-Behalf-Of</span> header, the server MUST behave as described in <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a></li>
<li>The server MUST create a new resource containing content equivalent to or derived from the deposited content, or return an error document.</li>
<li>The server MUST be able to record and later reflect the Dublin Core [<a href="#dublincore">DublinCore</a>] foreign markup in the <span class="code_inline">atom:entry</span> element, but MAY NOT understand any other embedded formats.</li>
</ul>
<p>
Once the server has processed the request it SHOULD return a Deposit Receipt as described in <a href="#depositreceipt">Section 10: Deposit Receipt</a> with the HTTP status code <span class="code_inline">201 (Created)</span>. The Deposit Receipt MUST be available under the <strong>Edit-IRI</strong> (Member Entry IRI), as supplied in the <span class="code_inline">Location</span> header.
</p>
<p>
For example:
</p>
<div class="code">
<pre>
201 Created
Location: [Edit-IRI]
[optional Deposit Receipt]
</pre>
</div>
<h4><a name="protocoloperations_creatingresource_entry">6.3.3. Creating a Resource with an Atom Entry</a></h4>
<em>See Sections 5.3 and 9.2 of [<a href="#atompub">AtomPub</a>] for details.</em>
<p>
Clients can create a container within a SWORD server and optionally provide it with metadata without adding any binary content to it. This is done by POSTing an Atom Entry to the <strong>Col-IRI</strong> with the following requirements:
</p>
<ul>
<li>The client SHOULD supply a <span class="code_inline">Content-Type</span> header with the value <span class="code_inline">application/atom+xml;type=entry</span></li>
<li>The client MAY provide an <span class="code_inline">In-Progress</span> header with a value of <span class="code_inline">true</span> or <span class="code_inline">false</span> [<a href="#sword001">SWORD001</a>]. See <a href="#continueddeposit">Section 9: Continued Deposit</a> for more details.</li>
<li>The client MAY provide an <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>]. See <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a> for more details.</li>
<li>The client MAY supply a <span class="code_inline">Slug</span> header providing a suggested identifier for the deposited content</li>
<li>The client SHOULD add Dublin Core [<a href="#dublincore">DublinCore</a>] terms to the Atom Entry as foreign markup (if appropriate); the terms MUST be embedded as direct children of the <span class="code_inline">atom:entry</span> element, if present.</li>
<li>The client MAY add any other metadata formats or foreign markup to the <span class="code_inline">atom:entry</span> element</li>
</ul>
<p>
For example:
</p>
<div class="code">
<pre>
POST Col-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: application/atom+xml;type=entry
In-Progress: true
On-Behalf-Of: jbloggs
Slug: [suggested identifier]
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:dcterms="http://purl.org/dc/terms/">
<title>Title</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Contributor</name></author>
<summary type="text">The abstract</summary>
<!-- some embedded metadata -->
<dcterms:abstract>The abstract</dcterms:abstract>
<dcterms:accessRights>Access Rights</dcterms:accessRights>
<dcterms:alternative>Alternative Title</dcterms:alternative>
<dcterms:available>Date Available</dcterms:available>
<dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
<dcterms:contributor>Contributor</dcterms:contributor>
<dcterms:description>Description</dcterms:description>
<dcterms:hasPart>Has Part</dcterms:hasPart>
<dcterms:hasVersion>Has Version</dcterms:hasVersion>
<dcterms:identifier>Identifier</dcterms:identifier>
<dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
<dcterms:publisher>Publisher</dcterms:publisher>
<dcterms:references>References</dcterms:references>
<dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
<dcterms:source>Source</dcterms:source>
<dcterms:title>Title</dcterms:title>
<dcterms:type>Type</dcterms:type>
</entry>
</pre>
</div>
<p>
The requirements placed on the server here are:
</p>
<ul>
<li>Server implementations MUST adopt the behaviour and requirements in Section 9.7 of [<a href="#atompub">AtomPub</a>] with respect to the <span class="code_inline">Slug</span> header</li>
<li>If there is no <span class="code_inline">In-Progress</span> header, the server MUST assume that it is <span class="code_inline">false</span>, and MUST behave as described in <a href="#continueddeposit">Section 9: Continued Deposit</a></li>
<li>If there is an <span class="code_inline">On-Behalf-Of</span> header, the server MUST behave as described in <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a></li>
<li>The server MUST create a new resource, or return an error document.</li>
<li>The server MUST be able to record and later reflect the Dublin Core [<a href="#dublincore">DublinCore</a>] foreign markup in the <span class="code_inline">atom:entry</span> element, but MAY NOT understand any other embedded formats.</li>
<li>The server MUST supply an <strong>EM-IRI</strong> for the client to use in future update operations, even though this EM-IRI may at this stage not return any content under HTTP GET.</li>
</ul>
<p>
Once the server has processed the request it SHOULD return a Deposit Receipt as described in <a href="#depositreceipt">Section 10: Deposit Receipt</a> with the HTTP status code <span class="code_inline">201 (Created)</span>. The Deposit Receipt MUST be available under the <strong>Edit-IRI</strong> (Member Entry IRI), as supplied in the <span class="code_inline">Location</span> header.
</p>
<p>
For example:
</p>
<div class="code">
<pre>
201 Created
Location: [Edit-IRI]
[optional Deposit Receipt]
</pre>
</div>
<h3><a name="protocoloperations_retrievingcontent">6.4. Retrieving the content</a></h3>
<em>See section 5.4 of [<a href="#atompub">AtomPub</a>] for details.</em>
<p>
The Deposit Receipt contains two IRIs which can be used to retrieve content from the server: <strong>Cont-IRI</strong> and <strong>EM-IRI</strong>. These are provided in the <span class="code_inline">atom:content@src</span> element and the <span class="code_inline">atom:link@rel="edit-media"</span> elements respectively. Their only functional difference is that the client MUST NOT carry out any HTTP operations other than GET on the <strong>Cont-IRI</strong>, while all operations are permitted on the <strong>EM-IRI</strong>. It is acceptable, but not required, that both IRIs to be the same, and in this section we refer only to the <strong>EM-IRI</strong> but in all cases it can be substituted for the <strong>Cont-IRI</strong>.
</p>
<p>
The Deposit Receipt contains zero or more <span class="code_inline">sword:packaging</span> elements [<a href="#sword002">SWORD002</a>], indicating to the client what package formats can be retrieved from the server. For example:
</p>
<div class="code">
<pre>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
[...]
<content type="application/zip" src="http://swordapp.org/cont-IRI/43/my_deposit"/>
<link rel="edit-media" href="http://swordapp.org/em-IRI/43/my_deposit"/>
<sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
<sword:packaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:packaging>
<sword:packaging>http://purl.org/net/sword/package/BagIt</sword:packaging>
</entry>
</pre>
</div>
<p>
Requests to retrieve the Media Resource here refer to the Media Resource <em>as a whole</em>, as per [<a href="#atompub">AtomPub</a>], and not to any of the component parts of a complex Media Resource. That is, the response to a request for the Media Resource should be considered a representation of the entire content of the object on the server, and it is not permissable to attempt to content negotiate for a particular part of the Media Resource. Implementers who wish to access the parts of a Media Resource should see <a href="#protocoloperations_retrievingcontent_feed">Section 6.4.1. Atom Feed Representations of Media Resources</a> below.
</p>
<p>
To retrieve the content in the desired packaging format, the client makes an HTTP GET request to the <strong>EM-IRI</strong> and MAY supply an <span class="code_inline">Accept-Packaging</span> header [<a href="#sword001">SWORD001</a>] with the IRI from one of the <span class="code_inline">sword:packaging</span> elements.
</p>
<p>
If the content is not in a publicly available space on the server, the user agent may be required to authenticate. In these cases the client MAY supply the <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>] for informational purposes.
</p>
<p>
The server will respond in different ways depending on a number of conditions:
</p>
<ol>
<li>If the <span class="code_inline">Accept-Packaging</span> header is not supplied, the server SHOULD assume a simple ZIP packaging format (see <a href="#iris">Section 5: IRIs</a>), but MAY elect another format if it wishes. The server MUST then supply the client with a package which meets these specifications, and SHOULD provide the SimpleZip IRI in a <span class="code_inline">Packaging</span> header on the response.</li>
<li>If the <span class="code_inline">Accept-Packaging</span> header is supplied, and contains the IRI (or other allowed value) of a format that the server supports, the server MUST then supply the client with a package which meets these specifications, and SHOULD provide an IRI (or other allowed value) of the format being returned in a <span class="code_inline">Packaging</span> header on the response.</li>
<li>If the <span class="code_inline">Accept-Packaging</span> header is supplied but contains a IRI (or other allowed value) for a format that the server does not support, the server MUST respond with 406 Not Acceptable and MAY include an error document as per <a href="#errordocuments">Section 12: Error Documents</a>.</li>
</ol>
<p>
Upon receiving a successful response, if no <span class="code_inline">Packaging</span> header is provided in the response the client SHOULD assume that it is a SimpleZip.
</p>
<p>
For more details about the packaging process, see <a href="#packaging">Section 7: Packaging</a>
</p>
<h4><a name="protocoloperations_retrievingcontent_feed">6.4.1. Atom Feed Representations of Media Resources</a></h4>
<em>See sections 11.2 and 12.1 of [<a href="#atompub">AtomPub</a>] for details.</em>
<p>
It is RECOMMENDED that implementations provide an EM-IRI in the Deposit Receipt with a type of <span class="code_inline">application/atom+xml;type=feed</span> in addition to any other types available.
</p>
<p>For example, the Depoisit Receipt would contain:</p>
<div class="code">
<pre>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/">
[...]
<link rel="edit-media" href="http://swordapp.org/em-IRI/43/my_deposit"/>
<link rel="edit-media" type="application/atom+xml;type=feed" href="http://swordapp.org/em-IRI/43/my_deposit.feed"/>
[...]
</entry>
</pre>
</div>
<p>
The exact contents of the Feed representation are unspecified, but it is RECOMMENDED that this is a list of <span class="code_inline">atom:entry</span> elements which represent the individual media items which together form the Media Resource. Each <span class="code_inline">atom:entry</span> element MUST have an edit-media IRI which SHOULD be actionable as per <a href="protocoloperations_swordactionableiris">Section 6.10</a>.
</p>
<p>
NOTE that this is not the same as the Statement, which is a representation of the entire object on the server, not just the Media Resource. See <a href="#statement">Section 11: The SWORD Statement</a> for details
</p>
<h3><a name="protocoloperations_editingcontent">6.5. Replacing the Content of a Resource</a></h3>
<h4><a name="protocoloperations_editingcontent_binary">6.5.1. Replacing the File Content of a Resource</a></h4>
<em>See section 5.4 and 9.3 of [<a href="#atompub">AtomPub</a>] for details.</em>
<p>
The client can replace the existing content of a resource by performing an HTTP PUT of some new binary content to the <strong>EM-IRI</strong>, with the following requirements:
</p>
<ul>
<li>The client SHOULD supply a <span class="code_inline">Content-Type</span> header</li>
<li>The client MUST supply a <span class="code_inline">Content-Disposition</span> header with a <span class="code_inline">filename</span> parameter (note that this requires the filename be expressed in ASCII).</li>
<li>The client SHOULD supply a <span class="code_inline">Content-MD5</span> header with the MD5 checksum hex encoded for the binary content</li>
<li>The client SHOULD supply a <span class="code_inline">Packaging</span> header [<a href="#sword001">SWORD001</a>] providing the IRI (or other allowed) of the packaging format used</li>
<li>The client MAY provide an <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>]</li>
<li>The client MAY provide a <span class="code_inline">Metadata Relevant</span> header [<a href="#sword001">SWORD001</a>] with the value <span class="code_inline">true</span> or <span class="code_inline">false</span>. This should be set to <span class="code_inline">true</span> if the server should consider the file a potential source of metadata extraction, or <span class="code_inline">false</span> if the server should not attempt to extract any metadata from the deposit.
</ul>
<p>
For example:
</p>
<div class="code">
<pre>
PUT EM-IRI HTTP/1.1
Host: example.org
Content-Type: application/zip
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-MD5: [md5-digest]
Content-Disposition: attachment; filename=[filename]
Packaging: http://purl.org/net/sword/package/METSDSpaceSIP
On-Behalf-Of: jbloggs
[request entity]
</pre>
</div>
<p>
The requirements placed on the server here are:
</p>
<ul>
<li>The server SHOULD verify the <span class="code_inline">Content-MD5</span> header against the content. If the check fails, the server MUST respond with 412 Precondition Failed. See <a href="#errordocuments">Section 12: Error Documents</a>.</li>
<li>Server implementations MUST adopt the behaviour and requirements in [<a href="#rfc2183">RFC2183</a>] with respect to the <span class="code_inline">Content-Disposition</span> header</li>
<li>If there is no <span class="code_inline">Packaging</span> header, the server SHOULD assume that it is the binary packaging format (See <a href="#iris">Section 5: IRIs</a>)</li>
<li>If the container to which the deposit is being made has been previously marked as "in progress", the server SHOULD continue to respect that assertion as per <a href="#continueddeposit">Section 9: Continued Deposit</a>.</li>
<li>If there is an <span class="code_inline">On-Behalf-Of</span> header, the server MUST behave as described in <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a></span>.</li>
<li>If no <span class="code_inline">Metadata-Relevant</span> header is provided the server MAY assume that it is <span class="code_inline">true</span> and MAY attempt to extract metadata from the deposit. If <span class="code_inline">Metadata-Relevant</span> is <span class="code_inline">false</span> the server SHOULD NOT attempt to extract metadata from the deposit.</li>
<li>The server MUST effectively replace all the existing content in the item, although implementations may choose to provide versioning or some other mechanism for retaining the overwritten content.</li>
</ul>
<p>
Once the server has processed the request it MUST return an HTTP status code <span class="code_inline">204 (No Content)</span>, or an appropriate error code.
</p>
<h4><a name="protocoloperations_editingcontent_metadata">6.5.2. Replacing the Metadata of a Resource</a></h4>
<em>See section 5.4 and 9.3 of [<a href="#atompub">AtomPub</a>] for details.</em>
<p>
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the <strong>Edit-IRI</strong>. The client can only be sure that the server will support this process when using the default format supported by SWORD: Qualified Dublin Core XML embedded directly in the <span class="code_inline">atom:entry</span>. Other metadata formats MAY be supported by a particular server, but this is not covered by the SWORD profile.
</p>
<ul>
<li>The client SHOULD supply a <span class="code_inline">Content-Type</span> header with the value <span class="code_inline">application/atom+xml</span> or <span class="code_inline">application/atom+xml;type=entry</span></li>
<li>The client MAY provide an <span class="code_inline">On-Behalf-Of</span> header [<a href="#sword001">SWORD001</a>]</li>
<li>The client MAY provide an <span class="code_inline">In-Progress</span> header with a value of true or false [<a href="#sword001">SWORD001</a>]. See <a href="#continueddeposit">Section 9: Continued Deposit</a> for more details.</li>
</ul>
<p>
For example:
</p>
<div class="code">
<pre>
PUT Edit-IRI HTTP/1.1
Host: example.org
Content-Type: application/atom+xml
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
On-Behalf-Of: jbloggs
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:dcterms="http://purl.org/dc/terms/">
<title>Title</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Contributor</name></author>
<summary type="text">The abstract</summary>
<!-- some embedded metadata -->
<dcterms:abstract>The abstract</dcterms:abstract>
<dcterms:accessRights>Access Rights</dcterms:accessRights>
<dcterms:alternative>Alternative Title</dcterms:alternative>
<dcterms:available>Date Available</dcterms:available>
<dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
<dcterms:contributor>Contributor</dcterms:contributor>
<dcterms:description>Description</dcterms:description>
<dcterms:hasPart>Has Part</dcterms:hasPart>
<dcterms:hasVersion>Has Version</dcterms:hasVersion>
<dcterms:identifier>Identifier</dcterms:identifier>
<dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
<dcterms:publisher>Publisher</dcterms:publisher>
<dcterms:references>References</dcterms:references>
<dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
<dcterms:source>Source</dcterms:source>
<dcterms:title>Title</dcterms:title>
<dcterms:type>Type</dcterms:type>
</entry>
</pre>
</div>
<p>
The requirements placed on the server here are:
</p>
<ul>
<li>If there is no <span class="code_inline">In-Progress</span> header, the server MUST assume that it is <span class="code_inline">false</span>, and MUST behave as described in <a href="#continueddeposit">Section 9: Continued Deposit</a></li>
<li>If there is an <span class="code_inline">On-Behalf-Of</span> header, the server MUST behave as described in <a href="#authenticationmediateddeposit">Section 8: Authentication and Mediated Deposit</a></span>.</li>
<li>The server MUST effectively replace all the existing metadata in the item, although implementations may choose to provide versioning or some other mechanism for retaining the overwritten metadata.</li>
</ul>
<p>
Once the server has processed the request it MUST return an HTTP status code <span class="code_inline">200 (OK)</span> or <span class="code_inline">204 (No Content)</span>, or an appropriate error code.
</p>
<h4><a name="protocoloperations_editingcontent_multipart">6.5.3. Replacing the Metadata and File Content of a Resource</a></h4>
<em>See [<a href="#atommultipart">AtomMultipart</a>] for details.</em>
<p>
The client can replace both the metadata and content of a resource by performing an HTTP PUT on the <strong>Edit-IRI</strong> with a multipart mime message, as per <a href="#protocoloperations_creatingresource_multipart">Section 6.3.2. Creating a Resource with a Multipart Deposit</a>