idnits 2.17.1 draft-ietf-webdav-protocol-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 44) being 62 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 21 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "Second" TimeType specifies the number of seconds that MUST elapse between granting of the lock at the server, and the automatic removal of the lock. A server MUST not generate a timeout value for "Second" greater than 2^32-1. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 18, 1998) is 9588 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Lagoze' is mentioned on line 511, but not defined == Missing Reference: 'Extension' is mentioned on line 828, but not defined == Unused Reference: 'ISO-8601' is defined on line 3836, but no explicit reference was found in the text == Unused Reference: 'Yergeau' is defined on line 3867, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'Alvestrand' ** Downref: Normative reference to an Informational RFC: RFC 1807 (ref. '1995') -- Possible downref: Non-RFC (?) normative reference: ref. '1998' ** Obsolete normative reference: RFC 2044 (ref. '1997') (Obsoleted by RFC 2279) -- Possible downref: Non-RFC (?) normative reference: ref. 'Bray' -- Possible downref: Non-RFC (?) normative reference: ref. 'Paoli' -- Possible downref: Non-RFC (?) normative reference: ref. 'Sperberg-McQueen' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-639' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-8601' -- Duplicate reference: RFC1807, mentioned in 'Lasher', was also mentioned in '1995'. ** Downref: Normative reference to an Informational RFC: RFC 1807 (ref. 'Lasher') -- Duplicate reference: RFC1807, mentioned in 'Cohen', was also mentioned in 'Lasher'. ** Downref: Normative reference to an Informational RFC: RFC 1807 (ref. 'Cohen') -- Possible downref: Non-RFC (?) normative reference: ref. 'Leach' -- Possible downref: Non-RFC (?) normative reference: ref. 'Salz' -- Possible downref: Non-RFC (?) normative reference: ref. 'MARC' -- Possible downref: Non-RFC (?) normative reference: ref. '1994' -- Duplicate reference: RFC2044, mentioned in 'Yergeau', was also mentioned in '1997'. ** Obsolete normative reference: RFC 2044 (ref. 'Yergeau') (Obsoleted by RFC 2279) Summary: 13 errors (**), 0 flaws (~~), 9 warnings (==), 16 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 WEBDAV Working Group Y.Y. Goland, Microsoft 2 INTERNET DRAFT E.J. Whitehead, Jr., UC Irvine 3 A. Faizi, Netscape 4 S.R. Carter, Novell 5 D. Jensen, Novell 6 Expires July, 1998 January 18, 1998 8 Extensions for Distributed Authoring on the World Wide Web -- WEBDAV 10 Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, 14 and its working groups. Note that other groups may also distribute 15 working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or made obsolete by other 19 documents at any time. It is inappropriate to use Internet-Drafts as 20 reference material or to cite them other than as "work in progress". 22 To learn the current status of any Internet-Draft, please check the 23 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 24 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 25 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 26 ftp.isi.edu (US West Coast). 28 Distribution of this document is unlimited. Please send comments to 29 the Distributed Authoring and Versioning (WEBDAV) working group at 30 , which may be joined by sending a message 31 with subject "subscribe" to . 33 Discussions of the WEBDAV working group are archived at 34 . 36 Abstract 38 This document specifies a set of methods, headers, and content-types 39 ancillary to HTTP/1.1 for the management of resource properties, 40 creation and management of resource collections, namespace 41 manipulation, and resource locking (collision avoidance). 43 Changes 45 Changes since draft-ietf-webdav-protocol-06.txt 47 [Editor's note: This section will not appear in the final form of 48 this document. Its purpose is to provide a concise list of changes 49 from the previous revision of the draft for use by reviewers.] 51 Rationale for many of the changes made in this revision of the draft 52 can be found in the mailing list archives at: 54 http://lists.w3.org/Archives/Public/w3c-dist-auth/1997OctDec/0160.ht 55 ml. 57 Where the 200 OK status code was used to indicate a successful 58 response without a response entity body, 204 No Content is now used. 59 Because PEP uses 420 and 421 status codes, and since PEP has been 60 submitted as an Experimental RFC, the WebDAV 420 status code has 61 been changed to 422, and the WebDAV 421 status code has been changed 62 to 423. 64 The 423 Destination Locked status code has been changed to 423 65 Locked, and now covers all cases where an operand was locked, 66 preventing the execution of the method. 68 Removed the Destroy header, since it is not needed in this draft, 69 but will be needed in the versioning draft. 71 The Enforce-Live-Properties header was renamed to Property-Behavior, 72 to more closely represent the meaning of the header now that the 73 "omit" functionality is included. A keepalive field was added to the 74 Property-Behavior header to make it more meaningful. 76 Removed the INDEX method, since the functionality of INDEX can now 77 be performed by the PROPFIND method. PROPFIND provides more 78 flexibility in specifying the type and amount of property 79 information returned than does INDEX, which is important for 80 returning information on a large number of resources. 82 Clarified that performing a MOVE as a COPY, then DELETE, performed 83 atomically, only applies to non-collection resources. 85 Clarified the semantics of errors that are encountered in infinite 86 depth move and copy of a hierarchy of resources. For errors copying 87 internal nodes of the hierarchy tree (i.e., collections), the 88 operation skips that subtree, and moves on to the next subtree. If 89 an error is encountered moving/copying a leaf of the tree, then skip 90 that resource, and move on to the next leaf. 92 Removed the PATCH method. This will be resubmitted as the document 93 draft-ietf-webdav-patch-00. 95 Added language that states that if a PROPPATCH is invoked on a null 96 resource (e.g., a deleted resource), an empty resource is created, 97 and the PROPPATCH directives are performed on this new resource. 99 Added a forward reference to the source link definition (Section 100 13.11) in Section 4.4. 102 Changed all Values= to Values:. Also changed all "values" to 103 "value". 105 References to state tokens are now restricted to sections 9.7 and 106 9.8. 108 The property-behavior header has been turned into the 109 propertybehavior XML element because it contained a list of URIs 110 which can thus have unbounded size. The lock-info header has been 111 turned into the lockinfo XML element for the same reason. I have 112 also made the same change of the Propfind header into the Propfind 113 XML element. We can put the property behavior header into the body 114 because neither COPY nor MOVE have bodies. However we can't put 115 lock-token, if-state-match, etc. in the body because they may need 116 to be used with PUT. However I don't consider this a big deal 117 because I sincerely doubt that there will be cases where lock-token 118 or if-state-match will see large numbers of entries. 120 Also changed omit to mean "copy properties with best effort but 121 failure is acceptable." 123 Added the external members property. 125 Added language to 6.4 making it clear that any new resources created 126 as the child of a write locked collection is added to the lock. 128 Made the lock-token response header from a single URL to multiple 129 URLs. But all the URLs MUST refer to the exact same lock. 131 changed to the correct form: 134 Changed the delete rule for collections to read that if a delete in 135 a collection member fails then it is the ancestors, not the progeny, 136 who can not be deleted in order to maintain the namespace. 138 Updated our reference to the XML spec. 140 Added LOCK and UNLOCK to the list of methods covered by the write 141 lock. This is necessary so that a lock-token will have to be 142 submitted in order to make changes, otherwise we defeat the whole 143 purpose of requiring the lock-token. 145 Changed the title of section 6.6 from Re-Issuing Write Locks to 146 Refreshing Write Locks, made it illegal to make the same lock 147 request twice (you know you are making the same request because you 148 had to include the lock-token to make it!) and instead made it legal 149 to submit a LOCK method with no body but with a lock-token header. 150 I also added a refresh example. 152 Put in a note that an empty request body for PROPFIND means to 153 return all names and values of properties on the resources. 155 I have added a section on XML processing errors. I know, I know, it 156 shouldn't be in the standard. I will move it to our compliance draft 157 as soon as we prepare the first version. 159 Removed addlocks and replaced with the depth header and the depth 160 element. 162 Changed all the as in namespace elements to all lower case. 164 Moved all XML element declarations to the same section. Removed the 165 parent description. 167 Updated the depth section to make it more generic, changed the 168 wording for how COPY/MOVE are handled with write locks, require that 169 ALL propfind responses include href, require that if a property is 170 not found in a propfind then a 404 Not Found must be returned, and 171 made explicit that PROPFIND responses on resources with internal 172 members are returned as a flat list with no significance to its 173 ordering. 175 Removed reference to efficient update in the introduction since 176 PATCH is now gone. 178 Rewrote the write lock and null resource section to deal with the 179 question of the state of the resource when it is locked and null. 181 Changed www.ietf.org to www.iana.org. 183 Changed the response element and added the new propstat element. 184 With the prohibition that an HREF can only appear once in a 185 multistatus response we can guarantee linear processing costs. 187 Added Intellectual Property section, as required by RFC 2026. 189 Added IANA Considerations section. 191 Added Authorization headers to LOCK and UNLOCK examples. 193 Changed lock tokens in examples to use string format of UUID. 195 Since the latest HTTP revision defines a 418 and 419 status code, 196 the 418 status code has been changed to 422, 419 to 423, 422 to 424, 197 and 423 to 425. 199 Changed implementation of the get* (e.g., getcontentlength) 200 properties to strength MUST. 202 Changed definition of XML elements and DAV properties to use XML 203 element definitions, rather than BNF. 205 Renumbered all sections 207 Contents 209 STATUS OF THIS MEMO..................................................1 210 ABSTRACT.............................................................1 211 CHANGES..............................................................1 212 Changes since draft-ietf-webdav-protocol-06.txt......................1 213 CONTENTS.............................................................5 214 1 INTRODUCTION.......................................................9 215 2 DATA MODEL FOR RESOURCE PROPERTIES................................10 216 2.1 The Resource Property Model....................................10 217 2.2 Existing Metadata Proposals....................................10 218 2.3 Properties and HTTP Headers....................................11 219 2.4 Property Values................................................11 220 2.5 Property Names.................................................12 221 3 COLLECTIONS OF WEB RESOURCES......................................12 222 3.1 Collection Resources...........................................12 223 3.2 Creation and Retrieval of Collection Resources.................13 224 3.3 HTTP URL Namespace Model.......................................13 225 3.4 Source Resources and Output Resources..........................14 226 4 LOCKING...........................................................15 227 4.1 Exclusive Vs. Shared Locks.....................................15 228 4.2 Required Support...............................................16 229 4.3 Lock Tokens....................................................16 230 4.4 opaquelocktoken Lock Token URI Scheme..........................17 231 4.5 Lock Capability Discovery......................................17 232 4.6 Active Lock Discovery..........................................18 233 5 WRITE LOCK........................................................18 234 5.1 Methods Restricted by Write Locks..............................18 235 5.2 Write Locks and Properties.....................................18 236 5.3 Write Locks and Null Resources.................................18 237 5.4 Write Locks and Collections....................................19 238 5.5 Write Locks and COPY/MOVE......................................19 239 5.6 Refreshing Write Locks.........................................19 240 5.7 Write Locks and The Lock-Token Request Header..................20 241 5.7.1 Write Lock Token Example...................................20 242 6 NOTATIONAL CONVENTIONS............................................21 243 7 HTTP METHODS FOR DISTRIBUTED AUTHORING............................21 244 7.1 PROPFIND.......................................................21 245 7.1.1 Example: Retrieving Named Properties.......................22 246 7.1.2 Example: Using allprop to Retrieve All Properties..........23 247 7.1.3 Example: Using propname to Retrieve all Property Names.....26 248 7.2 PROPPATCH......................................................28 249 7.2.1 Status Codes...............................................28 250 7.2.2 Example....................................................28 251 7.3 MKCOL Method...................................................30 252 7.3.1 Request....................................................30 253 7.3.2 Response Codes.............................................30 254 7.3.3 Example....................................................31 255 7.4 ADDREF Method..................................................31 256 7.4.1 The Request................................................31 257 7.4.2 Example....................................................31 258 7.5 DELREF Method..................................................32 259 7.5.1 The Request................................................32 260 7.5.2 Example....................................................32 261 7.6 GET, HEAD for Collections......................................32 262 7.7 POST for Collections...........................................33 263 7.8 DELETE.........................................................33 264 7.8.1 DELETE for Non-Collection Resources........................33 265 7.8.2 DELETE for Collections.....................................33 266 7.9 PUT............................................................34 267 7.9.1 PUT for Non-Collection Resources...........................34 268 7.9.2 PUT for Collections........................................35 269 7.10 COPY Method....................................................35 270 7.10.1 COPY for HTTP/1.1 resources................................35 271 7.10.2 COPY for Properties........................................35 272 7.10.3 COPY for Collections.......................................36 273 7.10.4 Type Interactions..........................................37 274 7.10.5 Status Codes...............................................37 275 7.10.6 Overwrite Example..........................................38 276 7.10.7 No Overwrite Example.......................................38 277 7.10.8 Collection Example.........................................38 278 7.11 MOVE Method....................................................39 279 7.11.1 MOVE for Collections.......................................40 280 7.11.2 Status Codes...............................................40 281 7.11.3 Non-Collection Example.....................................41 282 7.11.4 Collection Example.........................................41 283 7.12 LOCK Method....................................................42 284 7.12.1 Operation..................................................43 285 7.12.2 The Effect of Locks on Properties and Collections..........43 286 7.12.3 Locking Replicated Resources...............................43 287 7.12.4 Depth and Locking..........................................43 288 7.12.5 Interaction with other Methods.............................44 289 7.12.6 Lock Compatibility Table...................................44 290 7.12.7 Lock Response..............................................44 291 7.12.8 Status Codes...............................................44 292 7.12.9 Example - Simple Lock Request..............................45 293 7.12.10 Example - Refreshing a Write Lock.........................46 294 7.12.11 Example - Multi-Resource Lock Request.....................47 295 7.13 UNLOCK Method..................................................48 296 7.13.1 Example....................................................48 297 8 HTTP HEADERS FOR DISTRIBUTED AUTHORING............................49 298 8.1 Collection-Member Header.......................................49 299 8.2 DAV Header.....................................................49 300 8.3 Depth Header...................................................49 301 8.4 Destination Header.............................................50 302 8.5 If-None-State-Match............................................50 303 8.6 If-State-Match.................................................51 304 8.7 Lock-Token Request Header......................................51 305 8.8 Lock-Token Response Header.....................................52 306 8.9 Overwrite Header...............................................53 307 8.10 Status-URI Response Header.....................................53 308 8.11 Timeout Header.................................................53 309 9 STATUS CODE EXTENSIONS TO HTTP/1.1................................54 310 9.1 102 Processing.................................................54 311 9.2 207 Multi-Status...............................................55 312 9.3 422 Unprocessable Entity.......................................55 313 9.4 423 Insufficient Space on Resource.............................55 314 9.5 424 Method Failure.............................................55 315 9.6 425 Locked.....................................................55 316 10 MULTI-STATUS RESPONSE...........................................55 317 11 XML ELEMENT DEFINITIONS.........................................55 318 11.1 activelock XML Element.........................................56 319 11.1.1 depth XML Element..........................................56 320 11.1.2 locktoken XML Element......................................56 321 11.1.3 timeout XML Element........................................56 322 11.2 collection XML Element.........................................56 323 11.3 href XML Element...............................................56 324 11.4 link XML Element...............................................57 325 11.4.1 dst XML Element............................................57 326 11.4.2 src XML Element............................................57 327 11.5 lockentry XML Element..........................................57 328 11.6 lockinfo XML Element...........................................57 329 11.7 lockscope XML Element..........................................58 330 11.7.1 exclusive XML Element......................................58 331 11.7.2 shared XML Element.........................................58 332 11.8 locktype XML Element...........................................58 333 11.8.1 write XML Element..........................................58 334 11.9 multistatus XML Element........................................58 335 11.9.1 response XML Element.......................................59 336 11.9.2 responsedescription XML Element............................59 337 11.10 owner XML Element.............................................60 338 11.11 prop XML element..............................................60 339 11.12 propertybehavior XML element..................................60 340 11.12.1 keepalive XML element.....................................60 341 11.12.2 omit XML element..........................................61 342 11.13 propertyupdate XML element....................................61 343 11.13.1 remove XML element........................................61 344 11.13.2 set XML element...........................................62 345 11.14 propfind XML Element..........................................62 346 11.14.1 allprop XML Element.......................................62 347 11.14.2 propname XML Element......................................62 348 12 DAV PROPERTIES..................................................62 349 12.1 creationdate Property..........................................63 350 12.2 displayname Property...........................................63 351 12.3 externalmembers Property.......................................63 352 12.4 getcontentlanguage Property....................................63 353 12.5 getcontentlength Property......................................64 354 12.6 getcontenttype Property........................................64 355 12.7 getetag Property...............................................64 356 12.8 getlastmodified Property.......................................64 357 12.9 lockdiscovery Property.........................................65 358 12.9.1 Example....................................................65 359 12.10 resourcetype Property.........................................66 360 12.11 source Property...............................................66 361 12.11.1 Example...................................................67 362 12.12 supportedlock Property........................................67 363 12.12.1 Example...................................................68 364 13 DAV COMPLIANCE CLASSES..........................................68 365 13.1 Class 1........................................................69 366 13.2 Class 2........................................................69 367 14 INTERNATIONALIZATION CONSIDERATIONS.............................69 368 15 SECURITY CONSIDERATIONS.........................................70 369 15.1 Authentication of Clients......................................71 370 15.2 Denial of Service..............................................71 371 15.3 Security through Obscurity.....................................72 372 15.4 Privacy Issues Connected to Locks..............................72 373 15.5 Privacy Issues Connected to Properties.........................72 374 15.6 Reduction of Security due to Source Link.......................72 375 16 IANA CONSIDERATIONS.............................................73 376 17 TERMINOLOGY.....................................................73 377 18 COPYRIGHT.......................................................74 378 19 INTELLECTUAL PROPERTY...........................................74 379 20 ACKNOWLEDGEMENTS................................................75 380 21 REFERENCES......................................................76 381 22 AUTHORS' ADDRESSES..............................................78 382 23 APPENDICES......................................................79 383 23.1 Appendix 1 - WebDAV Document Type Definition...................79 384 23.2 Appendix 2 - ISO 8601 Date and Time Profile....................80 385 23.3 Appendix 3 - Notes on Processing XML Elements..................81 386 23.3.1 XML Syntax Error Example...................................81 387 23.3.2 Unknown XML Element Example................................81 389 1 Introduction 391 This document describes an extension to the HTTP/1.1 protocol that 392 allows clients to perform remote web content authoring operations. 393 This extension provides a coherent set of methods, headers, request 394 entity body formats, and response entity body formats that provide 395 operations for: 397 Properties: The ability to create, remove, and query information 398 about Web pages, such as their authors, creation dates, etc. Also, 399 the ability to link pages of any media type to related pages. 401 Collections: The ability to create sets of related documents, and to 402 receive a listing of pages at a particular hierarchy level (like a 403 directory listing in a file system). 405 Locking: The ability to keep more than one person from working on a 406 document at the same time. This prevents the "lost update problem," 407 in which modifications are lost as first one author, then another 408 writes changes without merging the other author's changes 410 Namespace Operations: The ability to copy and move Web resources 412 Requirements and rationale for these operations are described in a 413 companion document, "Requirements for a Distributed Authoring and 414 Versioning Protocol for the World Wide Web" [Slein et al., 1997]. 416 The sections below provide a detailed introduction to resource 417 properties (Section 2), collections of resources (Section 3), and 418 locking operations (Section 4). These sections introduce the 419 abstractions manipulated by the WebDAV-specific HTTP methods 420 described in Section 7, "HTTP Methods for Distributed Authoring". 422 In HTTP/1.1, method parameter information was exclusively encoded in 423 HTTP headers. Unlike HTTP/1.1, WebDAV, encodes method parameter 424 information either in an Extensible Markup Language (XML) [Bray, 425 Paoli, Sperberg-McQueen, 1998] request entity body, or in an HTTP 426 header. The use of XML to encode method parameters was motivated by 427 the ability to add extra XML elements to existing structures, 428 providing extensibility, and by XML's ability to encode information 429 in ISO 10646 character sets, providing internationalization support. 430 As a rule of thumb, parameters are encoded in XML entity bodies when 431 they have unbounded length, or when they may be shown to a human 432 user and hence require encoding in an ISO 10646 character set. 433 Otherwise, parameters are encoded within HTTP headers. Section 8 434 describes the new HTTP headers used with WebDAV methods. 436 In addition to encoding method parameters, XML is used in WebDAV to 437 encode the responses from methods, providing the extensibility and 438 internationalization advantages of XML for method output, as well as 439 input. XML elements used in this specification are defined in 440 Section 11. 442 While the status codes provided by HTTP/1.1 are sufficient to 443 describe most error conditions encountered by WebDAV methods, there 444 are some errors that do not fall neatly into the existing 445 categories. New status codes developed for the WebDAV methods are 446 defined in Section 9. Since some WebDAV methods may operate over 447 many resources, the Multi-Status status type has been introduced to 448 return status information for multiple resources. Multi-Status 449 response is described in Section 10. 451 WebDAV employs the property mechanism to store information about the 452 current state of the resource. For example, when a lock is taken 453 out on a resource, a lock information property describes the current 454 state of the lock. Section 12 defines the properties used within the 455 WebDAV specification. 457 Finishing off the specification are sections on what it means to be 458 compliant with this specification (Section 13), on 459 internationalization support (Section 14), and on security (Section 460 15). 462 2 Data Model for Resource Properties 464 2.1 The Resource Property Model 466 Properties are pieces of data that describe the state of a resource. 467 Properties are data about data. 469 Properties are used in distributed authoring environments to provide 470 for efficient discovery and management of resources. For example, a 471 'subject' property might allow for the indexing of all resources by 472 their subject, and an 'author' property might allow for the 473 discovery of what authors have written which documents. 475 The DAV property model consists of name/value pairs. The name of a 476 property identifies the property's syntax and semantics, and 477 provides an address by which to refer to that syntax and semantics. 479 There are two categories of properties: "live" and "dead". A live 480 property has its syntax and semantics enforced by the server. Live 481 properties include cases where a) the value of a property is read- 482 only, maintained by the server, and b) the value of the property is 483 maintained by the client, but the server performs syntax checking on 484 submitted values. A dead property has its syntax and semantics 485 enforced by the client; the server merely records the value of the 486 property verbatim. 488 2.2 Existing Metadata Proposals 489 Properties have long played an essential role in the maintenance of 490 large document repositories, and many current proposals contain some 491 notion of a property, or discuss web metadata more generally. These 492 include PICS [Miller et al., 1996], PICS-NG, XML [Bray, Paoli, 493 Sperberg-McQueen, 1998], Web Collections, and several proposals on 494 representing relationships within HTML. Work on PICS-NG and Web 495 Collections has been subsumed by the Resource Definition Framework 496 (RDF) metadata activity of the World Wide Web Consortium. RDF 497 consists of a network-based data model and an XML representation of 498 that model. 500 Some proposals come from a digital library perspective. These 501 include the Dublin Core [Weibel et al., 1995] metadata set and the 502 Warwick Framework [Lagoze, 1996], a container architecture for 503 different metadata schemas. The literature includes many examples 504 of metadata, including MARC [MARC, 1994], a bibliographic metadata 505 format, and RFC 1807 [Lasher, Cohen, 1995], a technical report 506 bibliographic format employed by the Dienst system. Additionally, 507 the proceedings from the first IEEE Metadata conference describe 508 many community-specific metadata sets. 510 Participants of the 1996 Metadata II Workshop in Warwick, UK 511 [Lagoze, 1996], noted that "new metadata sets will develop as the 512 networked infrastructure matures" and "different communities will 513 propose, design, and be responsible for different types of 514 metadata." These observations can be corroborated by noting that 515 many community-specific sets of metadata already exist, and there is 516 significant motivation for the development of new forms of metadata 517 as many communities increasingly make their data available in 518 digital form, requiring a metadata format to assist data location 519 and cataloging. 521 2.3 Properties and HTTP Headers 523 Properties already exist, in a limited sense, in HTTP message 524 headers. However, in distributed authoring environments a 525 relatively large number of properties are needed to describe the 526 state of a resource, and setting/returning them all through HTTP 527 headers is inefficient. Thus a mechanism is needed which allows a 528 principal to identify a set of properties in which the principal is 529 interested and to set or retrieve just those properties. 531 2.4 Property Values 533 The value of a property is expressed as a well-formed XML document. 535 XML has been chosen because it is a flexible, self-describing, 536 structured data format that supports rich schema definitions, and 537 because of its support for multiple character sets. XML's self- 538 describing nature allows any property's value to be extended by 539 adding new elements. Older clients will not break when they 540 encounter extensions because they will still have the data specified 541 in the original schema and will ignore elements they do not 542 understand. XML's support for multiple character sets allows any 543 human-readable property to be encoded and read in a character set 544 familiar to the user. 546 2.5 Property Names 548 A property name is a universally unique identifier that is 549 associated with a schema that provides information about the syntax 550 and semantics of the property. 552 Because a property's name is universally unique, clients can depend 553 upon consistent behavior for a particular property across multiple 554 resources, so long as that property is "live" on the resources in 555 question. 557 The XML namespace mechanism, which is based on URIs, is used to name 558 properties because it prevents namespace collisions and provides for 559 varying degrees of administrative control. 561 The property namespace is flat; that is, no hierarchy of properties 562 is explicitly recognized. Thus, if a property A and a property A/B 563 exist on a resource, there is no recognition of any relationship 564 between the two properties. It is expected that a separate 565 specification will eventually be produced which will address issues 566 relating to hierarchical properties. 568 Finally, it is not possible to define the same property twice on a 569 single resource, as this would cause a collision in the resource's 570 property namespace. 572 3 Collections of Web Resources 574 This section provides a description of a new type of Web resource, 575 the collection, and discusses its interactions with the HTTP Uniform 576 Resource Locator (URL) namespace. The purpose of a collection 577 resource is to model collection-like objects (e.g., filesystem 578 directories) within a server's namespace. 580 All DAV compliant resources MUST support the HTTP URL namespace 581 model specified herein. 583 3.1 Collection Resources 585 A collection is a resource whose state consists of an unordered list 586 of internal members, an unordered list of external members, and a 587 set of properties. An internal member resource MUST have a URI that 588 is immediately relative to the base URI of the collection. That is, 589 the internal member's URI is equal to the parent collection's URI 590 plus an additional segment where segment is defined in Section 3.2.1 591 of RFC 2068 [Fielding et al., 1996]. 593 An external member resource is a resource that could not be an 594 internal member resource. Any given internal or external Member MUST 595 only belong to the collection once, i.e., it is illegal to have 596 multiple instances of the same URI in a collection. Properties 597 defined on collections behave exactly as do properties on non- 598 collection resources. 600 There is a standing convention that when a collection is referred to 601 by its name without a trailing slash, the trailing slash is 602 automatically appended. Due to this, a resource MAY accept a URI 603 without a trailing "/" to point to a collection. In this case it 604 SHOULD return a location header in the response pointing to the URL 605 ending with the "/". For example, if a client invokes a method on 606 http://foo.bar/blah (no trailing slash), the resource 607 http://foo.bar/blah/ (trailing slash) MAY respond as if the 608 operation were invoked on it, and SHOULD return a location header 609 with http://foo.bar/blah/ in it. In general clients SHOULD use the 610 "/" form of collection names. 612 3.2 Creation and Retrieval of Collection Resources 614 This document specifies the MKCOL method to create new collection 615 resources, rather than using the existing HTTP/1.1 PUT or POST 616 method, for the following reasons 618 In HTTP/1.1, the PUT method is defined to store the request body at 619 the location specified by the Request-URI. While a description 620 format for a collection can readily be constructed for use with PUT, 621 the implications of sending such a description to the server are 622 undesirable. For example, if a description of a collection that 623 omitted some existing resources were PUT to a server, this might be 624 interpreted as a command to remove those members. This would extend 625 PUT to perform DELETE functionality, which is undesirable since it 626 changes the semantics of PUT, and makes it difficult to control 627 DELETE functionality with an access control scheme based on methods. 629 While the POST method is sufficiently open-ended that a "create a 630 collection" POST command could be constructed, this is undesirable 631 because it would be difficult to separate access control for 632 collection creation from other uses of POST. 634 The exact definition of the behavior of GET and PUT on collections 635 is defined later in this document. 637 3.3 HTTP URL Namespace Model 639 The HTTP URL Namespace is a hierarchical namespace where the 640 hierarchy is delimited with the "/" character. DAV compliant 641 resources MUST maintain the consistency of the HTTP URL namespace. 642 Any attempt to create a resource (excepting the root member of a 643 namespace) that would not be the internal member of a collection 644 MUST fail. For example, if the collection http://www.foo.bar.org/a/ 645 exists, but http://www.foo.bar.org/a/b/does not exist, an attempt to 646 create http://www.foo.bar.org/a/b/c must fail. 648 3.4 Source Resources and Output Resources 650 For many resources, the entity returned by a GET method exactly 651 matches the persistent state of the resource, for example, a GIF 652 file stored on a disk. For this simple case, the URL at which a 653 resource is accessed is identical to the URL at which the source 654 (the persistent state) of the resource is accessed. This is also 655 the case for HTML source files that are not processed by the server 656 prior to transmission. 658 However, the server can sometimes process HTML resources before they 659 are transmitted as a return entity body. For example, server-side- 660 include directives within an HTML file instruct a server to replace 661 the directive with another value, such as the current date. In this 662 case, what is returned by GET (HTML plus date) differs from the 663 persistent state of the resource (HTML plus directive). Typically 664 there is no way to access the HTML resource containing the 665 unprocessed directive. 667 Sometimes the entity returned by GET is the output of a data- 668 producing process that is described by one or more source resources 669 (that may not even have a location in the URL namespace). A single 670 data-producing process may dynamically generate the state of a 671 potentially large number of output resources. An example of this is 672 a CGI script that describes a "finger" gateway process that maps 673 part of the namespace of a server into finger requests, such as 674 http://www.foo.bar.org/finger_gateway/user@host. 676 In the absence of distributed authoring capabilities, it is 677 acceptable to have no mapping of source resource(s) to the URI 678 namespace. In fact, preventing access to the source resource(s) has 679 desirable security benefits. However, if remote editing of the 680 source resource(s) is desired, the source resource(s) should be 681 given a location in the URI namespace. This source location should 682 not be one of the locations at which the generated output is 683 retrievable, since in general it is impossible for the server to 684 differentiate requests for source resources from requests for 685 process output resources. There is often a many-to-many 686 relationship between source resources and output resources. 688 On WebDAV compliant servers, for all output resources which have a 689 single source resource (and that source resource has a URI), the URI 690 of the source resource SHOULD be stored in a link on the output 691 resource with type http://www.iana.org/standards/dav/source (see 692 Section 12.11 for a description of the source link). Note that by 693 storing the source URIs in links on the output resources, the burden 694 of discovering the source is placed on the authoring client. 696 4 Locking 698 The ability to lock a resource provides a mechanism for serializing 699 access to that resource. Using a lock, an authoring client can 700 provide a reasonable guarantee that another principal will not 701 modify a resource while it is being edited. In this way, a client 702 can prevent the "lost update" problem. 704 This specification allows locks to vary over two client-specified 705 parameters, the number of principals involved (exclusive vs. shared) 706 and the type of access to be granted. This document defines locking 707 for only one access type, write. However, the syntax is extensible, 708 and permits the eventual specification of locking for other access 709 types. 711 4.1 Exclusive Vs. Shared Locks 713 The most basic form of lock is an exclusive lock. This is a lock 714 where the access right in question is only granted to a single 715 principal. The need for this arbitration results from a desire to 716 avoid having to constantly merge results. 718 However, there are times when the goal of a lock is not to exclude 719 others from exercising an access right but rather to provide a 720 mechanism for principals to indicate that they intend to exercise 721 their access right. Shared locks are provided for this case. A 722 shared lock allows multiple principals to receive a lock. Hence any 723 principal with appropriate access can get the lock. 725 With shared locks there are two trust sets that affect a resource. 726 The first trust set is created by access permissions. Principals 727 who are trusted, for example, may have permission to write the 728 resource. Those who are not, don't. Among those who have access 729 permission to write the resource, the set of principals who have 730 taken out a shared lock also must trust each other, creating a 731 (typically) smaller trust set within the access permission write 732 set. 734 Starting with every possible principal on the Internet, in most 735 situations the vast majority of these principals will not have write 736 access to a given resource. Of the small number who do have write 737 access, some principals may decide to guarantee their edits are free 738 from overwrite conflicts by using exclusive write locks. Others may 739 decide they trust their collaborators will not overwrite their work 740 (the potential set of collaborators being the set of principals who 741 have write permission) and use a shared lock, which informs their 742 collaborators that a principal may be working on the resource. 744 The WebDAV extensions to HTTP do not need to provide all of the 745 communications paths necessary for principals to coordinate their 746 activities. When using shared locks, principals may use any out of 747 band communication channel to coordinate their work (e.g., face-to- 748 face interaction, written notes, post-it notes on the screen, 749 telephone conversation, Email, etc.) The intent of a shared lock is 750 to let collaborators know who else may be working on a resource. 752 Shared locks are included because experience from web distributed 753 authoring systems has indicated that exclusive write locks are often 754 too rigid. An exclusive write lock is used to enforce a particular 755 editing process: take out exclusive write lock, read the resource, 756 perform edits, write the resource, release the lock. This editing 757 process has the problem that locks are not always properly released, 758 for example when a program crashes, or when a lock owner leaves 759 without unlocking a resource. While both timeouts and 760 administrative action can be used to remove an offending lock, 761 neither mechanism may be available when needed; the timeout may be 762 long or the administrator may not be available. 764 Despite their potential problems, exclusive write locks are 765 extremely useful, since often a guarantee of freedom from overwrite 766 conflicts is what is needed. This specification provides both 767 exclusive write locks and the less strict mechanism of shared locks. 769 4.2 Required Support 771 A WebDAV compliant server is not required to support locking in any 772 form. If the server does support locking it MAY choose to support 773 any combination of exclusive and shared locks for any access types. 775 The reason for this flexibility is that locking policy strikes to 776 the very heart of the resource management and versioning systems 777 employed by various storage repositories. These repositories 778 require control over what sort of locking will be made available. 779 For example, some repositories only support shared write locks while 780 others only provide support for exclusive write locks while yet 781 others use no locking at all. As each system is sufficiently 782 different to merit exclusion of certain locking features, this 783 specification leaves locking as the sole axis of negotiation within 784 WebDAV. 786 4.3 Lock Tokens 788 A lock token is a URI that identifies a particular lock. A lock 789 token is returned by every successful LOCK operation in the Lock- 790 Token response header, and can also be discovered through lock 791 discovery on a resource. 793 Lock token URIs are required to be unique across all resources for 794 all time. This uniqueness constraint allows lock tokens to be 795 submitted across resources and servers without fear of confusion. 797 This specification provides a lock token URI scheme called 798 opaquelocktoken that meets the uniqueness requirements. However 799 resources are free to return any URI scheme so long as it meets the 800 uniqueness requirements. 802 4.4 opaquelocktoken Lock Token URI Scheme 804 The opaquelocktoken URI scheme is designed to be unique across all 805 resources for all time. Due to this uniqueness quality, a client 806 MAY submit an opaque lock token in a Lock-Token request header and 807 an If-[None]-State-Match header on a resource other than the one 808 that returned it. 810 All resources MUST recognize the opaquelocktoken scheme and, at 811 minimum, recognize that the lock token was not generated by the 812 resource. Note, however, that resources are not required to 813 generate opaquelocktokens in LOCK method responses. 815 In order to guarantee uniqueness across all resources for all time 816 the opaquelocktoken requires the use of the Universally Unique 817 Identifier (UUID, also known as a Globally Unique Identifier, or 818 GUID) mechanism, as described in [Leach, Salz, 1998]. 820 Opaquelocktoken generators, however, have a choice of how they 821 create these tokens. They can either generate a new UUID for every 822 lock token they create, which is potentially very expensive, or they 823 can create a single UUID and then add extension characters. If the 824 second method is selected then the program generating the extensions 825 MUST guarantee that the same extension will never be used twice with 826 the associated UUID. 828 OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The 829 UUID production is the string form of a UUID, as defined in [Leach, 830 Salz, 1998]. Note that white space (LWS) is not allowed between 831 elements of this production. 833 Extension = path ; path is defined in Section 3.2.1 of RFC 2068 834 [Fielding et al., 1996] 836 4.5 Lock Capability Discovery 838 Since server lock support is optional, a client trying to lock a 839 resource on a server can either try the lock and hope for the best, 840 or perform some form of discovery to determine what lock 841 capabilities the server supports. This is known as lock capability 842 discovery. Lock capability discovery differs from discovery of 843 supported access control types, since there may be access control 844 types without corresponding lock types. A client can determine what 845 lock types the server supports by retrieving the supportedlock 846 property. 848 Any DAV compliant resource that supports the LOCK method MUST 849 support the supportedlock property. 851 4.6 Active Lock Discovery 853 If another principal locks a resource that a principal wishes to 854 access, it is useful for the second principal to be able to find out 855 who the first principal is. For this purpose the lockdiscovery 856 property is provided. This property lists all outstanding locks, 857 describes their type, and provides their lock token. 859 Any DAV compliant resource that supports the LOCK method MUST 860 support the lockdiscovery property. 862 5 Write Lock 864 This section describes the semantics specific to the write access 865 type for locks. The write lock is a specific instance of a lock 866 type, and is the only lock type described in this specification. A 867 DAV compliant resource MAY support the write lock. 869 5.1 Methods Restricted by Write Locks 871 A write lock prevents a principal without the lock from successfully 872 executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, DELETE, MKCOL, 873 ADDREF or DELREF on the locked resource. All other current methods, 874 GET in particular, function independent of the lock. 876 Note, however, that as new methods are created it will be necessary 877 to specify how they interact with a write lock. 879 5.2 Write Locks and Properties 881 While those without a write lock may not alter a property on a 882 resource it is still possible for the values of live properties to 883 change, even while locked, due to the requirements of their schemas. 884 Only dead properties and live properties defined to respect locks 885 are guaranteed not to change while write locked. 887 5.3 Write Locks and Null Resources 889 It is possible to assert a write lock on a null resource in order to 890 lock the name. A write locked null resource acts in all ways as a 891 null resource other than it MUST respond to a PROPFIND request and 892 MUST support the lockdiscovery and supportedlock properties. 894 Until a method such as PUT or MKCOL is executed, the resource stays 895 in the null state with the exception of the behavior stated above. 897 If the resource is unlocked without a PUT, MKCOL, or similar method 898 having been executed, the resource is no longer required to support 899 the PROPFIND method or the lockdiscovery and supportedlock 900 properties. 902 5.4 Write Locks and Collections 904 A write lock on a collection prevents the addition or removal of 905 members of the collection by non-lock owners. As a consequence, 906 when a principal issues a request to create a new internal member of 907 a write locked collection using PUT or POST, or to remove an 908 existing internal member of a write locked collection using DELETE, 909 this request MUST fail if the principal does not have a write lock 910 on the collection. 912 However, if a write lock request is issued to a collection 913 containing internal member resources that are currently locked in a 914 manner which conflicts with the write lock, the request MUST fail 915 with a 425 Locked status code. 917 If a lock owner causes a resource to be added as an internal member 918 of a locked collection then the new resource is automatically added 919 to the lock. This is the only mechanism that allows a resource to 921 be added to a write lock. Thus, for example, if the collection 922 /a/b/ is write locked and the resource /c is moved to /a/b/c then 923 /a/b/c will be added to the write lock. 925 5.5 Write Locks and COPY/MOVE 927 A COPY method invocation MUST NOT duplicate any write locks active 928 on the source. However, as previously noted, if the COPY copies the 929 resource into a collection that is depth locked then the resource 930 will be added to the lock. 932 A MOVE does not move the write lock with the resource. There are two 933 exceptions to this rule. First, as noted in section 5.4, if the MOVE 934 makes the resource a child of a collection that is depth locked then 935 the resource will be under the same lock. Second, if a depth locked 936 resource is moved to a destination that is within the scope of the 937 same depth lock (e.g., within the namespace tree covered by the 938 lock), the moved resource is still a member of the lock. In both 939 cases a Lock-Token header MUST be submitted containing a lock token 940 for the lock on the source, if locked, and on the destination. 942 5.6 Refreshing Write Locks 944 A client MUST NOT submit the same write lock request twice. Note 945 that a client is always aware it is resubmitting the same lock 946 request because it must include the Lock-Token header in order to 947 make the request for a resource that is already locked. 949 However, a client MAY submit a LOCK method with a Lock-Token header 950 but without a body. This form of LOCK MAY only be used to "refresh" 951 a lock. Currently, refreshing a lock only means that any timers 952 associated with the lock are re-set. 954 A server MAY return a Timeout header with a lock refresh that is 955 different than the Timeout header returned when the lock was 956 originally requested. Additionally clients MAY submit Timeout 957 headers of arbitrary value with their lock refresh requests. 958 Servers, as always, MAY ignore Timeout headers submitted by the 959 client. 961 If an error is received in response to a refresh LOCK request the 962 client MUST assume that the lock was not refreshed. 964 5.7 Write Locks and The Lock-Token Request Header 966 If a user agent is not required to have knowledge about a lock when 967 requesting an operation on a locked resource, the following scenario 968 might occur. Program A, run by User A, takes out a write lock on a 969 resource. Program B, also run by User A, has no knowledge of the 970 lock taken out by Program A, yet performs a PUT to the locked 971 resource. In this scenario, the PUT succeeds because locks are 972 associated with a principal, not a program, and thus program B, 973 because it is acting with principal A's credential, is allowed to 974 perform the PUT. However, had program B known about the lock, it 975 would not have overwritten the resource, preferring instead to 976 present a dialog box describing the conflict to the user. Due to 977 this scenario, a mechanism is needed to prevent different programs 978 from accidentally ignoring locks taken out by other programs with 979 the same authorization. 981 In order to prevent these collisions the Lock-Token request header, 982 defined in Section 8.7, is introduced. 984 5.7.1 Write Lock Token Example 986 >>Request 988 COPY /~fielding/index.html HTTP/1.1 989 Host: www.ics.uci.edu 990 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 991 Lock-Token: 992 Authorization: Digest username="fielding", 993 realm="fielding@ics.uci.edu", nonce="...", 994 uri="/~fielding/index.html", response="...", 995 opaque="..." 997 >>Response 999 HTTP/1.1 204 No Content 1001 In this example, even though both the source and destination are 1002 locked, only one lock token must be submitted, for the lock on the 1003 destination. This is due to the source resource not being modified 1004 during a COPY, and hence unaffected by the write lock. The 1005 Authorization header provides the Digest authentication credentials 1006 for the principal making the request (note that the nonce, response, 1007 and opaque fields have not been calculated for this example). The 1008 source and the destination resources are both located within the 1009 same authentication realm, therefore only one set of Authorization 1010 credentials needs to be submitted. 1012 6 Notational Conventions 1014 Since this document describes a set of extensions to the HTTP/1.1 1015 protocol, the augmented BNF used herein to describe protocol 1016 elements is exactly the same as described in Section 2.1 of 1017 [Fielding et al., 1997]. Since this augmented BNF uses the basic 1018 production rules provided in Section 2.2 of [Fielding et al., 1997], 1019 these rules apply to this document as well. 1021 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 1022 "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 1023 document are to be interpreted as described in RFC 2119 [Bradner, 1024 1997]. 1026 7 HTTP Methods for Distributed Authoring 1028 7.1 PROPFIND 1030 The PROPFIND method retrieves properties defined on the Request-URI, 1031 if the resource does not have any internal members, or on the 1032 Request-URI and potentially its member resources, if the resource 1033 does have internal members. All DAV compliant resources MUST 1034 support the PROPFIND method. 1036 A client MAY submit a Depth header with a value of "0", "1", or 1037 "infinity" with a PROPFIND on a resource with internal members. DAV 1038 compliant servers MUST support the "0", "1" and "infinity" 1039 behaviors. By default, the PROPFIND method without a Depth header 1040 MUST act as if a "Depth: infinity" header was included. 1042 A client MAY submit a propfind XML element in the body of the 1043 request method describing what information is being requested. It 1044 is possible to request particular property values, all property 1045 values, or a list of the names of the resource's properties. A 1046 client MAY choose not to submit a request body. An empty request 1047 body MUST be treated as a request for the names and values of all 1048 properties. 1050 The response is a text/xml message body that contains a multistatus 1051 XML element that describes the results of the attempts to retrieve 1052 the various properties. If a property was successfully retrieved 1053 then its value MUST be returned in a prop XML element. 1055 If there is an error retrieving a property then a proper error 1056 result must be included. Requests to retrieve the value of a 1057 property which does not exist is an error and MUST be noted with a 1058 response XML element which contains a 404 Not Found status value. 1060 Consequently, the multistatus XML element for a resource with 1061 members MUST include a response XML element for each member of the 1062 resource, to whatever depth was requested. Each response XML element 1063 MUST contain an href XML element that identifies the resource on 1064 which the properties in the prop XML element are defined. Results 1065 for a PROPFIND on a resource with internal members are returned as a 1066 flat list whose order of entries is not significant. 1068 In the case of allprop and propname, if a principal does not have 1069 the right to know if a particular property exists then a 404 Not 1070 Found MUST be returned. 1072 The results of this method SHOULD NOT be cached. 1074 7.1.1 Example: Retrieving Named Properties 1076 >>Request 1078 PROPFIND /files/ HTTP/1.1 1079 Host: www.foo.bar 1080 Depth: 0 1081 Content-type: text/xml 1082 Content-Length: xyz 1084 1085 1086 1087 http://www.foo.bar/boxschema/bigbox 1088 http://www.foo.bar/boxschema/author 1089 http://www.foo.bar/boxschema/DingALing 1090 http://www.foo.bar/boxschema/Random 1091 1093 >>Response 1095 HTTP/1.1 207 Multi-Status 1096 Content-Type: text/xml 1097 Content-Length: xxxxx 1099 1100 1101 1102 1103 1104 http://www.foo.bar/files/ 1105 1106 1107 1108 Box type A 1109 1110 1111 J.J. Johnson 1112 1113 1114 HTTP/1.1 200 OK 1115 1116 1117 1118 HTTP/1.1 403 Forbidden 1119 The user does not have access to 1120 the DingALing property. 1121 1122 1123 1124 There has been an access violation error. 1125 1126 1128 In this example, PROPFIND is executed on the collection 1129 http://www.foo.bar/files/. The specified depth is zero, hence the 1130 PROPFIND applies only to the collection itself, and not to any of 1131 its members. The propfind XML element specifies the name of four 1132 properties whose values are being requested. In this case only two 1133 properties were returned, since the principal issuing the request 1134 did not have sufficient access rights to see the third and fourth 1135 properties. 1137 7.1.2 Example: Using allprop to Retrieve All Properties 1139 >>Request 1141 PROPFIND /container/ HTTP/1.1 1142 Host: www.foo.bar 1143 Depth: 1 1144 Content-Type: text/xml 1145 Content-Length: xxxxx 1147 1148 1149 1150 1151 1153 >>Response 1155 HTTP/1.1 207 Multi-Status 1156 Content-Type: text/xml 1157 Content-Length: xxxxx 1158 1159 1160 1161 1162 1163 http://www.foo.bar/container/ 1164 1165 1166 1167 Box type A 1168 1169 1170 Hadrian 1171 1172 1173 1997-12-01T17:42:21-08:00 1174 1175 1176 Example collection 1177 1178 1179 http://www.acme.com/front/ 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 HTTP 1.1 200 OK 1192 1193 1194 1195 http://www.foo.bar/container/front.html 1196 1197 1198 1199 Box type B 1200 1201 1202 1997-12-01T18:27:21-08:00 1203 1204 1205 Example HTML resource 1206 1207 1208 4525 1209 1210 1211 text/html 1212 1213 1214 zzyzx 1215 1216 1217 Monday, 12-Jan-98 09:25:56 GMT 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 HTTP 1.1 200 OK 1230 1231 1232 1234 In this example, PROPFIND was invoked on the resource 1235 http://www.foo.bar/container/ with a Depth header of 1, meaning the 1236 request applies to the resource and its children, and a propfind XML 1237 element containing the allprop XML element, meaning the request 1238 should return the name and value of all properties defined on each 1239 resource. 1241 The resource http://www.foo.bar/container/ has seven properties 1242 defined on it, named http://www.foo.bar/boxschema/bigbox, 1243 http://www.foo.bar/boxschema/author, 1244 http://www.iana.org/standards/dav/creationdate, 1245 http://www.iana.org/standards/dav/displayname, 1246 http://www.iana.org/standards/dav/externalmembers, 1247 http://www.iana.org/standards/dav/resourcetype, and 1248 http://www.iana.org/standards/dav/supportedlock. The last five 1249 properties are WebDAV-specific, defined in Section 12. Since GET is 1250 not supported on this resource, the get-* properties (e.g., get- 1251 content-length) are not defined on this resource. The DAV-specific 1252 properties assert that "container" was created on December 1, 1997, 1253 at 5:42:21PM, in a time zone 8 hours west of GMT (creationdate), has 1254 a name of "Example collection" (displayname), a single external 1255 member resource, http://www.acme.com/front/ (externalmembers), a 1256 collection resource type (resourcetype), and supports exclusive 1257 write and shared write locks (supportedlock). 1259 The resource http://www.foo.bar/container/front.html has nine 1260 properties defined on it, named http://www.foo.bar/boxschema/bigbox 1261 (another instance of the "bigbox" property type), 1262 http://www.iana.org/standards/dav/creationdate, 1263 http://www.iana.org/standards/dav/displayname, 1264 http://www.iana.org/standards/dav/getcontentlength, 1265 http://www.iana.org/standards/dav/getcontenttype, 1266 http://www.iana.org/standards/dav/getetag, 1267 http://www.iana.org/standards/dav/getlastmodified, 1268 http://www.iana.org/standards/dav/resourcetype, and 1269 http://www.iana.org/standards/dav/supportedlock. The DAV-specific 1270 properties assert that "front.html" was created on December 1, 1997, 1271 at 6:27:21PM, in a time zone 8 hours west of GMT (creationdate), has 1272 a name of "Example HTML resource" (displayname), a content length of 1273 4525 (getcontentlength), a MIME type of "text/html" 1274 (getcontenttype), an entity tag of "zzyzx" (getetag), was last 1275 modified on Monday, January 12, 1998, at 09:25:56 GMT 1276 (getlastmodified), has an undefined resource type, meaning that it 1277 is not a collection (resourcetype), and supports both exclusive 1278 write and shared write locks (supportedlock). 1280 7.1.3 Example: Using propname to Retrieve all Property Names 1282 >>Request 1284 PROPFIND /container/ HTTP/1.1 1285 Host: www.foo.bar 1286 Content-Type: text/xml 1287 Content-Length: xxxxx 1289 1290 1291 1292 1293 1295 >>Response 1297 HTTP/1.1 207 Multi-Status 1298 Content-Type: text/xml 1299 Content-Length: xxxx 1301 1302 1303 1304 1305 1306 http://www.foo.bar/container/ 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 HTTP 1.1 200 OK 1318 1319 1320 1321 http://www.foo.bar/container/front.html 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 HTTP 1.1 200 OK 1335 1336 1337 1339 In this example, PROPFIND is invoked on the collection resource 1340 http://www.foo.bar/container/, with a propfind XML element 1341 containing the propname XML element, meaning the name of all 1342 properties should be returned. Since no depth header is present, it 1343 assumes its default value of "infinity", meaning the name of the 1344 properties on the collection and all its progeny should be returned. 1346 Consistent with the previous example, resource 1347 http://www.foo.bar/container/ has seven properties defined on it, 1348 http://www.foo.bar/boxschema/bigbox, and 1349 http://www.foo.bar/boxschema/author, 1350 http://www.iana.org/standards/dav/creationdate, 1351 http://www.iana.org/standards/dav/displayname, 1352 http://www.iana.org/standards/dav/externalmembers, 1353 http://www.iana.org/standards/dav/resourcetype, and 1354 http://www.iana.org/standards/dav/supportedlock. The resource 1355 http://www.foo.bar/container/index.html, a member of the "container" 1356 collection, has nine properties defined on it, 1357 http://www.foo.bar/boxschema/bigbox, 1358 http://www.iana.org/standards/dav/creationdate, 1359 http://www.iana.org/standards/dav/displayname, 1360 http://www.iana.org/standards/dav/get-content-length, 1361 http://www.iana.org/standards/dav/get-content-type, 1362 http://www.iana.org/standards/dav/get-etag, 1363 http://www.iana.org/standards/dav/get-last-modified, 1364 http://www.iana.org/standards/dav/resourcetype, and 1365 http://www.iana.org/standards/dav/supportedlock. 1367 7.2 PROPPATCH 1369 The PROPPATCH method processes instructions specified in the request 1370 body to set and/or remove properties defined on the resource 1371 identified by Request-URI. 1373 All DAV compliant resources MUST support the PROPPATCH method and 1374 MUST process instructions that are specified using the 1375 propertyupdate, set, and remove XML elements of the DAV schema. 1376 Execution of the directives in this method is, of course, subject to 1377 access control constraints. DAV compliant resources SHOULD support 1378 the setting of arbitrary dead properties. 1380 The request message body of a PROPPATCH method MUST contain at least 1381 one propertyupdate XML element. Instruction processing MUST occur in 1382 the order instructions are received (i.e., from top to bottom). 1383 Instructions MUST either all be executed or none executed. Thus if 1384 any error occurs during processing all executed instructions MUST be 1385 undone and a proper error result returned. Instruction processing 1387 details can be found in the definition of the set and remove 1388 instructions in Section 11.13. 1390 If PROPPATCH is invoked on a null resource (e.g., a deleted 1391 resource), an empty resource is created, and the PROPPATCH 1392 directives are performed on this new resource. 1394 7.2.1 Status Codes 1396 200 OK - The command succeeded. As there can be a mixture of sets 1397 and removes in a body, a 201 Created seems inappropriate. 1399 403 Forbidden - The client, for reasons the server chooses not to 1400 specify, cannot alter one of the properties. 1402 409 Conflict - The client has provided a value whose semantics are 1403 not appropriate for the property. This includes trying to set read- 1404 only properties. 1406 413 Request Entity Too Long - If a particular property is too long 1407 to be recorded then a composite XML error will be returned 1408 indicating the offending property. 1410 7.2.2 Example 1412 >>Request 1414 PROPPATCH /bar.html HTTP/1.1 1415 Host: www.foo.com 1416 Content-Type: text/xml 1417 Content-Length: xxxx 1419 1420 1421 1422 1423 1424 1425 1426 Jim Whitehead 1427 Roy Fielding 1428 1429 1430 1431 1432 1433 1434 1436 >>Response 1438 HTTP/1.1 207 Multi-Status 1439 Content-Type: text/xml 1440 Content-Length: xxxxx 1442 1443 1444 1445 1446 1447 http://www.foo.com/bar 1448 1449 1450 HTTP/1.1 424 Method Failure 1451 1452 1453 1454 HTTP/1.1 409 Conflict 1455 1456 Copyright Owner can not be deleted or 1457 altered. 1458 1459 1461 In this example, the client requests the server to set the value of 1462 the http://www.w3.com/standards/z39.50/Authors property, and to 1463 remove the property http://www.w3.com/standards/z39.50/Copyright- 1464 Owner. Since the Copyright-Owner property could not be removed, no 1465 property modifications occur. The Method Failure status code for 1466 the Authors property indicates this action would have succeeded if 1467 it were not for the conflict with removing the Copyright-Owner 1468 property. 1470 7.3 MKCOL Method 1472 The MKCOL method is used to create a new collection. All DAV 1473 compliant resources MUST support the MKCOL method. 1475 7.3.1 Request 1477 MKCOL creates a new collection resource at the location specified by 1478 the Request-URI. If the resource identified by the Request-URI is 1479 non-null then the MKCOL must fail. During MKCOL processing, a 1480 server MUST make the Request-URI a member of its parent collection. 1481 If no such ancestor exists, the method MUST fail. When the MKCOL 1482 operation creates a new collection resource, all ancestors MUST 1483 already exist, or the method MUST fail with a 409 Conflict status 1484 code. For example, if a request to create collection /a/b/c/d/ is 1485 made, and neither /a/b/ nor /a/b/c/ exists, the request MUST fail. 1487 When MKCOL is invoked without a request body, the newly created 1488 collection has no members. 1490 A MKCOL request message MAY contain a message body. The behavior of 1491 a MKCOL request when the body is present is limited to creating 1492 collections, members of a collection, bodies of members and 1493 properties on the collections or members. If the server receives a 1494 MKCOL request entity type it does not support or understand it MUST 1495 respond with a 415 Unsupported Media Type status code. The exact 1496 behavior of MKCOL for various request media types is undefined in 1497 this document, and will be specified in separate documents. 1499 7.3.2 Response Codes 1501 Responses from a MKCOL request are not cacheable, since MKCOL has 1502 non-idempotent semantics. 1504 201 Created - The collection or structured resource was created in 1505 its entirety. 1507 403 Forbidden - This indicates at least one of two conditions: 1) 1508 The server does not allow the creation of collections at the given 1509 location in its namespace, and 2) The parent collection of the 1510 Request-URI exists but cannot accept members. 1512 405 Method Not Allowed - MKCOL can only be executed on a 1513 deleted/non-existent resource. 1515 409 Conflict - A collection cannot be made at the Request-URI until 1516 one or more intermediate collections have been created. 1518 415 Unsupported Media Type- The server does not support the request 1519 type of the body. 1521 423 Insufficient Space on Resource - The resource does not have 1522 sufficient space to record the state of the resource after the 1523 execution of this method. 1525 7.3.3 Example 1527 This example creates a collection called /webdisc/xfiles/ on the 1528 server www.server.org. 1530 >>Request 1532 MKCOL /webdisc/xfiles/ HTTP/1.1 1533 Host: www.server.org 1535 >>Response 1537 HTTP/1.1 201 Created 1539 7.4 ADDREF Method 1541 The ADDREF method is used to add external members to a resource. 1542 All DAV compliant collection resources MUST support the ADDREF 1543 method. All other DAV compliant resources MAY support the ADDREF 1544 method as appropriate. 1546 7.4.1 The Request 1548 The ADDREF method adds the URI specified in the Collection-Member 1549 header as an external member to the collection specified by the 1550 Request-URI. 1552 It is not an error if the URI specified in the Collection-Member 1553 header already exists as an external member of the collection. 1554 However, after processing the ADDREF there MUST be only one instance 1555 of the URI in the collection. If the URI specified in the 1556 Collection-Member header already exists as an internal member of the 1557 collection, the ADDREF method MUST fail with a 412 Precondition 1558 Failed status code. 1560 More than one Collection-Member request header MUST NOT be used with 1561 the ADDREF method. 1563 7.4.2 Example 1565 >>Request 1567 ADDREF /~ejw/dav/ HTTP/1.1 1568 Host: www.ics.uci.edu 1569 Collection-Member: http://www.iana.org/standards/dav/ 1571 >>Response 1573 HTTP/1.1 204 No Content 1575 This example adds the URI http://www.iana.org/standards/dav/ as an 1576 external member resource of the collection 1577 http://www.ics.uci.edu/~ejw/dav/. 1579 7.5 DELREF Method 1581 The DELREF method is used to remove external members from a 1582 resource. All DAV compliant collection resources MUST support the 1583 DELREF method. All other DAV compliant resources MUST support the 1584 DELREF method only if they support the ADDREF method. 1586 7.5.1 The Request 1588 The DELREF method removes the URI specified in the Collection-Member 1589 header from the collection specified by the Request-URI. 1591 DELREFing a URI which is not a member of the collection is not an 1592 error. DELREFing an internal member MUST fail with a 412 1593 Precondition Failed status code. 1595 More than one Collection-Member request header MUST NOT be used with 1596 the DELREF method. 1598 7.5.2 Example 1600 >>Request 1602 DELREF /~ejw/dav/ HTTP/1.1 1603 Host: www.ics.udi.edu 1604 Collection-Member: http://www.iana.org/standards/dav/ 1606 >>Response 1608 HTTP/1.1 204 No Content 1610 This example removes the URI http://www.iana.org/standards/dav/, an 1611 external member resource, from the collection 1612 http://www.ics.uci.edu/~ejw/dav/. 1614 7.6 GET, HEAD for Collections 1615 The semantics of GET are unchanged when applied to a collection, 1616 since GET is defined as, "retrieve whatever information (in the form 1617 of an entity) is identified by the Request-URI" [Fielding et al., 1618 1997]. GET when applied to a collection MAY return the contents of 1619 an "index.html" resource, a human-readable view of the contents of 1620 the collection, or something else altogether. Hence it is possible 1621 that the result of a GET on a collection will bear no correlation to 1622 the state of the collection. 1624 Similarly, since the definition of HEAD is a GET without a response 1625 message body, the semantics of HEAD are unmodified when applied to 1626 collection resources. 1628 7.7 POST for Collections 1630 Since by definition the actual function performed by POST is 1631 determined by the server and often depends on the particular 1632 resource, the behavior of POST when applied to collections cannot be 1633 meaningfully modified because it is largely undefined. Thus the 1634 semantics of POST are unmodified when applied to a collection. 1636 7.8 DELETE 1638 7.8.1 DELETE for Non-Collection Resources 1640 If the DELETE method is issued to a non-collection resource which is 1641 an internal member of a collection, then during DELETE processing a 1642 server MUST remove the Request-URI from its parent collection. A 1643 server MAY remove the URI of a deleted resource from any collections 1644 of which the resource is an external member. 1646 7.8.2 DELETE for Collections 1648 The DELETE method on a collection MUST act as if a Depth = infinity 1649 header was used on it. A client MUST NOT submit a Depth header on a 1650 DELETE on a collection with any value but infinity. 1652 DELETE instructs that the collection specified in the request-URI, 1653 the records of its external member resources, and all its internal 1654 member resources, are to be deleted. 1656 If any member cannot be deleted then all of the member's ancestors 1657 MUST NOT be deleted, so as to maintain the namespace. 1659 Any headers included with DELETE MUST be applied in processing every 1660 resource to be deleted. 1662 When the DELETE method has completed processing it MUST return a 1663 consistent namespace. 1665 The response SHOULD be a Multi-Status response that describes the 1666 result of the DELETE on each affected resource. 1668 7.8.2.1 Example 1670 >>Request 1672 DELETE /container/ HTTP/1.1 1673 Host: www.foo.bar 1675 >>Response 1677 HTTP/1.1 207 Multi-Status 1678 Content-Type: text/xml 1679 Content-Length: xxxxx 1681 1682 1683 1684 1685 http://www.foo.bar/container/resource1 1686 http://www.foo.bar/container/resource2 1687 HTTP/1.1 200 OK 1688 1689 1690 http://www.foo.bar/container/ 1691 HTTP/1.1 424 Method Failure 1692 1693 1694 http://www.foo.bar/container/resource3 1695 HTTP/1.1 425 Locked 1696 1697 1699 In this example the attempt to delete 1700 http://www.foo.bar/container/resource3 failed because it is locked, 1701 and no lock token was submitted with the request. Consequently, the 1702 attempt to delete http://www.foo.bar/container/ also failed, but 1703 resource1 and resource2 were deleted. Even though a Depth header has 1704 not been included, a depth of infinity is assumed because the method 1705 is on a collection. As this example illustrates, DELETE processing 1706 need not be atomic. 1708 7.9 PUT 1710 7.9.1 PUT for Non-Collection Resources 1712 A PUT performed on an existing resource replaces the GET response 1713 entity of the resource. Properties defined on the resource MAY be 1714 recomputed during PUT processing but are not otherwise effected. 1715 For example, if a server recognizes the content type of the request 1716 body, it may be able to automatically extract information that could 1717 be profitably exposed as properties. 1719 A PUT that would result in the creation of a resource without an 1720 appropriately scoped parent collection MUST fail with a 409 1721 Conflict. 1723 7.9.2 PUT for Collections 1725 As defined in the HTTP/1.1 specification [Fielding et al., 1997], 1726 the "PUT method requests that the enclosed entity be stored under 1727 the supplied Request-URI." Since submission of an entity 1728 representing a collection would implicitly encode creation and 1729 deletion of resources, this specification intentionally does not 1730 define a transmission format for creating a collection using PUT. 1731 Instead, the MKCOL method is defined to create collections. If a 1732 PUT is invoked on a collection resource it MUST fail. 1734 When the PUT operation creates a new non-collection resource all 1735 ancestors MUST already exist. If all ancestors do not exist, the 1736 method MUST fail with a 409 Conflict status code. For example, if 1737 resource /a/b/c/d.html is to be created and /a/b/c/ does not exist, 1738 then the request must fail. 1740 7.10 COPY Method 1742 The COPY method creates a duplicate of the source resource, given by 1743 the Request-URI, in the destination resource, given by the 1744 Destination header. The Destination header MUST be present. The 1745 exact behavior of the COPY method depends on the type of the source 1746 resource. 1748 Support for the COPY method does not guarantee the ability to copy a 1749 resource. For example, separate programs may control resources on 1750 the same server. As a result, it may not even be possible to copy a 1751 resource to a location that appears to be on the same server. 1753 7.10.1 COPY for HTTP/1.1 resources 1755 When the source resource is not a collection the body of the 1756 destination resource MUST be octet-for-octet identical to the body 1757 of the source resource. Subsequent alterations to the destination 1758 resource will not modify the source resource. Subsequent 1759 alterations to the source resource will not modify the destination 1760 resource. Thus, all copies are performed "by-value". 1762 All properties on the source resource MUST be duplicated on the 1763 destination resource, subject to modifying headers and XML elements, 1764 following the definition for copying properties. 1766 7.10.2 COPY for Properties 1767 The following section defines how properties on a resource are 1768 handled during a COPY operation. 1770 Live properties SHOULD be duplicated as identically behaving live 1771 properties at the destination resource. If a property cannot be 1772 copied live, then its value MUST be duplicated, octet-for-octet, in 1773 an identically named, dead property on the destination resource. 1775 The propertybehavior XML element can specify that properties are 1776 copied on best effort, that all live properties MUST be successfully 1777 copied or the method MUST fail, or that a specified list of live 1778 properties MUST be successfully copied or the method must fail. The 1779 propertybehavior XML element is defined in Section 11.12. 1781 If a property on the source already exists on the destination 1782 resource and the Overwrite header is set to "T" then the property at 1783 the destination MUST be overwritten with the property from the 1784 source. If the Overwrite header is "F" and the previous situation 1785 exists, then the COPY MUST fail with a 412 Precondition Failed. 1787 7.10.3 COPY for Collections 1789 The COPY method on a collection without a Depth header MUST act as 1790 if a Depth header with value "infinity" was included. A client MAY 1791 submit a Depth header on a COPY on a collection with a value of "0" 1792 or "infinity". DAV compliant servers MUST support the "0" and 1793 "infinity" behaviors. 1795 A COPY of depth infinity instructs that the collection specified in 1796 the Request-URI and the records of its external member resources is 1797 to be copied to the location specified in the Destination header, 1798 and all its internal member resources are to be copied to a 1799 location relative to it, recursively through all levels of the 1800 collection hierarchy. 1802 A COPY of depth "0" only instructs that the collection, the 1803 properties, and the records of its external members, not its 1804 internal members, are to be copied. 1806 Any headers included with a COPY are to be applied in processing 1807 every resource to be copied. 1809 The exception to this rule is the Destination header. This header 1810 only specifies the destination for the Request-URI. When applied to 1811 members of the collection specified in the request-URI the value of 1812 Destination is to be modified to reflect the current location in the 1813 hierarchy. So, if the request-URI is "a" and the destination is "b" 1814 then when a/c/d is processed it MUST use a destination of b/c/d. 1816 When the COPY method has completed processing it MUST have created a 1817 consistent namespace at the destination. However, if an error 1818 occurs while copying an internal member collection, all members of 1819 this collection MUST NOT be copied. In this case, after detecting 1820 the error, the COPY operation SHOULD try to finish as much of the 1821 original copy operation as possible. So, for example, if an 1822 infinite depth copy operation is performed on collection /a/, which 1823 contains collections /a/b/ and /a/c/, and an error occurs copying 1824 /a/b/, an attempt should still be made to copy /a/c/. Similarly, 1825 after encountering an error copying a non-collection resource as 1826 part of an infinite depth copy, the server SHOULD try to finish as 1827 much of the original copy operation as possible. 1829 The response is a Multi-Status status code with an entity body that 1830 describes the result of the COPY on each affected resource. The 1831 href XML element in the response refers to the resource that was to 1832 be copied, not the resource that was created as a result of the 1833 copy. In other words, each entry indicates whether the copy on the 1834 resource specified in the href XML element succeeded or failed and 1835 why. 1837 The exception to this rule is for errors that occurred on the 1838 destination. For example, if the destination was locked the 1839 response would indicate the destination URL and a 425 Locked error. 1841 7.10.4 Type Interactions 1843 If the destination resource identifies a collection and the 1844 Overwrite header is "T", prior to performing the copy the server 1845 MUST perform a DELETE operation on the collection. 1847 7.10.5 Status Codes 1849 201 Created - The source resource was successfully copied. The copy 1850 operation resulted in the creation of a new resource. 1852 204 No Content - The source resource was successfully copied to a 1853 pre-existing destination resource. Since there is no entity body in 1854 the response, 204 No Content is used instead of 200 OK. 1856 412 Precondition Failed - This status code MUST be returned if the 1857 server was unable to maintain the liveness of the properties listed 1858 in the propertybehavior XML element, or if the Overwrite header is 1859 "F", and the state of the destination resource is non-null. 1861 423 Insufficient Space on Resource - The destination resource does 1862 not have sufficient space to record the state of the resource after 1863 the execution of this method. 1865 425 Locked - The destination resource was locked and either a valid 1866 Lock-Token header was not submitted, or the Lock-Token header 1867 identifies a lock held by another principal. 1869 502 Bad Gateway - This may occur when the destination is on another 1870 server and the destination server refuses to accept the resource. 1872 7.10.6 Overwrite Example 1874 This example shows resource 1875 http://www.ics.uci.edu/~fielding/index.html being copied to the 1876 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1877 204 No Content status code indicates the existing resource at the 1878 destination was overwritten. 1880 >>Request 1882 COPY /~fielding/index.html HTTP/1.1 1883 Host: www.ics.uci.edu 1884 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1886 >>Response 1888 HTTP/1.1 204 No Content 1890 7.10.7 No Overwrite Example 1892 The following example shows the same copy operation being performed, 1893 except with the Overwrite header set to "F." A response of 412 1894 Precondition Failed is returned because the destination resource has 1895 a non-null state. 1897 >>Request 1899 COPY /~fielding/index.html HTTP/1.1 1900 Host: www.ics.uci.edu 1901 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1902 Overwrite: F 1904 >>Response 1906 HTTP/1.1 412 Precondition Failed 1908 7.10.8 Collection Example 1910 >>Request 1912 COPY /container/ HTTP/1.1 1913 Host: www.foo.bar 1914 Destination: http://www.foo.bar/othercontainer/ 1915 Depth: infinity 1916 Content-Type: text/xml 1917 Content-Length: xxxxx 1919 1920 1921 1922 * 1923 1925 >>Response 1927 HTTP/1.1 207 Multi-Status 1928 Content-Type: text/xml 1929 Content-Length: xxxxx 1931 1932 1933 1934 1935 http://www.foo.bar/othercontainer/resource1 1936 http://www.foo.bar/othercontainer/resource2 1937 http://www.foo.bar/othercontainer/ 1938 HTTP/1.1 201 Created 1939 1941 1942 http://www.foo.bar/othercontainer/R2/ 1943 http://www.foo.bar/othercontainer/R2/D2 1944 HTTP/1.1 412 Precondition Failed 1945 1946 1948 The Depth header is unnecessary as the default behavior of COPY on a 1949 collection is to act as if a "Depth: infinity" header had been 1950 submitted. In this example most of the resources, along with the 1951 collection, were copied successfully. However the collection R2 1952 failed, most likely due to a problem with maintaining the liveness 1953 of properties (this is specified by the propertybehavior XML 1954 element). Since an error occurred copying R2, R2's member D2 was not 1955 copied. 1957 7.11 MOVE Method 1959 The MOVE operation on a non-collection resource is the logical 1960 equivalent of a copy (COPY) followed by a delete, where the actions 1961 are performed atomically. All DAV compliant resources MUST support 1962 the MOVE method. 1964 However, support for the MOVE method does not guarantee the ability 1965 to move a resource to a particular destination. For example, 1966 separate programs may actually control different sets of resources 1967 on the same server. Therefore, it may not even be possible to move 1968 a resource within a namespace that appears to belong to the same 1969 server. 1971 If a resource exists at the destination, the destination resource 1972 will be DELETEd as a side effect of the MOVE operation, subject to 1973 the restrictions of the Overwrite header. 1975 7.11.1 MOVE for Collections 1977 A MOVE of depth infinity instructs that the collection specified in 1978 the Request-URI, including the records of its external member 1979 resources, is to be moved to the location specified in the 1980 Destination header, and all its internal member resources are to be 1981 moved to locations relative to it, recursively through all levels of 1982 the collection hierarchy. 1984 The MOVE method on a collection MUST act as if a Depth "infinity" 1985 header was used on it. A client MUST NOT submit a Depth header on a 1986 MOVE on a collection with any value but "infinity". 1988 Any headers included with MOVE are to be applied in processing every 1989 resource to be moved. 1991 The exception to this rule is the Destination header. The behavior 1992 of this header is the same as given for COPY on collections. 1994 When the MOVE method has completed processing it MUST have created a 1995 consistent namespace on both the source and destination. However, if 1996 an error occurs while moving an internal member collection, all 1997 members of the failed collection MUST NOT be moved. In this case, 1998 after detecting the error, the move operation SHOULD try to finish 1999 as much of the original move as possible. So, for example, if an 2000 infinite depth move is performed on collection /a/, which contains 2001 collections /a/b/ and /a/c/, and an error occurs moving /a/b/, an 2002 attempt should still be made to try moving /a/c/. Similarly, after 2003 encountering an error moving a non-collection resource as part of an 2004 infinite depth move, the server SHOULD try to finish as much of the 2005 original move operation as possible. 2007 As specified in the definition of MOVE, a MOVE of a collection over 2008 another collection causes the destination collection and all its 2009 members to be deleted. 2011 The response is a Multi-Status response that describes the result of 2012 the MOVE on each affected resource. The href XML element in the 2013 response refers to the resource that was to be moved, not the 2014 resource that was created as a result of the move. In other words, 2015 each entry indicates whether the move on the resource specified in 2016 the href succeeded or failed and why. 2018 The exception to this rule is for errors that occurred on the 2019 destination. For example, if the destination was locked the 2020 response would indicate the destination URL and a 425 Locked error. 2022 7.11.2 Status Codes 2023 201 Created - The source resource was successfully moved, and a new 2024 resource was created at the destination. 2026 204 No Content - The move operation was successful, and the resource 2027 at the destination was overwritten. 2029 412 Precondition Failed - This status code MUST be returned if the 2030 server was unable to maintain the liveness of the properties listed 2031 in the propertybehavior XML element, or if the Overwrite header is 2032 "F", and the state of the destination resource is non-null. 2034 425 Locked - The source or the destination resource was locked and 2035 either a valid Lock-Token header was not submitted, or the Lock- 2036 Token header identifies a lock held by another principal. 2038 502 Bad Gateway - This may occur when the destination is on another 2039 server and the destination server refuses to accept the resource. 2041 7.11.3 Non-Collection Example 2043 This example shows resource 2044 http://www.ics.uci.edu/~fielding/index.html being moved to the 2045 location http://www.ics.uci.edu/users/f/fielding/index.html. The 2046 contents of the destination resource would have been overwritten if 2047 the destination resource had been non-null. In this case, since 2048 there was nothing at the destination resource, the response code is 2049 201 Created. 2051 >>Request 2053 MOVE /~fielding/index.html HTTP/1.1 2054 Host: www.ics.uci.edu 2055 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 2057 >>Response 2059 HTTP/1.1 201 Created 2060 Location: http://www.ics.uci.edu/users/f/fielding/index.html 2062 7.11.4 Collection Example 2064 >>Request 2066 MOVE /container/ HTTP/1.1 2067 Host: www.foo.bar 2068 Destination: http://www.foo.bar/othercontainer/ 2069 Overwrite: F 2070 Lock-Token: , 2071 2073 Content-Type: text/xml 2074 Content-Length: xyz 2075 Authorization: Digest username="rohit", 2076 realm="rohit@www.foo.bar", nonce="...", 2077 uri="/container/", response="...", 2078 opaque="..." 2080 2081 2082 2083 * 2084 2086 >>Response 2088 HTTP/1.1 207 Multi-Status 2089 Content-Type: text/xml 2090 Content-Length: zzz 2092 2093 2094 2095 2096 http://www.foo.bar/container/resource1 2097 http://www.foo.bar/container/resource2 2098 http://www.foo.bar/container/ 2099 HTTP/1.1 204 No Content 2100 2101 2102 http://www.foo.bar/container/C2/R2 2103 HTTP/1.1 424 Method Failure 2104 2105 http://www.foo.bar/othercontainer/C2/ 2106 HTTP/1.1 425 Locked 2107 2108 2110 In this example the client has submitted a number of lock tokens 2111 with the request. A lock token will need to be submitted for every 2112 resource, both source and destination, anywhere in the scope of the 2113 method, that is locked. In this case the proper lock token was not 2114 submitted for the destination http://www.foo.bar/othercontainer/C2/. 2115 This means that the resource /container/C2/ could not be moved. As 2116 the attempt to move /container/C2/ failed then the resource 2117 /container/C2/R2 MUST also fail since it is a child of 2118 /container/C2/. 2120 7.12 LOCK Method 2122 The following sections describe the LOCK method, which is used to 2123 take out a lock of any access type. These sections on the LOCK 2124 method describe only those semantics that are specific to the LOCK 2125 method and are independent of the access type of the lock being 2126 requested. 2128 7.12.1 Operation 2130 A LOCK method invocation creates the lock specified by the lockinfo 2131 XML element on the Request-URI. Lock method requests SHOULD have a 2132 XML request body which contains an owner XML element for this lock 2133 request, unless this is a refresh request. The LOCK request MAY have 2134 a Timeout header. 2136 A successful response to a lock invocation MUST include Lock-Token 2137 and Timeout headers. Clients MUST assume that locks may arbitrarily 2138 disappear at any time, regardless of the value given in the Timeout 2139 header. The Timeout header only indicates the behavior of the 2140 server if "extraordinary" circumstances do not occur. For example, 2141 an administrator may remove a lock at any time or the system may 2142 crash in such a way that it loses the record of the lock's 2143 existence. The response MUST also contain the value of the 2144 lockdiscovery property in a prop XML element. 2146 7.12.2 The Effect of Locks on Properties and Collections 2148 The scope of a lock is the entire state of the resource, including 2149 its body and associated properties. As a result, a lock on a 2150 resource also locks the resource's properties. 2152 For collections, a lock also affects the ability to add or remove 2153 members. The nature of the effect depends upon the type of access 2154 control involved. 2156 7.12.3 Locking Replicated Resources 2158 Some servers automatically replicate resources across multiple URLs. 2159 In such a circumstance the server MAY only accept a lock on one of 2160 the URLs if the server can guarantee that the lock will be honored 2161 across all the URLs. 2163 7.12.4 Depth and Locking 2165 The Depth header MAY be used with the LOCK method. Values other 2166 than 0 or infinity MUST NOT be used with the Depth header. 2168 A Depth header of value 0 means to just lock the resource specified 2169 by the request-URI. 2171 If the Depth header is set to infinity then the resource specified 2172 in the request-URI along with all its internal members, all the way 2173 down the hierarchy, are to be locked. A successful result will 2174 return a single lock token which represents all the resources that 2175 have been locked. If an UNLOCK is executed on this token, all 2176 associated resources are unlocked. If the lock cannot be granted to 2177 all resources, a 409 Conflict status code MUST be returned with a 2178 response entity body containing a multistatus XML element describing 2179 which resource(s) prevented the lock from being granted. Hence, 2180 partial success is not an option. Either the entire hierarchy is 2181 locked or no resources are locked. 2183 7.12.5 Interaction with other Methods 2185 The interaction of a LOCK with various methods is dependent upon the 2186 lock type. However, independent of lock type, a successful DELETE 2187 of a resource MUST cause all of its locks to be removed. 2189 7.12.6 Lock Compatibility Table 2191 The table below describes the behavior that occurs when a lock 2192 request is made on a resource. 2194 Current lock state/ Shared Lock Exclusive 2195 Lock request Lock 2197 None True True 2199 Shared Lock True False 2201 Exclusive Lock False False* 2203 Legend: True = lock MAY be granted. False = lock MUST NOT be 2204 granted. *=if the principal requesting the lock is the owner of the 2205 lock, the lock MUST be regranted. 2207 The current lock state of a resource is given in the leftmost 2208 column, and lock requests are listed in the first row. The 2209 intersection of a row and column gives the result of a lock request. 2210 For example, if a shared lock is held on a resource, and an 2211 exclusive lock is requested, the table entry is "false", indicating 2212 the lock must not be granted. 2214 If an exclusive or shared lock is re-requested by the principal who 2215 owns the lock, the lock MUST be regranted. If the lock is 2216 regranted, the same lock token that was previously issued MUST be 2217 returned. 2219 7.12.7 Lock Response 2221 A successful lock response MUST contain a Lock-Token response 2222 header, a Timeout header and a prop XML element in the response body 2223 which contains the value of the lockdiscovery property. 2225 7.12.8 Status Codes 2226 412 Precondition Failed - The included Lock-Token was not 2227 enforceable on this resource or the server could not satisfy the 2228 request in the lockinfo XML element. 2230 425 Locked - The resource is locked, so the method has been 2231 rejected. 2233 7.12.9 Example - Simple Lock Request 2235 >>Request 2237 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2238 Host: webdav.sb.aol.com 2239 Timeout: Infinite, Second-4100000000 2240 Content-Type: text/xml 2241 Content-Length: xyz 2242 Authorization: Digest username="ejw", 2243 realm="ejw@webdav.sb.aol.com", nonce="...", 2244 uri="/workspace/webdav/proposal.doc", 2245 response="...", opaque="..." 2247 2248 2249 2250 2251 2252 2253 http://www.ics.uci.edu/~ejw/contact.html 2254 2255 2257 >>Response 2259 HTTP/1.1 200 OK 2260 Lock-Token: 2261 Timeout: Second-604800 2262 Content-Type: text/xml 2263 Content-Length: xxxxx 2265 2266 2267 2268 2269 2270 2271 2272 2273 http://www.ics.uci.edu/~ejw/contact.html 2274 2275 Second-604800 2276 2277 2278 opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2279 2280 2281 2282 2283 2285 This example shows the successful creation of an exclusive write 2286 lock on resource 2287 http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The 2288 resource http://www.ics.uci.edu/~ejw/contact.html contains contact 2289 information for the owner of the lock. The server has an activity- 2290 based timeout policy in place on this resource, which causes the 2291 lock to automatically be removed after 1 week (604800 seconds). The 2292 response has a Lock-Token header that gives the lock token URL that 2293 uniquely identifies the lock created by this lock request. Note 2294 that the nonce, response, and opaque fields have not been calculated 2295 in the Authorization request header. 2297 7.12.10 Example - Refreshing a Write Lock 2299 >>Request 2301 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2302 Host: webdav.sb.aol.com 2303 Timeout: Infinite, Second-4100000000 2304 Lock-Token: 2305 Authorization: Digest username="ejw", 2306 realm="ejw@webdav.sb.aol.com", nonce="...", 2307 uri="/workspace/webdav/proposal.doc", 2308 response="...", opaque="..." 2310 >>Response 2312 HTTP/1.1 200 OK 2313 Lock-Token: 2314 Timeout: Second-604800 2315 Content-Type: text/xml 2316 Content-Length: xxxxx 2318 2319 2320 2321 2322 2323 2324 2325 2326 http://www.ics.uci.edu/~ejw/contact.html 2327 2328 Second-604800 2329 2330 2331 opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2332 2333 2334 2335 2336 2338 This request would refresh the lock, resetting any time outs. 2339 Notice that the client asked for an infinite time out but the server 2340 choose to ignore the request. In this example, the nonce, response, 2341 and opaque fields have not been calculated in the Authorization 2342 request header. 2344 7.12.11 Example - Multi-Resource Lock Request 2346 >>Request 2348 LOCK /webdav/ HTTP/1.1 2349 Host: webdav.sb.aol.com 2350 Timeout: Infinite, Second-4100000000 2351 Depth: infinity 2352 Authorization: Digest username="ejw", 2353 realm="ejw@webdav.sb.aol.com", nonce="...", 2354 uri="/workspace/webdav/proposal.doc", 2355 response="...", opaque="..." 2357 2358 2359 2360 2361 2362 2363 http://www.ics.uci.edu/~ejw/contact.html 2364 2365 2367 >>Response 2369 HTTP/1.1 207 Multistatus 2370 Content-Type: text/xml 2371 Content-Length: xxxxx 2373 2374 2375 2376 2377 http://webdav.sb.aol.com/webdav/proposal.doc 2378 http://webdav.sb.aol.com/webdav/ 2379 HTTP/1.1 424 Method Failure 2380 2381 2382 http://webdav.sb.aol.com/webdav/secret 2383 HTTP/1.1 403 Forbidden 2384 2385 2387 This example shows a request for an exclusive write lock on a 2388 collection and all its children. In this request, the client has 2389 specified that it desires an infinite length lock, if available, 2390 otherwise a timeout of 4.1 billion seconds, if available. The 2391 request entity body contains the contact information for the 2392 principal taking out the lock, in this case a web page URL. 2394 The 424 Method Failure indicates that a lock was not taken out on 2395 these resources due to an error elsewhere. Note that this does not 2396 mean that a lock would have succeeded on these resources had the 2397 other error not occurred. It only means that another error has 2398 occurred and so the entire method has been aborted. The error is a 2399 403 Forbidden response on the resource 2400 http://webdav.sb.aol.com/webdav/secret. Because this resource could 2401 not be locked, none of the resources were locked. 2403 In this example, the nonce, response, and opaque fields have not 2404 been calculated in the Authorization request header. 2406 7.13 UNLOCK Method 2408 The UNLOCK method removes the lock identified by the lock token in 2409 the Lock-Token header from the Request-URI, and all other resources 2410 included in the lock. 2412 Any DAV compliant resource which supports the LOCK method MUST 2413 support the UNLOCK method. 2415 7.13.1 Example 2417 >>Request 2419 UNLOCK /workspace/webdav/info.doc HTTP/1.1 2420 Host: webdav.sb.aol.com 2421 Lock-Token: 2422 Authorization: Digest username="ejw", 2423 realm="ejw@webdav.sb.aol.com", nonce="...", 2424 uri="/workspace/webdav/proposal.doc", 2425 response="...", opaque="..." 2427 >>Response 2429 HTTP/1.1 204 No Content 2430 In this example, the lock identified by the lock token 2431 "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is 2432 successfully removed from the resource 2433 http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock 2434 included more than just one resource, the lock is removed from all 2435 resources included in the lock. The 204 status code is used instead 2436 of 200 OK because there is no response entity body. 2438 In this example, the nonce, response, and opaque fields have not 2439 been calculated in the Authorization request header. 2441 8 HTTP Headers for Distributed Authoring 2443 8.1 Collection-Member Header 2445 CollectionMember = "Collection-Member" ":" absoluteURI ; 2446 absoluteURI is defined in section 3.2.1 of [Fielding et al., 1997] 2448 The Collection-Member header specifies the URI of an external 2449 resource to be added/deleted to/from a collection. 2451 8.2 DAV Header 2453 DAV = "DAV" ":" ["1"] [",2"] ["," 1#extend] 2455 This header indicates that the resource supports the DAV schema and 2456 protocol as specified. All DAV compliant resources MUST return the 2457 DAV header on all OPTIONS responses. 2459 The value is a list of all compliance classes that the resource 2460 supports. Note that above a comma has already been added to the 2. 2461 This is because a resource can not be level 2 compliant unless it is 2462 also level 1 compliant. Please refer to Section 13 for more details. 2463 In general, however, support for one compliance class does not 2464 entail support for any other. 2466 8.3 Depth Header 2468 Depth = "Depth" ":" ("0" | "1" | "infinity") 2470 The Depth header is used with methods executed on resources which 2471 could potentially have internal members to indicate whether the 2472 method is to be applied only to the resource (Depth = 0), to the 2473 resource and its immediate children, (Depth = 1), or the resource 2474 and all its progeny (Depth = infinity). 2476 The Depth header is only supported if a method's definition 2477 explicitly provides for such support. 2479 The following rules are the default behavior for any method that 2480 supports the Depth header. A method MAY override these defaults by 2481 defining different behavior in its definition. 2483 Methods which support the Depth header MAY choose not to support all 2484 of the header's values and MAY define, on a case by case basis, the 2485 behavior of the method if a Depth header is not present. For 2486 example, the MOVE method only supports Depth = infinity and if a 2487 Depth header is not present will act as if a Depth = infinity header 2488 had been applied. 2490 Clients MUST NOT rely upon methods executing on members of their 2491 hierarchies in any particular order or on the execution being 2492 atomic. Note that methods MAY provide guarantees on ordering and 2493 atomicity. 2495 Upon execution, a method with a Depth header will perform as much of 2496 its assigned task as possible and then return a response specifying 2497 what it was able to accomplish and what it failed to do. 2499 So, for example, an attempt to COPY a hierarchy may result in some 2500 of the members being copied and some not. 2502 Any headers on a method with a Depth header MUST be applied to all 2503 resources in the scope of the method. For example, an If-Match 2504 header will have its value applied against every resource in the 2505 method's scope and will cause the method to fail if the header fails 2506 to match. 2508 If a resource, source or destination, within the scope of the method 2509 is locked in such a way as to prevent the successful execution of 2510 the method, then the lock token for that resource MUST be submitted 2511 with the request in the Lock-Token request header. 2513 The Depth header only specifies the behavior of the method with 2514 regards to internal children. If a resource does not have internal 2515 children then the Depth header is ignored. 2517 Please note, however, that it is always an error to submit a value 2518 for the Depth header that is not allowed by the method's definition. 2519 Thus submitting a "Depth: 1" on a COPY, even if the resource does 2520 not have internal members, MUST result in a 400 Bad Request. The 2521 method should fail not because the resource doesn't have internal 2522 members, but because of the illegal value in the header. 2524 8.4 Destination Header 2526 Destination = "Destination" ":" URI 2528 The Destination header specifies a destination resource for methods 2529 such as COPY and MOVE, which take two URIs as parameters. 2531 8.5 If-None-State-Match 2533 If-None-State-Match = "If-None-State-Match" ":" 1#Coded-URL 2534 Coded-URL = "<" URI ">" 2536 The If-None-State-Match header is intended to have similar 2537 functionality to the If-None-Match header defined in section 14.26 2538 of [Fielding et al., 1997]. However the If-None-State-Match header 2539 is intended for use with any URI which represents state information 2540 about a resource, referred to as a state token. A typical example 2541 is a lock token. 2543 If any of the state tokens identifies the current state of the 2544 resource, the server MUST NOT perform the requested method. 2545 Instead, if the request method was GET, HEAD, or PROPFIND, the 2546 server SHOULD respond with a 304 Not Modified response, including 2547 the cache-related entity-header fields (particularly ETag) of the 2548 current state of the resource. For all other request methods, the 2549 server MUST respond with a status of 412 Precondition Failed. 2551 If none of the state tokens identifies the current state of the 2552 resource, the server MAY perform the requested method. 2554 If any of the tokens is not recognized, the method MUST fail with a 2555 412 Precondition Failed. 2557 Note that the "AND" and "OR" keywords specified with the If-State- 2558 Match header are intentionally not defined for If-None-State-Match, 2559 because this functionality is not required. 2561 8.6 If-State-Match 2563 If-State-Match = "If-State-Match" ":" ("AND" | "OR") 1#Coded-URL 2565 The If-State-Match header is intended to have similar functionality 2566 to the If-Match header defined in section 14.25 of [Fielding et al., 2567 1997]. However the If-State-Match header is intended for use with 2568 any URI which represents state information about a resource. A 2569 typical example is a lock token. 2571 If the AND keyword is used and all of the state tokens identify the 2572 state of the resource, then the server MAY perform the requested 2573 method. If the OR keyword is used and any of the state tokens 2574 identifies the current state of the resource, then the server MAY 2575 perform the requested method. If the keyword requirement for the 2576 keyword used is not met, the server MUST NOT perform the requested 2577 method, and MUST return a 412 Precondition Failed response. 2579 If any of the tokens is not recognized, the method MUST fail with a 2580 412 Precondition Failed. 2582 8.7 Lock-Token Request Header 2583 Lock-Token = "Lock-Token" ":" 1#Coded-URL 2585 The Lock-Token request header, containing a lock token owned by the 2586 requesting principal, is used by the principal to indicate that the 2587 principal is aware of the existence of the lock specified by the 2588 lock token. 2590 If the following conditions are met: 2592 1) The method is restricted by a lock type that requires the 2593 submission of a lock token, such as a write lock, 2594 2) The user-agent has authenticated itself as a given principal, 2595 3) The user-agent is submitting a method request to a resource on 2596 which the principal owns a write lock, 2598 Then: 2600 1) The method request MUST include a Lock-Token header with the lock 2601 token, or, 2602 2) The method MUST fail with a 409 Conflict status code. 2604 If multiple resources are involved with a method, such as the MOVE 2605 method, then the lock tokens, if any, for all affected resources, 2606 MUST be included in the Lock-Token request header. 2608 For example, Program A, used by user A, takes out a write lock on a 2609 resource. Program A then makes a number of PUT requests on the 2610 locked resource. All the requests contain a Lock-Token request 2611 header that includes the write lock token. Program B, also run by 2612 User A, then proceeds to perform a PUT to the locked resource. 2613 However, program B was not aware of the existence of the lock and so 2614 does not include the appropriate Lock-Token request header. The 2615 method is rejected even though principal A is authorized to perform 2616 the PUT. Program B can, if it so chooses, now perform lock 2617 discovery and obtain the lock token. Note that programs A and B can 2618 perform GETs without using the Lock-Token header because the ability 2619 to perform a GET is not affected by a write lock. 2621 Having a lock token provides no special access rights. Anyone can 2622 find out anyone else's lock token by performing lock discovery. 2623 Locks are to be enforced based upon whatever authentication 2624 mechanism is used by the server, not based on the secrecy of the 2625 token values. 2627 8.8 Lock-Token Response Header 2629 Lock-Token = "Lock-Token" ":" 1#Coded-URL 2631 If a resource is successfully locked then a Lock-Token header will 2632 be returned containing the lock token that represents the lock. 2634 If multiple lock-tokens are returned then they MUST all refer to the 2635 same lock. As the lock tokens all refer to the same lock a client 2636 need only record one of them. 2638 8.9 Overwrite Header 2640 Overwrite = "Overwrite" ":" ("T" | "F") 2642 The Overwrite header specifies whether the server should overwrite 2643 the state of a non-null destination resource during a COPY or MOVE. 2644 A value of "F" states that the server MUST NOT perform the COPY or 2645 MOVE operation if the state of the destination resource is non-null. 2646 By default, the value of Overwrite is "T" and a client MAY omit this 2647 header from a request when its value is "T". While the Overwrite 2648 header appears to duplicate the functionality of the If-Match: * 2649 header of HTTP/1.1, If-Match applies only to the Request-URI, and 2650 not to the Destination of a COPY or MOVE. 2652 If a COPY or MOVE is not performed due to the value of the Overwrite 2653 header, the method MUST fail with a 409 Conflict status code. 2655 8.10 Status-URI Response Header 2657 The Status-URI response header MAY be used with the 102 Processing 2658 status code to inform the client as to the status of a method. 2660 Status-URI = "Status-URI" ":" *(Status-Code "<" URI ">") ; Status- 2661 Code is defined in 6.1.1 of [Fielding et al., 1997] 2663 The URIs listed in the header are source resources which have been 2664 affected by the outstanding method. The status code indicates the 2665 resolution of the method on the identified resource. So, for 2666 example, if a MOVE method on a collection is outstanding and a 102 2667 "Processing" response with a Status-URI response header is returned, 2668 the included URIs will indicate resources that have had move 2669 attempted on them and what the result was. 2671 8.11 Timeout Header 2673 TimeOut = "Timeout" ":" 1#TimeType 2674 TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other) 2675 DAVTimeOutVal = 1*digit 2676 Other = Extend field-value ; See section 4.2 of [Fielding et al., 2677 1997] 2679 Clients MAY include Timeout headers in their LOCK requests. 2680 However, the server is not required to honor or even consider these 2681 requests. Clients MUST NOT submit a Timeout request header with any 2682 method other than a LOCK method. 2684 A Timeout request header MUST contain at least one TimeType and MAY 2685 contain multiple TimeType entries. The purpose of listing multiple 2686 TimeType entries is to indicate multiple different values and value 2687 types that are acceptable to the client. The client lists the 2688 TimeType entries in order of preference. 2690 The Timeout response header MUST use a Second value, Infinite, or a 2691 TimeType the client has indicated familiarity with. The server MAY 2692 assume a client is familiar with any TimeType submitted in a Timeout 2693 header. 2695 The "Second" TimeType specifies the number of seconds that MUST 2696 elapse between granting of the lock at the server, and the automatic 2697 removal of the lock. A server MUST not generate a timeout value for 2698 "Second" greater than 2^32-1. 2700 The timeout counter SHOULD be restarted any time an owner of the 2701 lock sends a method to any member of the lock, including unsupported 2702 methods, or methods which are unsuccessful. However the lock MUST 2703 be refreshed if a refresh LOCK method is successfully received. 2705 If the timeout expires then the lock is lost. Specifically the 2706 server SHOULD act as if an UNLOCK method was executed by the server 2707 on the resource using the lock token of the timed-out lock, 2708 performed with its override authority. Thus logs should be updated 2709 with the disposition of the lock, notifications should be sent, 2710 etc., just as they would be for an UNLOCK request. 2712 Servers are advised to pay close attention to the values submitted 2713 by clients, as they will be indicative of the type of activity the 2714 client intends to perform. For example, an applet running in a 2715 browser may need to lock a resource, but because of the instability 2716 of the environment within which the applet is running, the applet 2717 may be turned off without warning. As a result, the applet is 2718 likely to ask for a relatively small timeout value so that if the 2719 applet dies, the lock can be quickly harvested. However, a document 2720 management system is likely to ask for an extremely long timeout 2721 because its user may be planning on going off-line. 2723 9 Status Code Extensions to HTTP/1.1 2725 The following status codes are added to those defined in HTTP/1.1 2726 [Fielding et al., 1997]. 2728 9.1 102 Processing 2730 Methods can potentially take a long period of time to process, 2731 especially methods that support the Depth header. In such cases the 2732 client may time-out the connection while waiting for a response. To 2733 prevent this the server MAY return a 102 status code to indicate to 2734 the client that the server is still processing the method. 2736 If a method is taking longer than 20 seconds (a reasonable, but 2737 arbitrary value) to process the server SHOULD return a 102 2738 "Processing" response. 2740 9.2 207 Multi-Status 2742 The response provides status for multiple independent operations. 2744 9.3 422 Unprocessable Entity 2746 The server understands the content type of the request entity, but 2747 was unable to process the contained instructions. 2749 9.4 423 Insufficient Space on Resource 2751 The resource does not have sufficient space to record the state of 2752 the resource after the execution of this method. 2754 9.5 424 Method Failure 2756 The method was not executed on a particular resource within its 2757 scope because some part of the method's execution failed causing the 2758 entire method to be aborted. For example, if a resource could not 2759 be moved as part of a MOVE method, all the other resources would 2760 fail with a 424 Method Failure. 2762 9.6 425 Locked 2764 The source or destination resource of a method is locked, and either 2765 the request did not contain a valid Lock-Token header, or the lock 2766 token in the Lock-Token header identifies a lock held by another 2767 principal. 2769 10 Multi-Status Response 2771 The default 207 Multi-Status response body is a text/xml HTTP entity 2772 that contains a single XML element called multistatus, which 2773 contains a set of XML elements called response, one for each 200, 2774 300, 400, and 500 series status code generated during the method 2775 invocation. 100 series status codes MUST NOT be recorded in a 2776 response XML element. 2778 11 XML Element Definitions 2780 In the section below, the final line of each section gives the 2781 element type declaration using the format defined in [Bray, Paoli, 2782 Sperberg-McQueen, 1998]. The "Value" field, where present, specifies 2783 futher restrictions on the allowable contents of the XML element 2784 using BNF (i.e., to further restrict the values of a PCDATA 2785 element). 2787 11.1 activelock XML Element 2789 Name: activelock 2790 Namespace: http://www.iana.org/standards/dav/ 2791 Purpose: Describes a lock on a resource. 2793 2796 11.1.1 depth XML Element 2798 Name: depth 2799 Namespace: http://www.iana.org/standards/dav/ 2800 Purpose: The value of the depth header used to create a lock. 2801 Description: If this element is not included in a lockinfo element 2802 then the client MUST assume that the lock is of depth 0. 2803 Value: "0" | "infinity" 2805 2807 11.1.2 locktoken XML Element 2809 Name: locktoken 2810 Namespace: http://www.iana.org/standards/dav/ 2811 Purpose: The lock token associated with a lock. 2812 Description: The href contains an opaque lock token URI (i.e., the 2813 OpaqueLockToken-URI production in Section 4.4). 2815 2817 11.1.3 timeout XML Element 2819 Name: timeout 2820 Namespace: http://www.iana.org/standards/dav/ 2821 Purpose: The timeout associated with a lock 2822 Value: TimeType 2824 2826 11.2 collection XML Element 2828 Name: collection 2829 Namespace: http://www.iana.org/standards/dav/ 2830 Purpose: Identifies the associated resource as a collection. The 2831 resourcetype property of a collection resource MUST have this value. 2833 2835 11.3 href XML Element 2837 Name: href 2838 Namespace: http://www.iana.org/standards/dav/ 2839 Purpose: Identifies the content of the element as a URI. 2840 Value: URI ; See section 3.2.1 of [Fielding et al., 1997] 2842 2844 11.4 link XML Element 2846 Name: link 2847 Namespace: http://www.iana.org/standards/dav/ 2848 Purpose: Identifies the property as a link and contains the 2849 source and destination of that link. 2850 Description: The link XML element is used to provide the sources and 2851 destinations of a link. The name of the property containing the 2852 link XML element provides the type of the link. Link is a multi- 2853 valued element, so multiple links may be used together to indicate 2854 multiple links with the same type. 2856 2858 11.4.1 dst XML Element 2860 Name: dst 2861 Namespace: http://www.iana.org/standards/dav/ 2862 Purpose: Indicates the destination of a link 2863 Value: URI 2865 2867 11.4.2 src XML Element 2869 Name: src 2870 Namespace: http://www.iana.org/standards/dav/ 2871 Purpose: Indicates the source of a link. 2872 Value: URI 2874 2876 11.5 lockentry XML Element 2878 Name: lockentry 2879 Namespace: http://www.iana.org/standards/dav/ 2880 Purpose: Defines the types of locks that can be used with the 2881 resource. 2883 2885 11.6 lockinfo XML Element 2887 Name: lockinfo 2888 Namespace: http://www.iana.org/standards/dav/ 2889 Purpose: The lockinfo XML element is used with a LOCK method to 2890 specify the type of lock the client wishes to have created. 2892 2894 11.7 lockscope XML Element 2896 Name: lockscope 2897 Namespace: http://www.iana.org/standards/dav/ 2898 Purpose: Specifies whether a lock is an exclusive lock, or a 2899 shared lock. 2901 2903 11.7.1 exclusive XML Element 2905 Name: exclusive 2906 Namespace: http://www.iana.org/standards/dav/ 2907 Purpose: Specifies an exclusive lock 2909 2911 11.7.2 shared XML Element 2913 Name: shared 2914 Namespace: http://www.iana.org/standards/dav/ 2915 Purpose: Specifies a shared lock 2917 2919 11.8 locktype XML Element 2921 Name: locktype 2922 Namespace: http://www.iana.org/standards/dav/ 2923 Purpose: Specifies the access type of a lock. At present, this 2924 specification only defines one lock type, the write lock. 2926 2928 11.8.1 write XML Element 2930 Name: write 2931 Namespace: http://www.iana.org/standards/dav/ 2932 Purpose: Specifies a write lock. 2934 2936 11.9 multistatus XML Element 2938 Name: multistatus 2939 Namespace: http://www.iana.org/standards/dav/ 2940 Purpose: Contains multiple response messages. 2942 Description: The responsedescription at the top level is used to 2943 provide a general message describing the overarching nature of the 2944 response. If this value is available an application MAY use it 2945 instead of presenting the individual response descriptions contained 2946 within the responses. 2948 2950 11.9.1 response XML Element 2952 Name: response 2953 Namespace: http://www.iana.org/standards/dav/ 2954 Purpose: Holds a single response describing the effect of a 2955 method on resource and/or its properties. 2956 Description: A particular href MUST NOT appear more than once as the 2957 child of a response XML element under a multistatus XML element. 2958 This requirement is necessary in order to keep processing costs for 2959 a response to linear time. Essentially, this prevents having to 2960 search in order to group together all the responses by href. There 2961 are, however, no requirements regarding ordering based on href 2962 values. 2964 2967 11.9.1.1 propstat XML Element 2969 Name: propstat 2970 Namespace: http://www.iana.org/standards/dav/ 2971 Purpose: Groups together a prop and status element that is 2972 associated with a particular href element. 2973 Description: Prop MUST contain one or more empty XML elements 2974 representing the names of properties. Multiple properties may be 2975 included if the same response applies to them all. 2977 2979 11.9.1.2 status XML Element 2981 Name: status 2982 Namespace: http://www.iana.org/standards/dav/ 2983 Purpose: Holds a single HTTP status-line 2984 Value: status-line ;status-line defined in [Fielding et al., 2985 1997] 2987 2989 11.9.2 responsedescription XML Element 2991 Name: responsedescription 2992 Namespace: http://www.iana.org/standards/dav/ 2993 Purpose: Contains a message that can be displayed to the user 2994 explaining the nature of the response. 2995 Description: This XML element provides information suitable to be 2996 presented to a user. 2998 3000 11.10 owner XML Element 3002 Name: owner 3003 Namespace: http://www.iana.org/standards/dav/ 3004 Purpose: Provides information about the principal taking out a 3005 lock. 3006 Description: The owner XML element provides information sufficient 3007 for either directly contacting a principal (such as a telephone 3008 number or Email URI), or for discovering the principal (such as the 3009 URL of a homepage) who owns a lock. 3011 3013 11.11 prop XML element 3015 Name: prop 3016 Namespace: http://www.iana.org/standards/dav/ 3017 Purpose: Contains properties related to a resource. 3018 Description: The prop XML element is a generic container for 3019 properties defined on resources. All elements inside prop MUST 3020 define properties related to the resource. No other elements may be 3021 used inside of a prop element. 3023 3025 11.12 propertybehavior XML element 3027 Name: propertybehavior 3028 Namespace: http://www.iana.org/standards/dav/ 3029 Purpose: Specifies how properties are handled during a COPY or 3030 MOVE. 3031 Description: The propertybehavior XML element specifies how 3032 properties are handled during a COPY or MOVE. If this XML element 3033 is not included in the request body then the server is expected to 3034 act as defined by the default property handling behavior of the 3035 associated method. 3037 3039 11.12.1 keepalive XML element 3041 Name: keepalive 3042 Namespace: http://www.iana.org/standards/dav/ 3043 Purpose: Specifies requirements for the copying/moving of live 3044 properties. 3046 Description: If a list of URIs is included as the value of keepalive 3047 then the named properties MUST be "live" after they are copied 3048 (moved) to the destination resource of a COPY (or MOVE). If the 3049 value "*" is given for the keepalive XML element, this designates 3050 that all live properties on the source resource MUST be live on the 3051 destination. 3052 Value: "*" ; #PCDATA value can only be "*" 3054 3056 11.12.2 omit XML element 3058 Name: omit 3059 Namespace: http://www.iana.org/standards/dav/ 3060 Purpose: Indicates that the associated method MAY succeed even if 3061 the server is not able to copy/move every property on the source 3062 resource, even in a dead form. 3063 Description: The default behavior for a COPY or MOVE is to copy/move 3064 all properties or fail the method. In certain circumstances, such 3065 as when a server copies a resource over another protocol such as 3066 FTP, it may not be possible to copy/move the properties associated 3067 with the resource. Thus any attempt to copy/move over FTP would 3068 always have to fail because properties could not be moved over, even 3069 as dead properties. The omit XML element instructs the server that 3070 it should use best effort to copy properties but a failure to copy a 3071 property should not cause the method to fail. 3073 3075 11.13 propertyupdate XML element 3077 Name: propertyupdate 3078 Namespace: http://www.iana.org/standards/dav/ 3079 Purpose: Contains a request to alter the properties on a 3080 resource. 3081 Description: This XML element is a container for the information 3082 required to modify the properties on the resource. This XML element 3083 is multi-valued. 3085 3087 11.13.1 remove XML element 3089 Name: remove 3090 Namespace: http://www.iana.org/standards/dav/ 3091 Purpose: Lists the DAV properties to be removed from a resource. 3092 Description: Remove instructs that the properties specified in prop 3093 should be removed. Specifying the removal of a property that does 3094 not exist is not an error. All the XML elements in prop MUST be 3095 empty, as only the names of properties to be removed are required. 3097 3099 11.13.2 set XML element 3101 Name: set 3102 Namespace: http://www.iana.org/standards/dav/ 3103 Purpose: Lists the DAV property values to be set for a resource. 3104 Value: prop 3105 Description: This XML element MUST contain only a prop XML element. 3106 The elements contained by prop specify the name and value of 3107 properties that are set on the Request-URI. If a property already 3108 exists then its value is replaced. 3110 3112 11.14 propfind XML Element 3114 Name: propfind 3115 Namespace: http://www.iana.org/standards/dav/ 3116 Purpose: Specifies the properties to be returned from a PROPFIND 3117 method. Two special elements are specified for use with propfind, 3118 allprop and propname. 3120 3122 11.14.1 allprop XML Element 3124 Name: allprop 3125 Namespace: http://www.iana.org/standards/dav/ 3126 Purpose: The allprop XML element specifies that all property 3127 names and values on the resource are to be returned. 3129 3131 11.14.2 propname XML Element 3133 Name: propname 3134 Namespace: http://www.iana.org/standards/dav/ 3135 Purpose: the propname XML element specifies that only a list of 3136 property names on the resource is to be returned. 3138 3140 12 DAV Properties 3142 For DAV properties, the name of the property is also the same as the 3143 name of the XML element which contains its value. In the section 3144 below, the final line of each section gives the element type 3145 declaration using the format defined in [Bray, Paoli, Sperberg- 3146 McQueen, 1998]. The "Value" field, where present, specifies futher 3147 restrictions on the allowable contents of the XML element using BNF 3148 (i.e., to further restrict the values of a PCDATA element). 3150 12.1 creationdate Property 3152 Name: creationdate 3153 Namespace: http://www.iana.org/standards/dav/ 3154 Purpose: Records the time and date the resource was created. 3155 Value: ;The time and date MUST be given in ISO 8601 format 3156 defined in Appendix 2 3157 Description: This property SHOULD be defined on all DAV compliant 3158 resources. If present, it contains a timestamp of the moment when 3159 the resource was created (i.e., the moment it had non-null state). 3161 3163 12.2 displayname Property 3165 Name: displayname 3166 Namespace: http://www.iana.org/standards/dav/ 3167 Purpose: Provies a name for the resource that is suitable for 3168 presentation to a user. 3169 Description: This property SHOULD be defined on all DAV compliant 3170 resources. If present, the property contains a description of the 3171 resource that is suitable for presentation to a user. 3173 3175 12.3 externalmembers Property 3177 Name: externalmembers 3178 Namespace: http://www.iana.org/standards/dav/ 3179 Purpose: Provides the list of external members defined on the 3180 resource. 3181 Description: This property MUST be defined on any DAV compliant 3182 resource with external members. If defined it MUST contain the full 3183 list of external members. Resources MAY make this property read- 3184 only, thus only allowing its value to be altered using the 3185 ADDREF/DELREF methods. 3187 3189 12.4 getcontentlanguage Property 3191 Name: getcontentlanguage 3192 Namespace: http://www.iana.org/standards/dav/ 3193 Purpose: Contains the Content-Language header returned by a GET 3194 without accept headers 3195 Description: This property MUST be defined on any DAV compliant 3196 resource which supports GET, with the exception that if no Content- 3197 Language header is available, this property MUST NOT exist. 3198 Value: language-tag ;language-tag is defined in section 14.13 3199 of [Fielding et al., 1997] 3200 3202 12.5 getcontentlength Property 3204 Name: getcontentlength 3205 Namespace: http://www.iana.org/standards/dav/ 3206 Purpose: Contains the Content-Length header returned by a GET 3207 without accept headers. If no Content-Length header is available, 3208 this property MUST NOT exist. 3209 Description: This property MUST be defined on any DAV compliant 3210 resource which returns the Content-Length header in response to a 3211 GET. 3212 Value: content-length ; see section 14.14 of [Fielding et al., 3213 1997] 3215 3217 12.6 getcontenttype Property 3219 Name: getcontenttype 3220 Namespace: http://www.iana.org/standards/dav/ 3221 Purpose: Contains the Content-Type header returned by a GET 3222 without accept headers. If no Content-Type header is available, 3223 this property MUST NOT exist. 3224 Description: This property MUST be defined on any DAV compliant 3225 resource which returns the Content-Type header in response to a GET. 3226 Value: media-type ; defined in Section 3.7 of [Fielding et 3227 al., 1997] 3229 3231 12.7 getetag Property 3233 Name: getetag 3234 Namespace: http://www.iana.org/standards/dav/ 3235 Purpose: Contains the ETag header returned by a GET without 3236 accept headers. 3237 Description: Note that the ETag on a resource may reflect changes in 3238 any part of the state of the resource, not necessarily just a change 3239 to the response to the GET method. For example, a change to a 3240 resource's access permissions may cause the ETag to change. This 3241 property MUST be defined on any DAV compliant resource which returns 3242 the Etag header in response to a GET, except for the case if no ETag 3243 header is returned, this property MUST NOT exist. 3244 Value: entity-tag ; defined in Section 3.11 of [Fielding et 3245 al., 1997] 3247 3249 12.8 getlastmodified Property 3251 Name: getlastmodified 3252 Namespace: http://www.iana.org/standards/dav/ 3253 Purpose: Contains the Last-Modified header returned by a GET 3254 method without accept headers. 3255 Description: Note that the last-modified date on a resource may 3256 reflect changes in any part of the state of the resource, not 3257 necessarily just a change to the response to the GET method. For 3258 example, a change in a property may cause the last-modified date to 3259 change. This property MUST be defined on any DAV compliant resource 3260 which returns the Last-Modified header in response to a GET, except 3261 for the case if no Last-Modified header is returned, this property 3262 MUST NOT exist. 3263 Value: HTTP-date ; defined in Section 3.3.1 of [Fielding et 3264 al., 1997] 3266 3268 12.9 lockdiscovery Property 3270 Name: lockdiscovery 3271 Namespace: http://www.iana.org/standards/dav/ 3272 Purpose: Describes the active locks on a resource 3273 Description: The lockdiscovery property returns a listing of who has 3274 a lock, what type of lock he has, the timeout type and the time 3275 remaining on the timeout, and the associated lock token. The server 3276 is free to withhold any or all of this information if the requesting 3277 principal does not have sufficient access rights to see the 3278 requested data. A server which supports locks MUST provide the 3279 lockdiscovery property on any resource with locks on it. 3281 3283 12.9.1 Example 3285 >>Request 3287 PROPFIND /container/ HTTP/1.1 3288 Host: www.foo.bar 3289 Content-Length: xxxx 3290 Content-Type: text/xml 3292 3293 3294 3295 3297 3299 >>Response 3301 HTTP/1.1 207 Multi-Status 3302 Content-Type: text/xml 3303 Content-Length: xxxxx 3304 3305 3306 3307 3308 3309 3310 3311 3312 write 3313 exclusive 3314 0 3315 Jane Smith 3316 Infinite 3317 3318 3319 opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76 3320 3321 3322 3323 3324 3325 HTTP/1.1 200 OK 3326 3327 3328 3330 This resource has a single exclusive write lock on it, with an 3331 infinite timeout. Note that the Depth element could have been 3332 omitted as 0 is the default value of Depth. 3334 12.10 resourcetype Property 3336 Name: resourcetype 3337 Namespace: http://www.iana.org/standards/dav/ 3338 Purpose: Specifies the nature of the resource. 3339 Description: This property MUST be defined on all DAV compliant 3340 resources. The default value is empty. 3342 3344 12.11 source Property 3346 Name: source 3347 Namespace: http://www.iana.org/standards/dav/link/ 3348 Purpose: The destination of the source link identifies the 3349 resource that contains the unprocessed source of the link's source. 3350 Description: The source of the link (src) is typically the URI of 3351 the output resource on which the link is defined, and there is 3352 typically only one destination (dst) of the link, which is the URI 3353 where the unprocessed source of the resource may be accessed. When 3354 more than one link destination exists, this specification asserts no 3355 policy on ordering. 3357 3359 12.11.1 Example 3361 3362 3363 3364 3365 3366 3367 Source 3368 http://foo.bar/program 3369 http://foo.bar/src/main.c 3370 3371 3372 Library 3373 http://foo.bar/program 3374 http://foo.bar/src/main.lib 3375 3376 3377 Makefile 3378 http://foo.bar/program 3379 http://foo.bar/src/makefile 3380 3381 3382 3384 In this example the resource http://foo.bar/program has a source 3385 property that contains three links. Each link contains three 3386 elements, two of which, src and dst, are part of the DAV schema 3387 defined in this document, and one which is defined by the schema 3388 http://www.foocorp.com/project/ (Source, Library, and Makefile). A 3389 client which only implements the elements in the DAV spec will not 3390 understand the foocorp elements and will ignore them, thus seeing 3391 the expected source and destination links. An enhanced client may 3392 know about the foocorp elements and be able to present the user with 3393 additional information about the links. This example demonstrates 3394 the power of XML markup, allowing element values to be enhanced 3395 without breaking older clients. 3397 12.12 supportedlock Property 3399 Name: supportedlock 3400 Namespace: http://www.iana.org/standards/dav/ 3401 Purpose: To provide a listing of the lock capabilities supported 3402 by the resource. 3403 Description: The supportedlock property of a resource returns a 3404 listing of the combinations of scope and access types which may be 3405 specified in a lock request on the resource. Note that the actual 3406 contents are themselves controlled by access controls so a server is 3407 not required to provide information the client is not authorized to 3408 see. If supportedlock is available on "*" then it MUST define the 3409 set of locks allowed on all resources on that server. 3411 3413 12.12.1 Example 3415 >>Request 3417 PROPFIND /container/ HTTP/1.1 3418 Host: www.foo.bar 3419 Content-Length: xxxx 3420 Content-Type: text/xml 3422 3423 3424 3425 3426 3428 >>Response 3430 HTTP/1.1 207 Multi-Status 3431 Content-Type: text/xml 3432 Content-Length: xxxxx 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 HTTP/1.1 200 OK 3452 3453 3454 3456 13 DAV Compliance Classes 3457 A DAV compliant resource can choose from two classes of compliance. 3458 A client can discover the compliance classes of a resource by 3459 executing OPTIONS on the resource, and examining the "DAV" header 3460 which is returned. 3462 Since this document describes extensions to the HTTP/1.1 protocol, 3463 minimally all DAV compliant resources, clients, and proxies MUST be 3464 compliant with [Fielding et al., 1997]. 3466 Compliance classes are not necessarily sequential. A resource that 3467 is class 2 compliant MUST also be class 1 compliant; but if 3468 additional compliance classes are defined later, a resource that is 3469 class 1, 2, and 4 compliant might not be class 3 compliant. 3471 13.1 Class 1 3473 A class 1 compliant resource MUST meet all "MUST" requirements in 3474 all sections of this document. 3476 Class 1 compliant resources MUST return, at minimum, the value "1" 3477 in the DAV header on all responses to the OPTIONS method. 3479 13.2 Class 2 3481 A class 2 compliant resource MUST meet all class 1 requirements and 3482 support the supportedlock property as well as the LOCK method. It 3483 MUST also support the lockdiscovery property, since Section 12.9 3484 specifies that the LOCK method MUST also support the lockdiscovery 3485 property. 3487 Class 2 compliant resources MUST return, at minimum, the value "2" 3488 in the DAV header on all responses to the OPTIONS method. 3490 14 Internationalization Considerations 3492 In the realm of internationalization, this specification complies 3493 with the IETF Character Set Policy [Alvestrand, 1998]. In this 3494 specification, human-readable fields can be found either in the 3495 value of a property, or in an error message returned in a response 3496 entity body. In both cases, the human-readable content is encoded 3497 using XML, which has explicit provisions for character set tagging 3498 and encoding, and requires that XML processors read XML elements 3499 encoded using the UTF-8 and UCS-2 encodings of the ISO 10646 basic 3500 multilingual plane. Furthermore, XML contains provisions for 3501 encoding XML elements using other encoding schemes, notable among 3502 them UCS-4, which permits encoding of characters from any ISO 10646 3503 character plane. 3505 The default character set encoding for XML data in this 3506 specification, and in general, is UTF-8. WebDAV compliant 3507 applications MUST support the UTF-8 and UCS-2 character set 3508 encodings for XML elements, and SHOULD support the UCS-4 encoding. 3509 The XML character set encoding declaration for each supported 3510 character set MUST also be supported, since it is by using this 3511 encoding declaration that an XML processor determines the encoding 3512 of an element. 3514 XML also provides a language tagging capability for specifying the 3515 language of the contents of a particular XML element. XML uses 3516 either IANA registered language tags (see RFC 1766, [Alvestrand, 3517 1995]) or ISO 639 language tags [ISO-639] in the "xml:lang" 3518 attribute of an XML element to identify the language its content and 3519 attributes. 3521 Names used within this specification fall into three categories: 3522 names of protocol elements such as methods and headers, names of XML 3523 elements, and names of properties. Naming of protocol elements 3524 follows the precedent of HTTP, using English names encoded in 3525 USASCII for methods and headers. Since these protocol elements are 3526 not visible to users, and are in fact simply long token identifiers, 3527 they do not need to support encoding in multiple character sets. 3528 Similarly, though the names of XML elements used in this 3529 specification are English names encoded in UTF-8, these names are 3530 not visible to the user, and hence do not need to support multiple 3531 character set encodings. 3533 The name of a property defined on a resource is a URI. Although 3534 some applications (e.g., a generic property viewer) will display 3535 property URIs directly to their users, it is expected that the 3536 typical application will use a fixed set of properties, and will 3537 provide a mapping from the property name URI to a human-readable 3538 field when displaying the property name to a user. It is only in 3539 the case where the set of properties is not known ahead of time that 3540 an application need display a property name URI to a user. We 3541 recommend that applications provide human-readable property names 3542 wherever feasible. 3544 For error reporting, we follow the convention of HTTP/1.1 status 3545 codes, including with each status code a short, English description 3546 of the code (e.g., 425 Locked). While the possibility exists that a 3547 poorly crafted user agent would display this message to a user, 3548 internationalized applications will ignore this message, and display 3549 an appropriate message in the user's language and character set. 3551 Since interoperation of clients and servers does not require locale 3552 information, this specification does not specify any mechanism for 3553 transmission of this information. 3555 15 Security Considerations 3557 This section is provided to detail issues concerning security 3558 implications of which WebDAV applications need to be aware. 3560 All of the security considerations of HTTP/1.1 also apply to WebDAV. 3561 In addition, the security risks inherent in remote authoring require 3562 stronger authentication technology, and introduce several new 3563 privacy concerns, and may increase the hazards from poor server 3564 design. These issues are detailed below. 3566 15.1 Authentication of Clients 3568 Due to their emphasis on authoring, WebDAV servers need to use 3569 authentication technology to protect not just access to a network 3570 resource, but the integrity of the resource as well. Furthermore, 3571 the introduction of locking functionality requires support for 3572 authentication. 3574 A password sent in the clear over an insecure channel is an 3575 inadequate means for protecting the accessibility and integrity of a 3576 resource as the password may be intercepted. Since Basic 3577 authentication for HTTP/1.1 performs essentially clear text 3578 transmission of a password, Basic authentication MUST NOT be used to 3579 authenticate a WebDAV client to a server unless the connection is 3580 secure. Furthermore, a WebDAV server MUST NOT send Basic 3581 authentication credentials in a WWW-Authenticate header unless the 3582 connection is secure. Examples of secure connections include a 3583 Transport Layer Security (TLS) connection, or a connection over a 3584 network which is physically secure, for example, an isolated network 3585 in a building with restricted access. 3587 WebDAV applications MUST support the Digest authentication scheme 3588 [Franks, et al., 1997]. Since Digest authentication verifies that 3589 both parties to a communication know a shared secret, a password, 3590 without having to send that secret in the clear, Digest 3591 authentication avoids the security problems inherent in Basic 3592 authentication while providing a level of authentication which is 3593 useful in a wide range of scenarios. 3595 15.2 Denial of Service 3597 Denial of service attacks are of special concern to WebDAV servers. 3598 WebDAV plus HTTP enables denial of service attacks on every part of 3599 a system's resources. 3601 The underlying storage can be attacked by PUTting extremely large 3602 files. 3604 Asking for recursive operations on large collections can attack 3605 processing time. 3607 Making multiple pipelined requests on multiple connections can 3608 attack network connections. 3610 WebDAV servers need to be aware of the possibility of a denial of 3611 service attack at all levels. 3613 15.3 Security through Obscurity 3615 WebDAV provides, through the PROPFIND method, a mechanism for 3616 listing the member resources of a collection. This greatly 3617 diminishes the effectiveness of security or privacy techniques which 3618 rely only on the difficulty of discovering the names of network 3619 resources. Users of WebDAV servers are encouraged to use access 3620 control techniques to prevent unwanted access to resources, rather 3621 than depending on the relative obscurity of their resource names. 3623 15.4 Privacy Issues Connected to Locks 3625 When submitting a lock request a user agent may also submit an owner 3626 XML field giving contact information for the person taking out the 3627 lock (for those cases where a person, rather than a robot, is taking 3628 out the lock). This contact information is stored in a lockdiscovery 3629 property on the resource, and can be used by other collaborators to 3630 begin negotiation over access to the resource. However, in many 3631 cases this contact information can be very private, and should not 3632 be widely disseminated. Servers SHOULD limit read access to the 3633 lockdiscovery property as appropriate. Furthermore, user agents 3634 SHOULD provide control over whether contact information is sent at 3635 all, and if contact information is sent, control over exactly what 3636 information is sent. 3638 15.5 Privacy Issues Connected to Properties 3640 Since property values are typically used to hold information such as 3641 the author of a document, there is the possibility that privacy 3642 concerns could arise stemming from widespread access to a resource's 3643 property data. To reduce the risk of inadvertent release of private 3644 information via properties, servers are encouraged to develop access 3645 control mechanisms that separate read access to the resource body 3646 and read access to the resource's properties. This allows a user to 3647 control the dissemination of their property data without overly 3648 restricting access to the resource's contents. 3650 15.6 Reduction of Security due to Source Link 3652 HTTP/1.1 warns against providing read access to script code because 3653 it may contain sensitive information. Yet WebDAV, via its source 3654 link facility, can potentially provide a URL for script resources so 3655 they may be authored. For HTTP/1.1, a server could reasonably 3656 prevent access to source resources due to the predominance of read- 3657 only access. WebDAV, with its emphasis on authoring, encourages 3658 read and write access to source resources, and provides the source 3659 link facility to identify the source. This reduces the security 3660 benefits of eliminating access to source resources. Users and 3661 administrators of WebDAV servers should be very cautious when 3662 allowing remote authoring of scripts, limiting read and write access 3663 to the source resources to authorized principals. 3665 16 IANA Considerations 3667 This document defines two namespaces, the namespace of property 3668 names, and the namespace of WebDAV-specific XML elements used within 3669 property values. 3671 URLs are used for both names, for several reasons. Assignment of a 3672 URL does not require a request to a central naming authority, and 3673 hence allow WebDAV property names and XML elements to be quickly 3674 defined by any WebDAV user or application. URLs also provide a 3675 unique address space, ensuring that the distributed users of WebDAV 3676 will not have collisions among the property names and XML elements 3677 they create. 3679 This specification defines a distinguished set of property names and 3680 XML elements which are understood by all WebDAV applications. The 3681 property names and XML elements in this specification are all 3682 derived from the base URL: http://www.iana.org/standards/dav/ by 3683 adding a suffix to this URL, for example, 3684 http://www.iana.org/standards/dav/creationdate for the 3685 "creationdate" property. 3687 To ensure correct interoperation of this specification, IANA MUST 3688 reserve the URL namespace starting with 3689 http://www.iana.org/standards/dav/ for use by this specification, 3690 its revisions, and related WebDAV specifications. 3692 17 Terminology 3694 Collection - A resource that contains member resources. 3696 Member Resource - A resource contained by a collection. There are 3697 two types of member resources: external and internal. 3699 Internal Member Resource - A member resource of a collection whose 3700 URI is relative to the URI of the collection. 3702 External Member Resource - A member resource of a collection with an 3703 absolute URI that is not relative to its parent's URI. 3705 Property - A name/value pair that contains descriptive information 3706 about a resource. 3708 Live Property - A property whose semantics and syntax are enforced 3709 by the server. For example, a live "content-length" property would 3710 have its value, the length of the entity returned by a GET request, 3711 automatically calculated by the server. 3713 Dead Property - A property whose semantics and syntax are not 3714 enforced by the server. The server only records the value of a dead 3715 property; the client is responsible for maintaining the consistency 3716 of the syntax and semantics of a dead property. 3718 18 Copyright 3720 The following copyright notice is copied from RFC 2026 [Bradner, 3721 1996], Section 10.4, and describes the applicable copyright for this 3722 document. 3724 Copyright (C) The Internet Society January 18, 1998. All Rights 3725 Reserved. 3727 This document and translations of it may be copied and furnished to 3728 others, and derivative works that comment on or otherwise explain it 3729 or assist in its implementation may be prepared, copied, published 3730 and distributed, in whole or in part, without restriction of any 3731 kind, provided that the above copyright notice and this paragraph 3732 are included on all such copies and derivative works. However, this 3733 document itself may not be modified in any way, such as by removing 3734 the copyright notice or references to the Internet Society or other 3735 Internet organizations, except as needed for the purpose of 3736 developing Internet standards in which case the procedures for 3737 copyrights defined in the Internet Standards process must be 3738 followed, or as required to translate it into languages other than 3739 English. 3741 The limited permissions granted above are perpetual and will not be 3742 revoked by the Internet Society or its successors or assignees. 3744 This document and the information contained herein is provided on an 3745 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3746 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3747 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3748 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3749 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3751 19 Intellectual Property 3753 The following notice is copied from RFC 2026 [Bradner, 1996], 3754 Section 10.4, and describes the position of the IETF concerning 3755 intellectual property claims made against this document. 3757 The IETF takes no position regarding the validity or scope of any 3758 intellectual property or other rights that might be claimed to 3759 pertain to the implementation or use other technology described in 3760 this document or the extent to which any license under such rights 3761 might or might not be available; neither does it represent that it 3762 has made any effort to identify any such rights. Information on the 3763 IETF's procedures with respect to rights in standards-track and 3764 standards-related documentation can be found in BCP-11. Copies of 3765 claims of rights made available for publication and any assurances 3766 of licenses to be made available, or the result of an attempt made 3767 to obtain a general license or permission for the use of such 3768 proprietary rights by implementors or users of this specification 3769 can be obtained from the IETF Secretariat. 3771 The IETF invites any interested party to bring to its attention any 3772 copyrights, patents or patent applications, or other proprietary 3773 rights which may cover technology that may be required to practice 3774 this standard. Please address the information to the IETF Executive 3775 Director. 3777 20 Acknowledgements 3779 A specification such as this thrives on piercing critical review and 3780 withers from apathetic neglect. The authors gratefully acknowledge 3781 the contributions of the following people, whose insights were so 3782 valuable at every stage of our work. 3784 Terry Allen, Harald Alvestrand, Alan Babich, Dylan Barrell, Bernard 3785 Chester, Tim Berners-Lee, Dan Connolly, Jim Cunningham, Ron Daniel, 3786 Jr., Jim Davis, Keith Dawson, Mark Day, Brian Deen, Martin Duerst, 3787 David Durand, Lee Farrell, Chuck Fay, Roy Fielding, Mark Fisher, 3788 Alan Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, 3789 Dennis Hamilton, Steve Henning, Alex Hopmann, Andre van der Hoek, 3790 Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven Martin, 3791 Larry Masinter, Michael Mealling, Keith Moore, Henrik Nielsen, Kenji 3792 Ota, Bob Parker, Glenn Peterson, Jon Radoff, Saveen Reddy, Henry 3793 Sanders, Christopher Seiwald, Judith Slein, Mike Spreitzer, Einar 3794 Stefferud, Ralph Swick, Kenji Takahashi, Richard N. Taylor, Robert 3795 Thau, John Turner, Sankar Virdhagriswaran, Fabio Vitali, Gregory 3796 Woodhouse, and Lauren Wood. 3798 Two from this list deserve special mention. The contributions by 3799 Larry Masinter have been invaluable, both in helping the formation 3800 of the working group and in patiently coaching the authors along the 3801 way. In so many ways he has set high standards we have toiled to 3802 meet. The contributions of Judith Slein in clarifying the 3803 requirements, and in patiently reviewing draft after draft, both 3804 improved this specification and expanded our minds on document 3805 management. 3807 We would also like to thank John Turner for developing the XML DTD. 3809 21 References 3811 [Alvestrand, 1995] H. T. Alvestrand, "Tags for the Identification of 3812 Languages." RFC 1766. Uninett. March, 1995. 3814 [Alvestrand, 1998] H. T. Alvestrand, "IETF Policy on Character Sets 3815 and Languages." RFC XXXX, BCP YY. Maxware. January, 1998. 3817 [Bradner, 1996] S. Bradner, "The Internet Standards Process - 3818 Revision 3." RFC 2026, BCP 9. Harvard University. October, 1996. 3820 [Bradner, 1997] S. Bradner, "Key words for use in RFCs to Indicate 3821 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 3822 1997. 3824 [Bray, Paoli, Sperberg-McQueen, 1998] T. Bray, J. Paoli, C. M. 3825 Sperberg-McQueen, "Extensible Markup Language (XML)." World Wide Web 3826 Consortium Recommendation REC-XML-ZZZZ. http://www.w3.org/TR/PR-xml- 3827 971208. 3829 [Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H. 3830 Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." 3831 RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997. 3833 [ISO-639] ISO (International Organization for Standardization). ISO 3834 639:1988. "Code for the representation of names of languages." 3836 [ISO-8601] ISO (International Organization for Standardization). ISO 3837 8601:1988. "Data elements and interchange formats - Information 3838 interchange - Representation of dates and times." 3840 [Lasher, Cohen, 1995] R. Lasher, D. Cohen, "A Format for 3841 Bibliographic Records," RFC 1807. Stanford, Myricom. June, 1995. 3843 [Leach, Salz, 1997] P. J. Leach, R. Salz, "UUIDs and GUIDs." 3844 Internet-draft (expired), work-in-progress, February, 1997. 3845 http://www.internic.net/internet-drafts/draft-leach-uuids-guids- 3846 00.txt 3848 [MARC, 1994] Network Development and MARC Standards, Office, ed. 3849 1994. "USMARC Format for Bibliographic Data", 1994. Washington, DC: 3850 Cataloging Distribution Service, Library of Congress. 3852 [Miller et al., 1996] J. Miller, T. Krauskopf, P. Resnick, W. 3853 Treese, "PICS Label Distribution Label Syntax and Communication 3854 Protocols" Version 1.1, World Wide Web Consortium Recommendation 3855 REC-PICS-labels-961031. http://www.w3.org/pub/WWW/TR/REC-PICS- 3856 labels-961031.html. 3858 [Slein et al., 1997] J. A. Slein, F. Vitali, E. J. Whitehead, Jr., 3859 D. Durand, "Requirements for Distributed Authoring and Versioning 3860 Protocol for the World Wide Web." RFC XXXX. Xerox, Univ. of Bologna, 3861 U.C. Irvine, Boston Univ. YYY, 1997. 3863 [Weibel et al., 1995] S. Weibel, J. Godby, E. Miller, R. Daniel, 3864 "OCLC/NCSA Metadata Workshop Report." 3865 http://purl.oclc.org/metadata/dublin_core_report. 3867 [Yergeau, 1997] F. Yergeau, "UTF-8, a transformation format of 3868 Unicode and ISO 10646." RFC 2044. Alis Technologies. October, 1996. 3870 22 Authors' Addresses 3872 Y. Y. Goland 3873 Microsoft Corporation 3874 One Microsoft Way 3875 Redmond, WA 98052-6399 3876 Email: yarong@microsoft.com 3878 E. J. Whitehead, Jr. 3879 Dept. Of Information and Computer Science 3880 University of California, Irvine 3881 Irvine, CA 92697-3425 3882 Email: ejw@ics.uci.edu 3884 A. Faizi 3885 Netscape 3886 685 East Middlefield Road 3887 Mountain View, CA 94043 3888 Email: asad@netscape.com 3890 S. R. Carter 3891 Novell 3892 1555 N. Technology Way 3893 M/S ORM F111 3894 Orem, UT 84097-2399 3895 Email: srcarter@novell.com 3897 D. Jensen 3898 Novell 3899 1555 N. Technology Way 3900 M/S ORM F111 3901 Orem, UT 84097-2399 3902 Email: dcjensen@novell.com 3904 23 Appendices 3906 23.1 Appendix 1 - WebDAV Document Type Definition 3908 This section provides a document type definition, following the 3909 rules in [Bray, Paoli, Sperberg-McQueen, 1998], for the XML elements 3910 used in the protocol stream and in the values of properties. It 3911 collects the element definitions given in Sections 11 and 12. 3913 3917 3920 3921 3923 3924 3926 3927 3928 3930 3932 3934 3936 3938 3940 3941 3942 3944 3946 3948 3949 3950 3952 3954 3955 3956 3958 3959 3960 3962 3963 3964 3966 3968 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3983 ]> 3985 23.2 Appendix 2 - ISO 8601 Date and Time Profile 3987 The creationdate property specifies the use of the ISO 8601 date 3988 format. This section defines a profile of the ISO 8601 date format 3989 for use with this specification. This profile is quoted verbatim 3990 from draft-newman-datetime-01.txt (expired). 3992 date-time = full-date "T" full-time 3994 full-date = date-fullyear "-" date-month "-" date-mday 3995 full-time = partial-time time-offset 3997 date-fullyear = 4DIGIT 3998 date-month = 2DIGIT ; 01-12 3999 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on 4000 month/year 4001 time-hour = 2DIGIT ; 00-23 4002 time-minute = 2DIGIT ; 00-59 4003 time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules 4004 time-secfrac = "." 1*DIGIT 4005 time-numoffset = ("+" / "-") time-hour ":" time-minute 4006 time-offset = "Z" / time-numoffset 4007 partial-time = time-hour ":" time-minute ":" time-second 4008 [time-secfrac] 4010 Numeric offsets are calculated as local time minus UTC (Coordinated 4011 Universal Time). So the equivalent time in UTC can be determined by 4012 subtracting the offset from the local time. For example, 18:50:00- 4013 04:00 is the same time as 22:58:00Z. 4015 If the time in UTC is known, but the offset to local time is 4016 unknown, this can be represented with an offset of "-00:00". This 4017 differs from an offset of "Z" which implies that UTC is the 4018 preferred reference point for the specified time. 4020 23.3 Appendix 3 - Notes on Processing XML Elements 4022 XML is a flexible data format that makes it easy to submit data that 4023 appears legal but in fact is not. The philosophy of "Be flexible in 4024 what you accept and strict in what you send" still applies, but it 4025 must not be applied inappropriately. XML is extremely flexible in 4026 dealing with issues of white space, element ordering, inserting new 4027 elements, etc. This flexibility does not require extension, 4028 especially not in the area of the meaning of elements. 4030 There is no kindness in accepting illegal combinations of XML 4031 elements. At best it will cause an unwanted result and at worst it 4032 can cause real damage. 4034 23.3.1 XML Syntax Error Example 4036 The following request body for a PROPFIND method is illegal. 4038 4039 4040 4041 4042 4043 4045 The definition of the propfind element only allows for the allprop 4046 or the propname element, not both. Thus the above is an error and 4047 MUST be responded to with a 400 Bad Request. 4049 Imagine, however, that a server wanted to be "kind" and decided to 4050 pick the allprop element as the true element and respond to it. A 4051 client running over a bandwidth limited line who intended to execute 4052 a propname would be in for a big surprise if the server treated the 4053 command as an allprop. 4055 23.3.2 Unknown XML Element Example 4056 The previous example was illegal because it contained two elements 4057 that were explicitly banned from appearing together in the propfind 4058 element. However, XML is an extensible language, so one can imagine 4059 new elements being defined for use with propfind. Below is the 4060 request body of a PROPFIND and, like the previous example, MUST be 4061 rejected with a 400 Bad Request by a server that does not understand 4062 the expired-props element. 4064 4065 4066 4067 4068 4069 4071 To understand why a 400 Bad Request is returned let us look at the 4072 request body as the server unfamiliar with expired-props sees it. 4074 4075 4076 4077 4078 4080 As the server does not understand the expired-props element, by the 4081 rules of XML, it MUST ignore it. Thus the server sees an empty 4082 propfind, which by the definition of the propfind element is 4083 illegal. 4085 Please note that had the extension been additive it would not 4086 necessarily have resulted in a 400 Bad Request. For example, 4087 imagine the following request body for a PROPFIND: 4089 4090 4091 4092 4093 4094 *boss* 4095 4097 The previous example contains the fictitious element leave-out. Its 4098 purpose is to prevent the return of any property whose name matches 4099 the submitted pattern. If the previous example were submitted to a 4100 server unfamiliar with leave-out, the only result would be that the 4101 leave-out element would be ignored and a propname would be executed.