idnits 2.17.1 draft-ietf-webdav-protocol-09.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. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 15 longer pages, the longest (page 3) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 20 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 804 has weird spacing: '...ntation of a ...' == 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). -- 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 (October 22, 1998) is 9318 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 442, but not defined -- Looks like a reference, but probably isn't: '1996' on line 442 == Missing Reference: 'Extension' is mentioned on line 803, but not defined -- Looks like a reference, but probably isn't: '1' on line 4332 -- Looks like a reference, but probably isn't: '2' on line 4333 -- Looks like a reference, but probably isn't: '3' on line 4334 -- Looks like a reference, but probably isn't: '4' on line 4336 == Missing Reference: 'RFC2141' is mentioned on line 4345, but not defined ** Obsolete undefined reference: RFC 2141 (Obsoleted by RFC 8141) -- Looks like a reference, but probably isn't: '5' on line 4385 -- Looks like a reference, but probably isn't: '6' on line 4386 -- Looks like a reference, but probably isn't: '7' on line 4387 -- Looks like a reference, but probably isn't: '8' on line 4407 -- Looks like a reference, but probably isn't: '9' on line 4409 -- Looks like a reference, but probably isn't: '10' on line 4410 -- Looks like a reference, but probably isn't: '11' on line 4417 -- Looks like a reference, but probably isn't: '12' on line 4444 -- Looks like a reference, but probably isn't: '13' on line 4446 -- Looks like a reference, but probably isn't: '14' on line 4447 -- Looks like a reference, but probably isn't: '15' on line 4448 -- Looks like a reference, but probably isn't: '16' on line 4450 -- Looks like a reference, but probably isn't: '17' on line 4451 ** Obsolete normative reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-XML' ** Obsolete normative reference: RFC 2069 (Obsoleted by RFC 2617) ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-639' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-8601' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-11578' ** Obsolete normative reference: RFC 2279 (ref. 'UTF-8') (Obsoleted by RFC 3629) -- Obsolete informational reference (is this intentional?): RFC 2413 (Obsoleted by RFC 5013) -- Obsolete informational reference (is this intentional?): RFC 2376 (Obsoleted by RFC 3023) Summary: 12 errors (**), 0 flaws (~~), 9 warnings (==), 27 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 September, 1998 October 22, 1998 8 HTTP Extensions for Distributed Authoring -- 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), ftp.ietf.org (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 Contents 45 STATUS OF THIS MEMO...................................................1 46 ABSTRACT..............................................................1 47 CONTENTS..............................................................2 49 1 INTRODUCTION .......................................................7 51 2 NOTATIONAL CONVENTIONS .............................................8 53 3 TERMINOLOGY ........................................................8 55 4 DATA MODEL FOR RESOURCE PROPERTIES .................................9 56 4.1 The Resource Property Model .....................................9 57 4.2 Existing Metadata Proposals ....................................10 58 4.3 Properties and HTTP Headers ....................................10 59 4.4 Property Values ................................................10 60 4.5 Property Names .................................................11 61 4.6 Media Independent Links ........................................11 63 5 COLLECTIONS OF WEB RESOURCES ......................................11 64 5.1 HTTP URL Namespace Model .......................................12 65 5.2 Collection Resources ...........................................12 66 5.3 Creation and Retrieval of Collection Resources .................13 67 5.4 Source Resources and Output Resources ..........................14 69 6 LOCKING ...........................................................15 70 6.1 Exclusive Vs. Shared Locks .....................................15 71 6.2 Required Support ...............................................16 72 6.3 Lock Tokens ....................................................16 73 6.4 opaquelocktoken Lock Token URI Scheme ..........................17 74 6.4.1 Node Field Generation Without the IEEE 802 Address ..........17 75 6.5 Lock Capability Discovery ......................................19 76 6.6 Active Lock Discovery ..........................................19 77 6.7 Usage Considerations ...........................................19 79 7 WRITE LOCK ........................................................20 80 7.1 Methods Restricted by Write Locks ..............................20 81 7.2 Write Locks and Lock Tokens ....................................20 82 7.3 Write Locks and Properties .....................................20 83 7.4 Write Locks and Null Resources .................................21 84 7.5 Write Locks and Collections ....................................21 85 7.6 Write Locks and the If Request Header ..........................22 86 7.6.1 Example - Write Lock ........................................22 87 7.7 Write Locks and COPY/MOVE ......................................22 88 7.8 Refreshing Write Locks .........................................23 89 8 HTTP METHODS FOR DISTRIBUTED AUTHORING ............................23 91 8.1 PROPFIND .......................................................24 92 8.1.1 Example - Retrieving Named Properties .......................25 93 8.1.2 Example - Using allprop to Retrieve All Properties ..........26 94 8.1.3 Example - Using propname to Retrieve all Property Names .....29 96 8.2 PROPPATCH ......................................................30 97 8.2.1 Status Codes for use with 207 (Multi-Status) ................31 98 8.2.2 Example - PROPPATCH .........................................31 100 8.3 MKCOL Method ...................................................32 101 8.3.1 Request .....................................................32 102 8.3.2 Status Codes ................................................33 103 8.3.3 Example - MKCOL .............................................33 105 8.4 GET, HEAD for Collections ......................................34 107 8.5 POST for Collections ...........................................34 109 8.6 DELETE .........................................................34 110 8.6.1 DELETE for Non-Collection Resources .........................34 111 8.6.2 DELETE for Collections ......................................34 113 8.7 PUT ............................................................35 114 8.7.1 PUT for Non-Collection Resources ............................35 115 8.7.2 PUT for Collections .........................................36 117 8.8 COPY Method ....................................................36 118 8.8.1 COPY for HTTP/1.1 resources .................................36 119 8.8.2 COPY for Properties .........................................36 120 8.8.3 COPY for Collections ........................................37 121 8.8.4 COPY and the Overwrite Header ...............................38 122 8.8.5 Status Codes ................................................38 123 8.8.6 Example - COPY with Overwrite ...............................39 124 8.8.7 Example - COPY with No Overwrite ............................39 125 8.8.8 Example - COPY of a Collection ..............................39 127 8.9 MOVE Method ....................................................40 128 8.9.1 MOVE for Properties .........................................40 129 8.9.2 MOVE for Collections ........................................41 130 8.9.3 MOVE and the Overwrite Header ...............................42 131 8.9.4 Status Codes ................................................42 132 8.9.5 Example - MOVE of a Non-Collection ..........................42 133 8.9.6 Example - MOVE of a Collection ..............................43 135 8.10 LOCK Method ....................................................43 136 8.10.1 Operation ...................................................44 137 8.10.2 The Effect of Locks on Properties and Collections ...........44 138 8.10.3 Locking Replicated Resources ................................44 139 8.10.4 Depth and Locking ...........................................44 140 8.10.5 Interaction with other Methods ..............................45 141 8.10.6 Lock Compatibility Table ....................................45 142 8.10.7 Status Codes ................................................46 143 8.10.8 Example - Simple Lock Request ...............................46 144 8.10.9 Example - Refreshing a Write Lock ...........................48 145 8.10.10 Example - Multi-Resource Lock Request ......................49 147 8.11 UNLOCK Method ..................................................50 148 8.11.1 Example - UNLOCK ............................................50 150 9 HTTP HEADERS FOR DISTRIBUTED AUTHORING ............................51 151 9.1 DAV Header .....................................................51 152 9.2 Depth Header ...................................................51 153 9.3 Destination Header .............................................52 154 9.4 If Header ......................................................52 155 9.4.1 No-tag-list Production ......................................53 156 9.4.2 Tagged-list Production ......................................53 157 9.4.3 not Production ..............................................54 158 9.4.4 Matching Function ...........................................54 159 9.4.5 If Header and Non-DAV Compliant Proxies .....................55 160 9.5 Lock-Token Header ..............................................55 161 9.6 Overwrite Header ...............................................55 162 9.7 Status-URI Response Header .....................................55 163 9.8 Timeout Request Header .........................................56 165 10 STATUS CODE EXTENSIONS TO HTTP/1.1 ..............................57 166 10.1 102 Processing .................................................57 167 10.2 207 Multi-Status ...............................................57 168 10.3 422 Unprocessable Entity .......................................57 169 10.4 423 Locked .....................................................58 170 10.5 424 Failed Dependency ..........................................58 171 10.6 507 Insufficient Storage .......................................58 173 11 MULTI-STATUS RESPONSE ...........................................58 175 12 XML ELEMENT DEFINITIONS .........................................58 176 12.1 activelock XML Element .........................................58 177 12.1.1 depth XML Element ...........................................59 178 12.1.2 locktoken XML Element .......................................59 179 12.1.3 timeout XML Element .........................................59 180 12.2 collection XML Element .........................................59 181 12.3 href XML Element ...............................................59 182 12.4 link XML Element ...............................................60 183 12.4.1 dst XML Element .............................................60 184 12.4.2 src XML Element .............................................60 185 12.5 lockentry XML Element ..........................................60 186 12.6 lockinfo XML Element ...........................................60 187 12.7 lockscope XML Element ..........................................61 188 12.7.1 exclusive XML Element .......................................61 189 12.7.2 shared XML Element ..........................................61 190 12.8 locktype XML Element ...........................................61 191 12.8.1 write XML Element ...........................................61 192 12.9 multistatus XML Element ........................................62 193 12.9.1 response XML Element ........................................62 194 12.9.2 responsedescription XML Element .............................63 195 12.10owner XML Element ..............................................63 196 12.11prop XML element ...............................................63 197 12.12propertybehavior XML element ...................................63 198 12.12.1 keepalive XML element ......................................64 199 12.12.2 omit XML element ...........................................64 200 12.13propertyupdate XML element .....................................64 201 12.13.1 remove XML element .........................................65 202 12.13.2 set XML element ............................................65 203 12.14propfind XML Element ...........................................65 204 12.14.1 allprop XML Element ........................................65 205 12.14.2 propname XML Element .......................................66 207 13 DAV PROPERTIES ..................................................66 208 13.1 creationdate Property ..........................................66 209 13.2 displayname Property ...........................................66 210 13.3 getcontentlanguage Property ....................................67 211 13.4 getcontentlength Property ......................................67 212 13.5 getcontenttype Property ........................................67 213 13.6 getetag Property ...............................................67 214 13.7 getlastmodified Property .......................................68 215 13.8 lockdiscovery Property .........................................68 216 13.8.1 Example - Retrieving the lockdiscovery Property .............68 217 13.9 resourcetype Property ..........................................69 218 13.10source Property ................................................70 219 13.10.1 Example - A source Property ................................70 220 13.11supportedlock Property .........................................71 221 13.11.1 Example - Retrieving the supportedlock Property ............71 223 14 INSTRUCTIONS FOR PROCESSING XML IN DAV ..........................72 225 15 DAV COMPLIANCE CLASSES ..........................................73 226 15.1 Class 1 ........................................................73 227 15.2 Class 2 ........................................................73 228 16 INTERNATIONALIZATION CONSIDERATIONS .............................73 230 17 SECURITY CONSIDERATIONS .........................................75 231 17.1 Authentication of Clients ......................................75 232 17.2 Denial of Service ..............................................75 233 17.3 Security through Obscurity .....................................76 234 17.4 Privacy Issues Connected to Locks ..............................76 235 17.5 Privacy Issues Connected to Properties .........................76 236 17.6 Reduction of Security due to Source Link .......................76 237 17.7 Implications of XML External Entities ..........................77 238 17.8 Risks Connected with Lock Tokens ...............................77 240 18 IANA CONSIDERATIONS .............................................78 242 19 COPYRIGHT .......................................................78 244 20 INTELLECTUAL PROPERTY ...........................................79 246 21 ACKNOWLEDGEMENTS ................................................80 248 22 REFERENCES ......................................................81 249 22.1 Normative References ...........................................81 250 22.2 Informational References .......................................82 252 23 AUTHORS' ADDRESSES ..............................................83 254 24 APPENDICES ......................................................84 255 24.1 Appendix 1 - WebDAV Document Type Definition ...................84 256 24.2 Appendix 2 - ISO 8601 Date and Time Profile ....................85 257 24.3 Appendix 3 - Notes on Processing XML Elements ..................86 258 24.3.1 Notes on Empty XML Elements .................................86 259 24.3.2 Notes on Illegal XML Processing .............................86 260 24.4 Appendix 4 -- XML Namespaces for WebDAV ........................88 261 24.4.1 Introduction ................................................88 262 24.4.2 Motivation and Summary ......................................88 263 24.4.3 Declaring Namespaces ........................................89 264 24.4.4 Qualified Names .............................................90 265 24.4.5 Using Qualified Names .......................................91 266 24.4.6 Applying Namespaces to Elements and Attributes ..............92 267 24.4.7 Uniqueness of Attributes ....................................94 268 24.4.8 Conformance .................................................95 269 24.4.9 Meaning of Qualified Names ..................................95 271 1 Introduction 273 This document describes an extension to the HTTP/1.1 protocol that 274 allows clients to perform remote web content authoring operations. 275 This extension provides a coherent set of methods, headers, request 276 entity body formats, and response entity body formats that provide 277 operations for: 279 Properties: The ability to create, remove, and query information 280 about Web pages, such as their authors, creation dates, etc. Also, 281 the ability to link pages of any media type to related pages. 283 Collections: The ability to create sets of related documents and to 284 retrieve a hierarchical membership listing (like a directory listing 285 in a file system). 287 Locking: The ability to keep more than one person from working on a 288 document at the same time. This prevents the "lost update problem," 289 in which modifications are lost as first one author then another 290 writes changes without merging the other author's changes. 292 Namespace Operations: The ability to instruct the server to copy and 293 move Web resources. 295 Requirements and rationale for these operations are described in a 296 companion document, "Requirements for a Distributed Authoring and 297 Versioning Protocol for the World Wide Web" [RFC2291]. 299 The sections below provide a detailed introduction to resource 300 properties (section 3), collections of resources (section 5), and 301 locking operations (section 6). These sections introduce the 302 abstractions manipulated by the WebDAV-specific HTTP methods 303 described in section 8, "HTTP Methods for Distributed Authoring". 305 In HTTP/1.1, method parameter information was exclusively encoded in 306 HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter 307 information either in an Extensible Markup Language (XML) [REC-XML] 308 request entity body, or in an HTTP header. The use of XML to encode 309 method parameters was motivated by the ability to add extra XML 310 elements to existing structures, providing extensibility; and by 311 XML's ability to encode information in ISO 10646 character sets, 312 providing internationalization support. As a rule of thumb, 313 parameters are encoded in XML entity bodies when they have unbounded 314 length, or when they may be shown to a human user and hence require 315 encoding in an ISO 10646 character set. Otherwise, parameters are 316 encoded within HTTP headers. Section 9 describes the new HTTP 317 headers used with WebDAV methods. 319 In addition to encoding method parameters, XML is used in WebDAV to 320 encode the responses from methods, providing the extensibility and 321 internationalization advantages of XML for method output, as well as 322 input. 324 XML elements used in this specification are defined in section 12. 326 The XML namespace extension (Appendix 4) is also used in this 327 specification in order to allow for new XML elements to be added 328 without fear of colliding with other element names. 330 While the status codes provided by HTTP/1.1 are sufficient to 331 describe most error conditions encountered by WebDAV methods, there 332 are some errors that do not fall neatly into the existing 333 categories. New status codes developed for the WebDAV methods are 334 defined in section 10. Since some WebDAV methods may operate over 335 many resources, the Multi-Status response has been introduced to 336 return status information for multiple resources. The Multi-Status 337 response is described in section 11. 339 WebDAV employs the property mechanism to store information about the 340 current state of the resource. For example, when a lock is taken 341 out on a resource, a lock information property describes the current 342 state of the lock. Section 13 defines the properties used within the 343 WebDAV specification. 345 Finishing off the specification are sections on what it means to be 346 compliant with this specification (section 15), on 347 internationalization support (section 16), and on security (section 348 17). 350 2 Notational Conventions 352 Since this document describes a set of extensions to the HTTP/1.1 353 protocol, the augmented BNF used herein to describe protocol 354 elements is exactly the same as described in section 2.1 of 355 [RFC2068]. Since this augmented BNF uses the basic production rules 356 provided in section 2.2 of [RFC2068], these rules apply to this 357 document as well. 359 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 360 "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 361 document are to be interpreted as described in RFC 2119 [RFC2119]. 363 3 Terminology 365 URI/URL - As defined in [RFC2396]. 367 Collection - A resource that contains member resources and meets the 368 requirements in section 5 of this specification. 370 Member Resource - A resource contained by a collection. 372 Internal Member Resource - A member resource of a collection whose 373 URI is immediately relative to the URI of the collection. 375 Property - A name/value pair that contains descriptive information 376 about a resource. 378 Live Property - A property whose semantics and syntax are enforced 379 by the server. For example, the live "getcontentlength" property 380 has its value, the length of the entity returned by a GET request, 381 automatically calculated by the server. 383 Dead Property - A property whose semantics and syntax are not 384 enforced by the server. The server only records the value of a dead 385 property; the client is responsible for maintaining the consistency 386 of the syntax and semantics of a dead property. 388 Null Resource - A resource which responds with a 404 (Not Found) to 389 any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK. 390 A NULL resource MUST NOT appear as a member of its parent 391 collection. 393 4 Data Model for Resource Properties 395 4.1 The Resource Property Model 397 Properties are pieces of data that describe the state of a resource. 398 Properties are data about data. 400 Properties are used in distributed authoring environments to provide 401 for efficient discovery and management of resources. For example, a 402 'subject' property might allow for the indexing of all resources by 403 their subject, and an 'author' property might allow for the 404 discovery of what authors have written which documents. 406 The DAV property model consists of name/value pairs. The name of a 407 property identifies the property's syntax and semantics, and 408 provides an address by which to refer to its syntax and semantics. 410 There are two categories of properties: "live" and "dead". A live 411 property has its syntax and semantics enforced by the server. Live 412 properties include cases where a) the value of a property is read- 413 only, maintained by the server, and b) the value of the property is 414 maintained by the client, but the server performs syntax checking on 415 submitted values. All instances of a given live property MUST comply 416 with the definition associated with that property name. A dead 417 property has its syntax and semantics enforced by the client; the 418 server merely records the value of the property verbatim. 420 4.2 Existing Metadata Proposals 422 Properties have long played an essential role in the maintenance of 423 large document repositories, and many current proposals contain some 424 notion of a property, or discuss web metadata more generally. These 425 include PICS [REC-PICS], PICS-NG, XML, Web Collections, and several 426 proposals on representing relationships within HTML. Work on PICS-NG 427 and Web Collections has been subsumed by the Resource Definition 428 Framework (RDF) metadata activity of the World Wide Web Consortium. 429 RDF consists of a network-based data model and an XML representation 430 of that model. 432 Some proposals come from a digital library perspective. These 433 include the Dublin Core [RFC2413] metadata set and the Warwick 434 Framework [Lagoze, 1996], a container architecture for different 435 metadata schemas. The literature includes many examples of 436 metadata, including MARC [USMARC], a bibliographic metadata format, 437 and a technical report bibliographic format employed by the Dienst 438 system [RFC1807]. Additionally, the proceedings from the first IEEE 439 Metadata conference describe many community-specific metadata sets. 441 Participants of the 1996 Metadata II Workshop in Warwick, UK 442 [Lagoze, 1996], noted that "new metadata sets will develop as the 443 networked infrastructure matures" and "different communities will 444 propose, design, and be responsible for different types of 445 metadata." These observations can be corroborated by noting that 446 many community-specific sets of metadata already exist, and there is 447 significant motivation for the development of new forms of metadata 448 as many communities increasingly make their data available in 449 digital form, requiring a metadata format to assist data location 450 and cataloging. 452 4.3 Properties and HTTP Headers 454 Properties already exist, in a limited sense, in HTTP message 455 headers. However, in distributed authoring environments a 456 relatively large number of properties are needed to describe the 457 state of a resource, and setting/returning them all through HTTP 458 headers is inefficient. Thus a mechanism is needed which allows a 459 principal to identify a set of properties in which the principal is 460 interested and to set or retrieve just those properties. 462 4.4 Property Values 464 The value of a property when expressed in XML MUST be well formed. 465 XML has been chosen because it is a flexible, self-describing, 466 structured data format that supports rich schema definitions, and 467 because of its support for multiple character sets. XML's self- 468 describing nature allows any property's value to be extended by 469 adding new elements. Older clients will not break when they 470 encounter extensions because they will still have the data specified 471 in the original schema and will ignore elements they do not 472 understand. XML's support for multiple character sets allows any 473 human-readable property to be encoded and read in a character set 474 familiar to the user. XML's support for multiple human languages, 475 using the "xml:lang" attribute, handles cases where the same 476 character set is employed by multiple human languages. 478 4.5 Property Names 480 A property name is a universally unique identifier that is 481 associated with a schema that provides information about the syntax 482 and semantics of the property. 484 Because a property's name is universally unique, clients can depend 485 upon consistent behavior for a particular property across multiple 486 resources, on the same and across different servers, so long as that 487 property is "live" on the resources in question, and the 488 implementation of the live property is faithful to its definition. 490 The XML namespace mechanism, which is based on URIs [RFC2396], is 491 used to name properties because it prevents namespace collisions and 492 provides for varying degrees of administrative control. 494 The property namespace is flat; that is, no hierarchy of properties 495 is explicitly recognized. Thus, if a property A and a property A/B 496 exist on a resource, there is no recognition of any relationship 497 between the two properties. It is expected that a separate 498 specification will eventually be produced which will address issues 499 relating to hierarchical properties. 501 Finally, it is not possible to define the same property twice on a 502 single resource, as this would cause a collision in the resource's 503 property namespace. 505 4.6 Media Independent Links 507 Although HTML resources support links to other resources, the Web 508 needs more general support for links between resources of any media 509 type. WebDAV provides such links. A WebDAV link is a special type 510 of property value, formally defined in section 12.4, that allows 511 typed connections to be established between resources of any media 512 type. The property value consists of source and destination Uniform 513 Resource Locators (URLs); the property name identifies the link 514 type. 516 5 Collections of Web Resources 518 This section provides a description of a new type of Web resource, 519 the collection, and discusses its interactions with the HTTP URL 520 namespace. The purpose of a collection resource is to model 521 collection-like objects (e.g., file system directories) within a 522 server's namespace. 524 All DAV compliant resources MUST support the HTTP URL namespace 525 model specified herein. 527 5.1 HTTP URL Namespace Model 529 The HTTP URL namespace is a hierarchical namespace where the 530 hierarchy is delimited with the "/" character. 532 An HTTP URL namespace is said to be consistent if it meets the 533 following rule: for every non-null resource A, there exists a non- 534 null resource B that is a collection and has resource A as an 535 internal member. The root of the namespace is exempt from the 536 previous rule. 538 Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL 539 namespace be consistent. However, certain WebDAV methods are 540 prohibited from producing results that cause namespace 541 inconsistencies. 543 5.2 Collection Resources 545 A collection is a resource whose state consists of at least a list 546 of internal members and a set of properties, but which may have 547 additional state such as entity bodies returned by GET. An internal 548 member resource MUST have a URI that is immediately relative to the 549 base URI of the collection. That is, the internal member's URI is 550 equal to the parent collection's URI plus an additional segment 551 where segment is defined in section 3.2.1 of RFC 2068 [Fielding et 552 al., 1996]. 554 Any given internal member MUST only belong to the collection once, 555 i.e., it is illegal to have multiple instances of the same URI in a 556 collection. Properties defined on collections behave exactly as do 557 properties on non-collection resources. 559 For all WebDAV compliant resources A and B for which B is the parent 560 of A in the HTTP URL namespace hierarchy, B MUST be a collection 561 which has A as an internal member. So, if http://foo.com/bar/blah is 562 WebDAV compliant and if http://foo.com/bar/ is WebDAV compliant then 563 http://foo.com/bar/ must be a collection and must contain 564 http://foo.com/bar/blah as an internal member. 566 Collection resources MAY list their non-WebDAV compliant children in 567 the HTTP URL namespace hierarchy as internal members but are not 568 required to do so. For example, if http://foo.com/bar/blah is not 569 WebDAV compliant and http://foo.com/bar/ is a collection then 570 http://foo.com/bar/blah may or may not be listed as an internal 571 member of http://foo.com/bar/. 573 If a WebDAV compliant resource has no WebDAV compliant children in 574 the HTTP URL namespace hierarchy then the WebDAV compliant resource 575 is not required to be a collection. 577 There is a standing convention that when a collection is referred to 578 by its name without a trailing slash, the trailing slash is 579 automatically appended. Due to this, a resource may accept a URI 580 without a trailing "/" to point to a collection. In this case it 581 SHOULD return a content-location header in the response pointing to 582 the URL ending with the "/". For example, if a client invokes a 583 method on http://foo.bar/blah (no trailing slash), the resource 584 http://foo.bar/blah/ (trailing slash) may respond as if the 585 operation were invoked on it, and should return a content-location 586 header with http://foo.bar/blah/ in it. In general clients SHOULD 587 use the "/" form of collection names. 589 A resource MAY be a collection but not be WebDAV compliant. That 590 is, the resource may comply with all the rules set out in this 591 specification regarding how a collection is to behave without 592 necessarily supporting all methods that a WebDAV compliant resource 593 is required to support. In such a case the resource may return the 594 dav:resourcetype property with the value dav:collection but MUST NOT 595 return a DAV header containing the value "1" on an OPTIONS response. 597 5.3 Creation and Retrieval of Collection Resources 599 This document specifies the MKCOL method to create new collection 600 resources, rather than using the existing HTTP/1.1 PUT or POST 601 method, for the following reasons: 603 In HTTP/1.1, the PUT method is defined to store the request body at 604 the location specified by the Request-URI. While a description 605 format for a collection can readily be constructed for use with PUT, 606 the implications of sending such a description to the server are 607 undesirable. For example, if a description of a collection that 608 omitted some existing resources were PUT to a server, this might be 609 interpreted as a command to remove those members. This would extend 610 PUT to perform DELETE functionality, which is undesirable since it 611 changes the semantics of PUT, and makes it difficult to control 612 DELETE functionality with an access control scheme based on methods. 614 While the POST method is sufficiently open-ended that a "create a 615 collection" POST command could be constructed, this is undesirable 616 because it would be difficult to separate access control for 617 collection creation from other uses of POST. 619 The exact definition of the behavior of GET and PUT on collections 620 is defined later in this document. 622 5.4 Source Resources and Output Resources 624 For many resources, the entity returned by a GET method exactly 625 matches the persistent state of the resource, for example, a GIF 626 file stored on a disk. For this simple case, the URL at which a 627 resource is accessed is identical to the URL at which the source 628 (the persistent state) of the resource is accessed. This is also 629 the case for HTML source files that are not processed by the server 630 prior to transmission. 632 However, the server can sometimes process HTML resources before they 633 are transmitted as a return entity body. For example, a server- 634 side-include directive within an HTML file might instruct a server 635 to replace the directive with another value, such as the current 636 date. In this case, what is returned by GET (HTML plus date) 637 differs from the persistent state of the resource (HTML plus 638 directive). Typically there is no way to access the HTML resource 639 containing the unprocessed directive. 641 Sometimes the entity returned by GET is the output of a data- 642 producing process that is described by one or more source resources 643 (that may not even have a location in the URL namespace). A single 644 data-producing process may dynamically generate the state of a 645 potentially large number of output resources. An example of this is 646 a CGI script that describes a "finger" gateway process that maps 647 part of the namespace of a server into finger requests, such as 648 http://www.foo.bar.org/finger_gateway/user@host. 650 In the absence of distributed authoring capabilities, it is 651 acceptable to have no mapping of source resource(s) to the URI 652 namespace. In fact, preventing access to the source resource(s) has 653 desirable security benefits. However, if remote editing of the 654 source resource(s) is desired, the source resource(s) should be 655 given a location in the URI namespace. This source location should 656 not be one of the locations at which the generated output is 657 retrievable, since in general it is impossible for the server to 658 differentiate requests for source resources from requests for 659 process output resources. There is often a many-to-many 660 relationship between source resources and output resources. 662 On WebDAV compliant servers the URI of the source resource(s) may be 663 stored in a link on the output resource with type DAV:source (see 664 section 13.10 for a description of the source link property). 665 Storing the source URIs in links on the output resources places the 666 burden of discovering the source on the authoring client. Note that 667 the value of a source link is not guaranteed to point to the correct 668 source. Source links may break or incorrect values may be entered. 669 Also note that not all servers will allow the client to set the 670 source link value. For example a server which generates source 671 links on the fly for its CGI files will most likely not allow a 672 client to set the source link value. 674 6 Locking 676 The ability to lock a resource provides a mechanism for serializing 677 access to that resource. Using a lock, an authoring client can 678 provide a reasonable guarantee that another principal will not 679 modify a resource while it is being edited. In this way, a client 680 can prevent the "lost update" problem. 682 This specification allows locks to vary over two client-specified 683 parameters, the number of principals involved (exclusive vs. shared) 684 and the type of access to be granted. This document defines locking 685 for only one access type, write. However, the syntax is extensible, 686 and permits the eventual specification of locking for other access 687 types. 689 6.1 Exclusive Vs. Shared Locks 691 The most basic form of lock is an exclusive lock. This is a lock 692 where the access right in question is only granted to a single 693 principal. The need for this arbitration results from a desire to 694 avoid having to merge results. 696 However, there are times when the goal of a lock is not to exclude 697 others from exercising an access right but rather to provide a 698 mechanism for principals to indicate that they intend to exercise 699 their access rights. Shared locks are provided for this case. A 700 shared lock allows multiple principals to receive a lock. Hence any 701 principal with appropriate access can get the lock. 703 With shared locks there are two trust sets that affect a resource. 704 The first trust set is created by access permissions. Principals 705 who are trusted, for example, may have permission to write to the 706 resource. Among those who have access permission to write to the 707 resource, the set of principals who have taken out a shared lock 708 also must trust each other, creating a (typically) smaller trust set 709 within the access permission write set. 711 Starting with every possible principal on the Internet, in most 712 situations the vast majority of these principals will not have write 713 access to a given resource. Of the small number who do have write 714 access, some principals may decide to guarantee their edits are free 715 from overwrite conflicts by using exclusive write locks. Others may 716 decide they trust their collaborators will not overwrite their work 717 (the potential set of collaborators being the set of principals who 718 have write permission) and use a shared lock, which informs their 719 collaborators that a principal may be working on the resource. 721 The WebDAV extensions to HTTP do not need to provide all of the 722 communications paths necessary for principals to coordinate their 723 activities. When using shared locks, principals may use any out of 724 band communication channel to coordinate their work (e.g., face-to- 725 face interaction, written notes, post-it notes on the screen, 726 telephone conversation, Email, etc.) The intent of a shared lock is 727 to let collaborators know who else may be working on a resource. 729 Shared locks are included because experience from web distributed 730 authoring systems has indicated that exclusive locks are often too 731 rigid. An exclusive lock is used to enforce a particular editing 732 process: take out an exclusive lock, read the resource, perform 733 edits, write the resource, release the lock. This editing process 734 has the problem that locks are not always properly released, for 735 example when a program crashes, or when a lock owner leaves without 736 unlocking a resource. While both timeouts and administrative action 737 can be used to remove an offending lock, neither mechanism may be 738 available when needed; the timeout may be long or the administrator 739 may not be available. 741 6.2 Required Support 743 A WebDAV compliant server is not required to support locking in any 744 form. If the server does support locking it may choose to support 745 any combination of exclusive and shared locks for any access types. 747 The reason for this flexibility is that locking policy strikes to 748 the very heart of the resource management and versioning systems 749 employed by various storage repositories. These repositories 750 require control over what sort of locking will be made available. 751 For example, some repositories only support shared write locks while 752 others only provide support for exclusive write locks while yet 753 others use no locking at all. As each system is sufficiently 754 different to merit exclusion of certain locking features, this 755 specification leaves locking as the sole axis of negotiation within 756 WebDAV. 758 6.3 Lock Tokens 760 A lock token is a type of state token, represented as a URI, which 761 identifies a particular lock. A lock token is returned by every 762 successful LOCK operation in the lockdiscovery property in the 763 response body, and can also be found through lock discovery on a 764 resource. 766 Lock token URIs MUST be unique across all resources for all time. 767 This uniqueness constraint allows lock tokens to be submitted across 768 resources and servers without fear of confusion. 770 This specification provides a lock token URI scheme called 771 opaquelocktoken that meets the uniqueness requirements. However 772 resources are free to return any URI scheme so long as it meets the 773 uniqueness requirements. 775 Having a lock token provides no special access rights. Anyone can 776 find out anyone else's lock token by performing lock discovery. 778 Locks MUST be enforced based upon whatever authentication mechanism 779 is used by the server, not based on the secrecy of the token values. 781 6.4 opaquelocktoken Lock Token URI Scheme 783 The opaquelocktoken URI scheme is designed to be unique across all 784 resources for all time. Due to this uniqueness quality, a client 785 may submit an opaque lock token in an If header on a resource other 786 than the one that returned it. 788 All resources MUST recognize the opaquelocktoken scheme and, at 789 minimum, recognize that the lock token does not refer to an 790 outstanding lock on the resource. 792 In order to guarantee uniqueness across all resources for all time 793 the opaquelocktoken requires the use of the globally unique 794 identifier (GUID) mechanism, as described in [ISO-11578]. 796 Opaquelocktoken generators, however, have a choice of how they 797 create these tokens. They can either generate a new GUID for every 798 lock token they create or they can create a single GUID and then 799 add extension characters. If the second method is selected then the 800 program generating the extensions MUST guarantee that the same 801 extension will never be used twice with the associated GUID. 803 OpaqueLockToken-URI = "opaquelocktoken:" GUID [Extension] ; The 804 GUID production is the string representation of a GUID, as defined 805 in [ISO-11578]. Note that white space (LWS) is not allowed between 806 elements of this production. 808 Extension = path ; path is defined in section 3.2.1 of RFC 2068 809 [Fielding et al., 1996] 811 6.4.1 Node Field Generation Without the IEEE 802 Address 813 GUIDs, as defined in [ISO-11578], contain a "node" field which 814 contains one of the IEEE 802 addresses for the server machine. As 815 noted in section 17.8, there are several security risks associated 816 with exposing a machine's IEEE 802 address. This section provides an 817 alternate mechanism for generating the "node" field of a GUID which 818 does not employ an IEEE 802 address. WebDAV servers MAY use this 819 algorithm for creating the node field when generating GUIDs. The 820 text in this section is quoted from section 4 of draft-leach-uuids- 821 guids-01 (expired). 823 The ideal solution is to obtain a 47 bit cryptographic quality 824 random number, and use it as the low 47 bits of the node ID, with 825 the most significant bit of the first octet of the node ID set to 1. 826 This bit is the unicast/multicast bit, which will never be set in 827 IEEE 802 addresses obtained from network cards; hence, there can 828 never be a conflict between GUIDs generated by machines with and 829 without network cards. 831 If a system does not have a primitive to generate cryptographic 832 quality random numbers, then in most systems there are usually a 833 fairly large number of sources of randomness available from which 834 one can be generated. Such sources are system specific, but often 835 include: 837 - the percent of memory in use 838 - the size of main memory in bytes 839 - the amount of free main memory in bytes 840 - the size of the paging or swap file in bytes 841 - free bytes of paging or swap file 842 - the total size of user virtual address space in bytes 843 - the total available user address space bytes 844 - the size of boot disk drive in bytes 845 - the free disk space on boot drive in bytes 846 - the current time 847 - the amount of time since the system booted 848 - the individual sizes of files in various system directories 849 - the creation, last read, and modification times of files in 850 various system directories 851 - the utilization factors of various system resources (heap, etc.) 852 - current mouse cursor position 853 - current caret position 854 - current number of running processes, threads 855 - handles or IDs of the desktop window and the active window 856 - the value of stack pointer of the caller 857 - the process and thread ID of caller 858 - various processor architecture specific performance counters 859 (instructions executed, cache misses, TLB misses) 861 (Note that it is precisely the above kinds of sources of randomness 862 that are used to seed cryptographic quality random number generators 863 on systems without special hardware for their construction.) 865 In addition, items such as the computer's name and the name of the 866 operating system, while not strictly speaking random, will help 867 differentiate the results from those obtained by other systems. 869 The exact algorithm to generate a node ID using these data is system 870 specific, because both the data available and the functions to 871 obtain them are often very system specific. However, assuming that 872 one can concatenate all the values from the randomness sources into 873 a buffer, and that a cryptographic hash function such as MD5 is 874 available, then any 6 bytes of the MD5 hash of the buffer, with the 875 multicast bit (the high bit of the first byte) set will be an 876 appropriately random node ID. 878 Other hash functions, such as SHA-1, can also be used. The only 879 requirement is that the result be suitably random _ in the sense 880 that the outputs from a set uniformly distributed inputs are 881 themselves uniformly distributed, and that a single bit change in 882 the input can be expected to cause half of the output bits to 883 change. 885 6.5 Lock Capability Discovery 887 Since server lock support is optional, a client trying to lock a 888 resource on a server can either try the lock and hope for the best, 889 or perform some form of discovery to determine what lock 890 capabilities the server supports. This is known as lock capability 891 discovery. Lock capability discovery differs from discovery of 892 supported access control types, since there may be access control 893 types without corresponding lock types. A client can determine what 894 lock types the server supports by retrieving the supportedlock 895 property. 897 Any DAV compliant resource that supports the LOCK method MUST 898 support the supportedlock property. 900 6.6 Active Lock Discovery 902 If another principal locks a resource that a principal wishes to 903 access, it is useful for the second principal to be able to find out 904 who the first principal is. For this purpose the lockdiscovery 905 property is provided. This property lists all outstanding locks, 906 describes their type, and where available, provides their lock 907 token. 909 Any DAV compliant resource that supports the LOCK method MUST 910 support the lockdiscovery property. 912 6.7 Usage Considerations 914 Although the locking mechanisms specified here provide some help in 915 preventing lost updates, they cannot guarantee that updates will 916 never be lost. Consider the following scenario: 918 Two clients A and B are interested in editing the resource 919 'index.html'. Client A is an HTTP client rather than a WebDAV 920 client, and so does not know how to perform locking. 922 Client A doesn't lock the document, but does a GET and begins 923 editing. 924 Client B does LOCK, performs a GET and begins editing. 925 Client B finishes editing, performs a PUT, then an UNLOCK. 926 Client A performs a PUT, overwriting and losing all of B's changes. 928 There are several reasons why the WebDAV protocol itself cannot 929 prevent this situation. First, it cannot force all clients to use 930 locking because it must be compatible with HTTP clients that do not 931 comprehend locking. Second, it cannot require servers to support 932 locking because of the variety of repository implementations, some 933 of which rely on reservations and merging rather than on locking. 935 Finally, being stateless, it cannot enforce a sequence of operations 936 like LOCK / GET / PUT / UNLOCK. 938 WebDAV servers that support locking can reduce the likelihood that 939 clients will accidentally overwrite each other's changes by 940 requiring clients to lock resources before modifying them. Such 941 servers would effectively prevent HTTP 1.0 and HTTP 1.1 clients from 942 modifying resources. 944 WebDAV clients can be good citizens by using a lock / retrieve / 945 write /unlock sequence of operations (at least by default) whenever 946 they interact with a WebDAV server that supports locking. 948 HTTP 1.1 clients can be good citizens, avoiding overwriting other 949 clients' changes, by using entity tags in If-Match headers with any 950 requests that would modify resources. 952 Information managers may attempt to prevent overwrites by 953 implementing client-side procedures requiring locking before 954 modifying WebDAV resources. 956 7 Write Lock 958 This section describes the semantics specific to the write lock 959 type. The write lock is a specific instance of a lock type, and is 960 the only lock type described in this specification. 962 7.1 Methods Restricted by Write Locks 964 A write lock MUST prevent a principal without the lock from 965 successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, 966 DELETE, or MKCOL on the locked resource. All other current methods, 967 GET in particular, function independently of the lock. 969 Note, however, that as new methods are created it will be necessary 970 to specify how they interact with a write lock. 972 7.2 Write Locks and Lock Tokens 974 A successful request for an exclusive or shared write lock MUST 975 result in the generation of a unique lock token associated with the 976 requesting principal. Thus if five principals have a shared write 977 lock on the same resource there will be five lock tokens, one for 978 each principal. 980 7.3 Write Locks and Properties 982 While those without a write lock may not alter a property on a 983 resource it is still possible for the values of live properties to 984 change, even while locked, due to the requirements of their schemas. 986 Only dead properties and live properties defined to respect locks 987 are guaranteed not to change while write locked. 989 7.4 Write Locks and Null Resources 991 It is possible to assert a write lock on a null resource in order to 992 lock the name. 994 A write locked null resource, referred to as a lock-null resource, 995 MUST respond with a 404 (Not Found) or 405 (Method Not Allowed) to 996 any HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, 997 PROPFIND, LOCK, and UNLOCK. A lock-null resource MUST appear as a 998 member of its parent collection. Additionally the lock-null 999 resource MUST have defined on it all mandatory DAV properties. Most 1000 of these properties, such as all the get* properties, will have no 1001 value as a lock-null resource does not support the GET method. 1002 Lock-Null resources MUST have defined values for lockdiscovery and 1003 supportedlock properties. 1005 Until a method such as PUT or MKCOL is successfully executed on the 1006 lock-null resource the resource MUST stay in the lock-null state. 1007 However, once a PUT or MKCOL is successfully executed on a lock-null 1008 resource the resource ceases to be in the lock-null state. 1010 If the resource is unlocked, for any reason, without a PUT, MKCOL, 1011 or similar method having been successfully executed upon it then the 1012 resource MUST return to the null state. 1014 7.5 Write Locks and Collections 1016 A write lock on a collection, whether created by a "Depth: 0" or 1017 "Depth: infinity" lock request, prevents the addition or removal of 1018 members of the collection by non-lock owners. As a consequence, 1019 when a principal issues a request to create a new internal member of 1020 a write locked collection using PUT or POST, or to remove an 1021 existing internal member of a write locked collection using DELETE, 1022 this request MUST fail if the principal does not have a write lock 1023 on the collection. 1025 However, if a write lock request is issued to a collection 1026 containing internal member resources that are currently locked in a 1027 manner which conflicts with the write lock, the request MUST fail 1028 with a 423 (Locked) status code. 1030 If a lock owner causes a resource to be added as an internal member 1031 of a locked collection then the new resource MUST be automatically 1032 added to the lock. This is the only mechanism that allows a 1033 resource to be added to a write lock. Thus, for example, if the 1034 collection /a/b/ is write locked and the resource /c is moved to 1035 /a/b/c then /a/b/c will be added to the write lock. 1037 7.6 Write Locks and the If Request Header 1039 If a user agent is not required to have knowledge about a lock when 1040 requesting an operation on a locked resource, the following scenario 1041 might occur. Program A, run by User A, takes out a write lock on a 1042 resource. Program B, also run by User A, has no knowledge of the 1043 lock taken out by Program A, yet performs a PUT to the locked 1044 resource. In this scenario, the PUT succeeds because locks are 1045 associated with a principal, not a program, and thus program B, 1046 because it is acting with principal A's credential, is allowed to 1047 perform the PUT. However, had program B known about the lock, it 1048 would not have overwritten the resource, preferring instead to 1049 present a dialog box describing the conflict to the user. Due to 1050 this scenario, a mechanism is needed to prevent different programs 1051 from accidentally ignoring locks taken out by other programs with 1052 the same authorization. 1054 In order to prevent these collisions a lock token MUST be submitted 1055 by an authorized principal in the If header for all locked resources 1056 that a method may interact with or the method MUST fail. For 1057 example, if a resource is to be moved and both the source and 1058 destination are locked then two lock tokens must be submitted, one 1059 for the source and the other for the destination. 1061 7.6.1 Example - Write Lock 1063 >>Request 1065 COPY /~fielding/index.html HTTP/1.1 1066 Host: www.ics.uci.edu 1067 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1068 If: 1069 () 1071 >>Response 1073 HTTP/1.1 204 No Content 1075 In this example, even though both the source and destination are 1076 locked, only one lock token must be submitted, for the lock on the 1077 destination. This is because the source resource is not modified by 1078 a COPY, and hence unaffected by the write lock. In this example, 1079 user agent authentication has previously occurred via a mechanism 1080 outside the scope of the HTTP protocol, in the underlying transport 1081 layer. 1083 7.7 Write Locks and COPY/MOVE 1085 A COPY method invocation MUST NOT duplicate any write locks active 1086 on the source. However, as previously noted, if the COPY copies the 1087 resource into a collection that is locked with "Depth: infinity", 1088 then the resource will be added to the lock. 1090 A successful MOVE request on a write locked resource MUST NOT move 1091 the write lock with the resource. However, the resource is subject 1092 to being added to an existing lock at the destination, as specified 1093 in section 7.5. For example, if the MOVE makes the resource a child 1094 of a collection that is locked with "Depth: infinity", then the 1095 resource will be added to that collection's lock. Additionally, if a 1096 resource locked with "Depth: infinity" is moved to a destination 1097 that is within the scope of the same lock (e.g., within the 1098 namespace tree covered by the lock), the moved resource will again 1099 be a added to the lock. In both these examples, as specified in 1100 section 7.6, an If header must be submitted containing a lock token 1101 for both the source and destination. 1103 7.8 Refreshing Write Locks 1105 A client MUST NOT submit the same write lock request twice. Note 1106 that a client is always aware it is resubmitting the same lock 1107 request because it must include the lock token in the If header in 1108 order to make the request for a resource that is already locked. 1110 However, a client may submit a LOCK method with an If header but 1111 without a body. This form of LOCK MUST only be used to "refresh" a 1112 lock. Meaning, at minimum, that any timers associated with the lock 1113 MUST be re-set. 1115 A server may return a Timeout header with a lock refresh that is 1116 different than the Timeout header returned when the lock was 1117 originally requested. Additionally clients may submit Timeout 1118 headers of arbitrary value with their lock refresh requests. 1119 Servers, as always, may ignore Timeout headers submitted by the 1120 client. 1122 If an error is received in response to a refresh LOCK request the 1123 client SHOULD assume that the lock was not refreshed. 1125 8 HTTP Methods for Distributed Authoring 1127 The following new HTTP methods use XML as a request and response 1128 format. All DAV compliant clients and resources MUST use XML 1129 parsers that are compliant with [REC-XML]. All XML used in either 1130 requests or responses MUST be, at minimum, well formed. If a server 1131 receives ill-formed XML in a request it MUST reject the entire 1132 request with a 400 (Bad Request). If a client receives ill-formed 1133 XML in a response then it MUST NOT assume anything about the outcome 1134 of the executed method and SHOULD treat the server as 1135 malfunctioning. 1137 8.1 PROPFIND 1139 The PROPFIND method retrieves properties defined on the Request-URI, 1140 if the resource does not have any internal members, or on the 1141 Request-URI and potentially its member resources, if the resource 1142 does have internal members. All DAV compliant resources MUST 1143 support the PROPFIND method and the propfind XML element (section 1144 12.14) along with all XML elements defined for use with that 1145 element. 1147 A client may submit a Depth header with a value of "0", "1", or 1148 "infinity" with a PROPFIND on a resource with internal members. DAV 1149 compliant servers MUST support the "0", "1" and "infinity" 1150 behaviors. By default, the PROPFIND method without a Depth header 1151 MUST act as if a "Depth: infinity" header was included. 1153 A client may submit a propfind XML element in the body of the 1154 request method describing what information is being requested. It 1155 is possible to request particular property values, all property 1156 values, or a list of the names of the resource's properties. A 1157 client may choose not to submit a request body. An empty PROPFIND 1158 request body MUST be treated as a request for the names and values 1159 of all properties. 1161 All servers MUST support returning a response of content type 1162 text/xml or application/xml that contains a multistatus XML element 1163 that describes the results of the attempts to retrieve the various 1164 properties. 1166 If there is an error retrieving a property then a proper error 1167 result MUST be included in the response. A request to retrieve the 1168 value of a property which does not exist is an error and MUST be 1169 noted, if the response uses a multistatus XML element, with a 1170 response XML element which contains a 404 (Not Found) status value. 1172 Consequently, the multistatus XML element for a resource with 1173 members MUST include a response XML element for each member of the 1174 resource, to whatever depth was requested. Each response XML element 1175 MUST contain an href XML element that identifies the resource on 1176 which the properties in the prop XML element are defined. Results 1177 for a PROPFIND on a resource with internal members are returned as a 1178 flat list whose order of entries is not significant. 1180 In the case of allprop and propname, if a principal does not have 1181 the right to know whether a particular property exists then the 1182 property should be silently excluded from the response. 1184 The results of this method SHOULD NOT be cached. 1186 8.1.1 Example - Retrieving Named Properties 1188 >>Request 1190 PROPFIND /file HTTP/1.1 1191 Host: www.foo.bar 1192 Content-type: text/xml; charset="utf-8" 1193 Content-Length: xyz 1195 1196 1197 1198 1199 1200 1201 1202 1203 1205 >>Response 1207 HTTP/1.1 207 Multi-Status 1208 Content-Type: text/xml; charset="utf-8" 1209 Content-Length: xxxxx 1211 1212 1213 1214 http://www.foo.bar/file 1215 1216 1217 1218 Box type A 1219 1220 1221 J.J. Johnson 1222 1223 1224 HTTP/1.1 200 OK 1225 1226 1227 1228 HTTP/1.1 403 Forbidden 1229 The user does not have access to 1230 the DingALing property. 1231 1232 1233 1234 There has been an access violation error. 1235 1236 1237 In this example, PROPFIND is executed on a non-collection resource 1238 http://www.foo.bar/file. The propfind XML element specifies the 1239 name of four properties whose values are being requested. In this 1240 case only two properties were returned, since the principal issuing 1241 the request did not have sufficient access rights to see the third 1242 and fourth properties. 1244 8.1.2 Example - Using allprop to Retrieve All Properties 1246 >>Request 1248 PROPFIND /container/ HTTP/1.1 1249 Host: www.foo.bar 1250 Depth: 1 1251 Content-Type: text/xml; charset="utf-8" 1252 Content-Length: xxxxx 1254 1255 1256 1257 1259 >>Response 1261 HTTP/1.1 207 Multi-Status 1262 Content-Type: text/xml; charset="utf-8" 1263 Content-Length: xxxxx 1265 1266 1267 1268 http://www.foo.bar/container/ 1269 1270 1271 1272 Box type A 1273 1274 1275 Hadrian 1276 1277 1278 1997-12-01T17:42:21-08:00 1279 1280 1281 Example collection 1282 1283 1284 1285 1286 1287 1289 1290 1291 1292 1293 1294 1295 1296 HTTP/1.1 200 OK 1297 1298 1299 1300 http://www.foo.bar/container/front.html 1301 1302 1303 1304 Box type B 1305 1306 1307 1997-12-01T18:27:21-08:00 1308 1309 1310 Example HTML resource 1311 1312 1313 4525 1314 1315 1316 text/html 1317 1318 1319 zzyzx 1320 1321 1322 Monday, 12-Jan-98 09:25:56 GMT 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 HTTP/1.1 200 OK 1337 1338 1339 1340 In this example, PROPFIND was invoked on the resource 1341 http://www.foo.bar/container/ with a Depth header of 1, meaning the 1342 request applies to the resource and its children, and a propfind XML 1343 element containing the allprop XML element, meaning the request 1344 should return the name and value of all properties defined on each 1345 resource. 1347 The resource http://www.foo.bar/container/ has six properties 1348 defined on it: 1350 http://www.foo.bar/boxschema/bigbox, 1351 http://www.foo.bar/boxschema/author, DAV:creationdate, 1352 DAV:displayname, DAV:resourcetype, and DAV:supportedlock. 1354 The last four properties are WebDAV-specific, defined in section 13. 1355 Since GET is not supported on this resource, the get* properties 1356 (e.g., getcontentlength) are not defined on this resource. The DAV- 1357 specific properties assert that "container" was created on December 1358 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT 1359 (creationdate), has a name of "Example collection" (displayname), a 1360 collection resource type (resourcetype), and supports exclusive 1361 write and shared write locks (supportedlock). 1363 The resource http://www.foo.bar/container/front.html has nine 1364 properties defined on it: 1366 http://www.foo.bar/boxschema/bigbox (another instance of the 1367 "bigbox" property type), DAV:creationdate, DAV:displayname, 1368 DAV:getcontentlength, DAV:getcontenttype, DAV:getetag, 1369 DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. 1371 The DAV-specific properties assert that "front.html" was created on 1372 December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT 1373 (creationdate), has a name of "Example HTML resource" (displayname), 1374 a content length of 4525 bytes (getcontentlength), a MIME type of 1375 "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), 1376 was last modified on Monday, January 12, 1998, at 09:25:56 GMT 1377 (getlastmodified), has an empty resource type, meaning that it is 1378 not a collection (resourcetype), and supports both exclusive write 1379 and shared write locks (supportedlock). 1381 8.1.3 Example - Using propname to Retrieve all Property Names 1383 >>Request 1385 PROPFIND /container/ HTTP/1.1 1386 Host: www.foo.bar 1387 Content-Type: text/xml; charset="utf-8" 1388 Content-Length: xxxxx 1390 1391 1392 1393 1395 >>Response 1397 HTTP/1.1 207 Multi-Status 1398 Content-Type: text/xml; charset="utf-8" 1399 Content-Length: xxxx 1401 1402 1403 1404 http://www.foo.bar/container/ 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 HTTP/1.1 200 OK 1415 1416 1417 1418 http://www.foo.bar/container/front.html 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 HTTP/1.1 200 OK 1432 1433 1434 1435 In this example, PROPFIND is invoked on the collection resource 1436 http://www.foo.bar/container/, with a propfind XML element 1437 containing the propname XML element, meaning the name of all 1438 properties should be returned. Since no Depth header is present, it 1439 assumes its default value of "infinity", meaning the name of the 1440 properties on the collection and all its progeny should be returned. 1442 Consistent with the previous example, resource 1443 http://www.foo.bar/container/ has six properties defined on it, 1444 http://www.foo.bar/boxschema/bigbox, 1445 http://www.foo.bar/boxschema/author, DAV:creationdate, 1446 DAV:displayname, DAV:resourcetype, and DAV:supportedlock. 1448 The resource http://www.foo.bar/container/index.html, a member of 1449 the "container" collection, has nine properties defined on it, 1450 http://www.foo.bar/boxschema/bigbox, DAV:creationdate, 1451 DAV:displayname, DAV:getcontentlength, DAV:getcontenttype, 1452 DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and 1453 DAV:supportedlock. 1455 This example also demonstrates the use of XML namespace scoping, and 1456 the default namespace. Since the "xmlns" attibute does not contain 1457 an explicit "shorthand name" (prefix) letter, the namespace applies 1458 by default to all enclosed elements. Hence, all elements which do 1459 not explicitly state the namespace to which they belong are members 1460 of the "DAV:" namespace schema. 1462 8.2 PROPPATCH 1464 The PROPPATCH method processes instructions specified in the request 1465 body to set and/or remove properties defined on the resource 1466 identified by the Request-URI. 1468 All DAV compliant resources MUST support the PROPPATCH method and 1469 MUST process instructions that are specified using the 1470 propertyupdate, set, and remove XML elements of the DAV schema. 1471 Execution of the directives in this method is, of course, subject to 1472 access control constraints. DAV compliant resources SHOULD support 1473 the setting of arbitrary dead properties. 1475 The request message body of a PROPPATCH method MUST contain the 1476 propertyupdate XML element. Instruction processing MUST occur in 1477 the order instructions are received (i.e., from top to bottom). 1478 Instructions MUST either all be executed or none executed. Thus if 1479 any error occurs during processing all executed instructions MUST be 1480 undone and a proper error result returned. Instruction processing 1481 details can be found in the definition of the set and remove 1482 instructions in section 12.13. 1484 8.2.1 Status Codes for use with 207 (Multi-Status) 1486 The following are examples of response codes one would expect to be 1487 used in a 207 (Multi-Status) response for this method. Note, 1488 however, that unless explicitly prohibited any 2/3/4/5xx series 1489 response code may be used in a 207 (Multi-Status) response. 1491 200 (OK) - The command succeeded. As there can be a mixture of sets 1492 and removes in a body, a 201 (Created) seems inappropriate. 1494 403 (Forbidden) - The client, for reasons the server chooses not to 1495 specify, cannot alter one of the properties. 1497 409 (Conflict) - The client has provided a value whose semantics are 1498 not appropriate for the property. This includes trying to set read- 1499 only properties. 1501 423 (Locked) - The specified resource is locked and the client 1502 either is not a lock owner or the lock type requires a lock token to 1503 be submitted and the client did not submit it. 1505 507 (Insufficient Storage) - The server did not have sufficient 1506 space to record the property. 1508 8.2.2 Example - PROPPATCH 1510 >>Request 1512 PROPPATCH /bar.html HTTP/1.1 1513 Host: www.foo.com 1514 Content-Type: text/xml; charset="utf-8" 1515 Content-Length: xxxx 1517 1518 1520 1521 1522 1523 Jim Whitehead 1524 Roy Fielding 1525 1526 1527 1528 1529 1530 1531 1533 >>Response 1534 HTTP/1.1 207 Multi-Status 1535 Content-Type: text/xml; charset="utf-8" 1536 Content-Length: xxxxx 1538 1539 1541 1542 http://www.foo.com/bar.html 1543 1544 1545 HTTP/1.1 424 Failed Dependency 1546 1547 1548 1549 HTTP/1.1 409 Conflict 1550 1551 Copyright Owner can not be deleted or 1552 altered. 1553 1554 1556 In this example, the client requests the server to set the value of 1557 the http://www.w3.com/standards/z39.50/Authors property, and to 1558 remove the property http://www.w3.com/standards/z39.50/Copyright- 1559 Owner. Since the Copyright-Owner property could not be removed, no 1560 property modifications occur. The 424 (Failed Dependency) status 1561 code for the Authors property indicates this action would have 1562 succeeded if it were not for the conflict with removing the 1563 Copyright-Owner property. 1565 8.3 MKCOL Method 1567 The MKCOL method is used to create a new collection. All DAV 1568 compliant resources MUST support the MKCOL method. 1570 8.3.1 Request 1572 MKCOL creates a new collection resource at the location specified by 1573 the Request-URI. If the resource identified by the Request-URI is 1574 non-null then the MKCOL MUST fail. During MKCOL processing, a 1575 server MUST make the Request-URI a member of its parent collection, 1576 unless the Request-URI is "/". If no such ancestor exists, the 1577 method MUST fail. When the MKCOL operation creates a new collection 1578 resource, all ancestors MUST already exist, or the method MUST fail 1579 with a 409 (Conflict) status code. For example, if a request to 1580 create collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ 1581 exists, the request must fail. 1583 When MKCOL is invoked without a request body, the newly created 1584 collection SHOULD have no members. 1586 A MKCOL request message may contain a message body. The behavior of 1587 a MKCOL request when the body is present is limited to creating 1588 collections, members of a collection, bodies of members and 1589 properties on the collections or members. If the server receives a 1590 MKCOL request entity type it does not support or understand it MUST 1591 respond with a 415 (Unsupported Media Type) status code. The exact 1592 behavior of MKCOL for various request media types is undefined in 1593 this document, and will be specified in separate documents. 1595 8.3.2 Status Codes 1597 Responses from a MKCOL request MUST NOT be cached as MKCOL has non- 1598 idempotent semantics. 1600 201 (Created) - The collection or structured resource was created in 1601 its entirety. 1603 403 (Forbidden) - This indicates at least one of two conditions: 1) 1604 the server does not allow the creation of collections at the given 1605 location in its namespace, or 2) the parent collection of the 1606 Request-URI exists but cannot accept members. 1608 405 (Method Not Allowed) - MKCOL can only be executed on a 1609 deleted/non-existent resource. 1611 409 (Conflict) - A collection cannot be made at the Request-URI 1612 until one or more intermediate collections have been created. 1614 415 (Unsupported Media Type)- The server does not support the 1615 request type of the body. 1617 507 (Insufficient Storage) - The resource does not have sufficient 1618 space to record the state of the resource after the execution of 1619 this method. 1621 8.3.3 Example - MKCOL 1623 This example creates a collection called /webdisc/xfiles/ on the 1624 server www.server.org. 1626 >>Request 1628 MKCOL /webdisc/xfiles/ HTTP/1.1 1629 Host: www.server.org 1631 >>Response 1633 HTTP/1.1 201 Created 1635 8.4 GET, HEAD for Collections 1637 The semantics of GET are unchanged when applied to a collection, 1638 since GET is defined as, "retrieve whatever information (in the form 1639 of an entity) is identified by the Request-URI" [RFC2068]. GET when 1640 applied to a collection may return the contents of an "index.html" 1641 resource, a human-readable view of the contents of the collection, 1642 or something else altogether. Hence it is possible that the result 1643 of a GET on a collection will bear no correlation to the membership 1644 of the collection. 1646 Similarly, since the definition of HEAD is a GET without a response 1647 message body, the semantics of HEAD are unmodified when applied to 1648 collection resources. 1650 8.5 POST for Collections 1652 Since by definition the actual function performed by POST is 1653 determined by the server and often depends on the particular 1654 resource, the behavior of POST when applied to collections cannot be 1655 meaningfully modified because it is largely undefined. Thus the 1656 semantics of POST are unmodified when applied to a collection. 1658 8.6 DELETE 1660 8.6.1 DELETE for Non-Collection Resources 1662 If the DELETE method is issued to a non-collection resource which is 1663 an internal member of a collection, then during DELETE processing a 1664 server MUST remove the Request-URI from its parent collection. 1666 8.6.2 DELETE for Collections 1668 The DELETE method on a collection MUST act as if a "Depth: infinity" 1669 header was used on it. A client MUST NOT submit a Depth header with 1670 a DELETE on a collection with any value but infinity. 1672 DELETE instructs that the collection specified in the Request-URI 1673 and all its internal member resources are to be deleted. 1675 If any member cannot be deleted then all of the member's ancestors 1676 MUST NOT be deleted, so as to maintain the namespace. 1678 Any headers included with DELETE MUST be applied in processing every 1679 resource to be deleted. 1681 When the DELETE method has completed processing it MUST return a 1682 consistent namespace. 1684 If an error occurs with a resource other than the resource 1685 identified in the Request-URI then the response MUST be a 207 1686 (Multi-Status). 424 (Failed Dependency) errors SHOULD NOT be in the 1687 207 (Multi-Status). They can be safely left out because the client 1688 will know that the ancestors of a resource could not be deleted when 1689 the client receives an error for the ancestor's progeny. 1690 Additionally 204 (No Content) errors SHOULD NOT be returned in the 1691 207 (Multi-Status). The reason for this prohibition is that 204 (No 1692 Content) is the default success code. 1694 8.6.2.1 Example - DELETE 1696 >>Request 1698 DELETE /container/ HTTP/1.1 1699 Host: www.foo.bar 1701 >>Response 1703 HTTP/1.1 207 Multi-Status 1704 Content-Type: text/xml; charset="utf-8" 1705 Content-Length: xxxxx 1707 1708 1709 1710 http://www.foo.bar/container/resource3 1711 HTTP/1.1 423 Locked 1712 1713 1715 In this example the attempt to delete 1716 http://www.foo.bar/container/resource3 failed because it is locked, 1717 and no lock token was submitted with the request. Consequently, the 1718 attempt to delete http://www.foo.bar/container/ also failed. Thus 1719 the client knows that the attempt to delete 1720 http://www.foo.bar/container/ must have also failed since the parent 1721 can not be deleted unless its child has also been deleted. Even 1722 though a Depth header has not been included, a depth of infinity is 1723 assumed because the method is on a collection. 1725 8.7 PUT 1727 8.7.1 PUT for Non-Collection Resources 1729 A PUT performed on an existing resource replaces the GET response 1730 entity of the resource. Properties defined on the resource may be 1731 recomputed during PUT processing but are not otherwise affected. 1732 For example, if a server recognizes the content type of the request 1733 body, it may be able to automatically extract information that could 1734 be profitably exposed as properties. 1736 A PUT that would result in the creation of a resource without an 1737 appropriately scoped parent collection MUST fail with a 409 1738 (Conflict). 1740 8.7.2 PUT for Collections 1742 As defined in the HTTP/1.1 specification [RFC2068], the "PUT method 1743 requests that the enclosed entity be stored under the supplied 1744 Request-URI." Since submission of an entity representing a 1745 collection would implicitly encode creation and deletion of 1746 resources, this specification intentionally does not define a 1747 transmission format for creating a collection using PUT. Instead, 1748 the MKCOL method is defined to create collections. 1750 When the PUT operation creates a new non-collection resource all 1751 ancestors MUST already exist. If all ancestors do not exist, the 1752 method MUST fail with a 409 (Conflict) status code. For example, if 1753 resource /a/b/c/d.html is to be created and /a/b/c/ does not exist, 1754 then the request must fail. 1756 8.8 COPY Method 1758 The COPY method creates a duplicate of the source resource, given by 1759 the Request-URI, in the destination resource, given by the 1760 Destination header. The Destination header MUST be present. The 1761 exact behavior of the COPY method depends on the type of the source 1762 resource. 1764 All WebDAV compliant resources MUST support the COPY method. 1765 However, support for the COPY method does not guarantee the ability 1766 to copy a resource. For example, separate programs may control 1767 resources on the same server. As a result, it may not be possible 1768 to copy a resource to a location that appears to be on the same 1769 server. 1771 8.8.1 COPY for HTTP/1.1 resources 1773 When the source resource is not a collection the result of the COPY 1774 method is the creation of a new resource at the destination whose 1775 state and behavior match that of the source resource as closely as 1776 possible. After a successful COPY invocation, all properties on the 1777 source resource MUST be duplicated on the destination resource, 1778 subject to modifying headers and XML elements, following the 1779 definition for copying properties. Since the environment at the 1780 destination may be different than at the source due to factors 1781 outside the scope of control of the server, such as the absence of 1782 resources required for correct operation, it may not be possible to 1783 completely duplicate the behavior of the resource at the 1784 destination. Subsequent alterations to the destination resource will 1785 not modify the source resource. Subsequent alterations to the 1786 source resource will not modify the destination resource. 1788 8.8.2 COPY for Properties 1790 The following section defines how properties on a resource are 1791 handled during a COPY operation. 1793 Live properties SHOULD be duplicated as identically behaving live 1794 properties at the destination resource. If a property cannot be 1795 copied live, then its value MUST be duplicated, octet-for-octet, in 1796 an identically named, dead property on the destination resource 1797 subject to the effects of the propertybehavior XML element. 1799 The propertybehavior XML element can specify that properties are 1800 copied on best effort, that all live properties must be successfully 1801 copied or the method must fail, or that a specified list of live 1802 properties must be successfully copied or the method must fail. The 1803 propertybehavior XML element is defined in section 12.12. 1805 8.8.3 COPY for Collections 1807 The COPY method on a collection without a Depth header MUST act as 1808 if a Depth header with value "infinity" was included. A client may 1809 submit a Depth header on a COPY on a collection with a value of "0" 1810 or "infinity". DAV compliant servers MUST support the "0" and 1811 "infinity" Depth header behaviors. 1813 A COPY of depth infinity instructs that the collection specified in 1814 the Request-URI is to be copied to the location specified in the 1815 Destination header, and all its internal member resources are to be 1816 copied to a location relative to it, recursively through all levels 1817 of the collection hierarchy. 1819 A COPY of "Depth: 0" only instructs that the collection and its 1820 properties but not its internal members, are to be copied. 1822 Any headers included with a COPY MUST be applied in processing every 1823 resource to be copied with the exception of the Destination header. 1825 The Destination header only specifies the destination for the 1826 Request-URI. When applied to members of the collection specified in 1827 the Request-URI the value of Destination is to be modified to 1828 reflect the current location in the hierarchy. So, if the Request- 1829 URI is /a/ and the destination is /b/ then when /a/c/d is processed 1830 it must use a destination of /b/c/d. 1832 When the COPY method has completed processing it MUST have created a 1833 consistent namespace at the destination (see section 5.1 for the 1834 definition of namespace consistency). However, if an error occurs 1835 while copying an internal member collection, the server MUST NOT 1836 copy any members of this collection (i.e., the server must skip this 1837 subtree), as this would create an inconsistent namespace. After 1838 detecting an error, the COPY operation SHOULD try to finish as much 1839 of the original copy operation as possible (i.e., the server should 1840 still attempt to copy other subtrees and their members, that are not 1841 descendents of an error-causing collection). So, for example, if an 1842 infinite depth copy operation is performed on collection /a/, which 1843 contains collections /a/b/ and /a/c/, and an error occurs copying 1844 /a/b/, an attempt should still be made to copy /a/c/. Similarly, 1845 after encountering an error copying a non-collection resource as 1846 part of an infinite depth copy, the server SHOULD try to finish as 1847 much of the original copy operation as possible. 1849 If an error in executing the COPY method occurs with a resource 1850 other than the resource identified in the Request-URI then the 1851 response MUST be a 207 (Multi-Status). 1853 The 424 (Failed Dependency) status code SHOULD NOT be returned in 1854 the 207 (Multi-Status) response from a COPY method. These responses 1855 can be safely omitted because the client will know that the progeny 1856 of a resource could not be copied when the client receives an error 1857 for the parent. Additionally 201 (Created)/204 (No Content) status 1858 codes SHOULD NOT be returned as values in 207 (Multi-Status) 1859 responses from COPY methods. They, too, can be safely omitted 1860 because they are the default success codes. 1862 8.8.4 COPY and the Overwrite Header 1864 If a resource exists at the destination and the Overwrite header is 1865 "T" then prior to performing the copy the server MUST perform a 1866 DELETE with "Depth: infinity" on the destination resource. If the 1867 Overwrite header is set to "F" then the operation will fail. 1869 8.8.5 Status Codes 1871 201 (Created) - The source resource was successfully copied. The 1872 copy operation resulted in the creation of a new resource. 1874 204 (No Content) - The source resource was successfully copied to a 1875 pre-existing destination resource. 1877 403 (Forbidden) _ The source and destination URIs are the same. 1879 409 (Conflict) _ A resource cannot be created at the destination 1880 until one or more intermediate collections have been created. 1882 412 (Precondition Failed) - The server was unable to maintain the 1883 liveness of the properties listed in the propertybehavior XML 1884 element or the Overwrite header is "F" and the state of the 1885 destination resource is non-null. 1887 423 (Locked) - The destination resource was locked. 1889 507 (Insufficient Storage) - The destination resource does not have 1890 sufficient space to record the state of the resource after the 1891 execution of this method. 1893 502 (Bad Gateway) - This may occur when the destination is on 1894 another server and the destination server refuses to accept the 1895 resource. 1897 8.8.6 Example - COPY with Overwrite 1899 This example shows resource 1900 http://www.ics.uci.edu/~fielding/index.html being copied to the 1901 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1902 204 (No Content) status code indicates the existing resource at the 1903 destination was overwritten. 1905 >>Request 1907 COPY /~fielding/index.html HTTP/1.1 1908 Host: www.ics.uci.edu 1909 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1911 >>Response 1913 HTTP/1.1 204 No Content 1915 8.8.7 Example - COPY with No Overwrite 1917 The following example shows the same copy operation being performed, 1918 but with the Overwrite header set to "F." A response of 412 1919 (Precondition Failed) is returned because the destination resource 1920 has a non-null state. 1922 >>Request 1924 COPY /~fielding/index.html HTTP/1.1 1925 Host: www.ics.uci.edu 1926 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1927 Overwrite: F 1929 >>Response 1931 HTTP/1.1 412 Precondition Failed 1933 8.8.8 Example - COPY of a Collection 1935 >>Request 1937 COPY /container/ HTTP/1.1 1938 Host: www.foo.bar 1939 Destination: http://www.foo.bar/othercontainer/ 1940 Depth: infinity 1941 Content-Type: text/xml; charset="utf-8" 1942 Content-Length: xxxxx 1944 1945 1946 * 1947 1948 >>Response 1950 HTTP/1.1 207 Multi-Status 1951 Content-Type: text/xml; charset="utf-8" 1952 Content-Length: xxxxx 1954 1955 1956 1957 http://www.foo.bar/othercontainer/R2/ 1958 HTTP/1.1 412 Precondition Failed 1959 1960 1962 The Depth header is unnecessary as the default behavior of COPY on a 1963 collection is to act as if a "Depth: infinity" header had been 1964 submitted. In this example most of the resources, along with the 1965 collection, were copied successfully. However the collection R2 1966 failed, most likely due to a problem with maintaining the liveness 1967 of properties (this is specified by the propertybehavior XML 1968 element). Because there was an error copying R2, none of R2's 1969 members were copied. However no errors were listed for those 1970 members due to the error minimization rules given in section 8.8.3. 1972 8.9 MOVE Method 1974 The MOVE operation on a non-collection resource is the logical 1975 equivalent of a copy (COPY) followed by a delete of the source, 1976 where the actions are performed atomically. Consequently, the 1977 Destination header MUST be present on all MOVE methods and MUST 1978 follow all COPY requirements for the COPY part of the MOVE method. 1979 All DAV compliant resources MUST support the MOVE method. However, 1980 support for the MOVE method does not guarantee the ability to move a 1981 resource to a particular destination. 1983 For example, separate programs may actually control different sets 1984 of resources on the same server. Therefore, it may not be possible 1985 to move a resource within a namespace that appears to belong to the 1986 same server. 1988 If a resource exists at the destination, the destination resource 1989 will be DELETEd as a side-effect of the MOVE operation, subject to 1990 the restrictions of the Overwrite header. 1992 8.9.1 MOVE for Properties 1994 The behavior of properties on a MOVE, including the effects of the 1995 propertybehavior XML element, MUST be the same as specified in 1996 section 8.8.2. 1998 8.9.2 MOVE for Collections 2000 A MOVE with "Depth: infinity" instructs that the collection 2001 specified in the Request-URI be moved to the location specified in 2002 the Destination header, and all its internal member resources are to 2003 be moved to locations relative to it, recursively through all levels 2004 of the collection hierarchy. 2006 The MOVE method on a collection MUST act as if a "Depth: infinity" 2007 header was used on it. A client MUST NOT submit a Depth header on a 2008 MOVE on a collection with any value but "infinity". 2010 Any headers included with MOVE MUST be applied in processing every 2011 resource to be moved with the exception of the Destination header. 2013 The behavior of the Destination header is the same as given for COPY 2014 on collections. 2016 When the MOVE method has completed processing it MUST have created a 2017 consistent namespace on both the source and destination (see section 2018 5.1 for the definition of namespace consistency). However, if an 2019 error occurs while moving an internal member collection, the server 2020 MUST NOT move any members of the failed collection (i.e., the server 2021 must skip the error-causing subtree), as this would create an 2022 inconsistent namespace. In this case, after detecting the error, the 2023 move operation SHOULD try to finish as much of the original move as 2024 possible (i.e., the server should still attempt to move other 2025 subtrees and their members, that are not descendents of an error- 2026 causing collection). So, for example, if an infinite depth move is 2027 performed on collection /a/, which contains collections /a/b/ and 2028 /a/c/, and an error occurs moving /a/b/, an attempt should still be 2029 made to try moving /a/c/. Similarly, after encountering an error 2030 moving a non-collection resource as part of an infinite depth move, 2031 the server SHOULD try to finish as much of the original move 2032 operation as possible. 2034 If an error occurs with a resource other than the resource 2035 identified in the Request-URI then the response MUST be a 207 2036 (Multi-Status). 2038 The 424 (Failed Dependency) status code SHOULD NOT be returned in 2039 the 207 (Multi-Status) response from a MOVE method. These errors 2040 can be safely omitted because the client will know that the progeny 2041 of a resource could not be moved when the client receives an error 2042 for the parent. Additionally 201 (Created)/204 (No Content) 2043 responses SHOULD NOT be returned as values in 207 (Multi-Status) 2044 responses from a MOVE. These responses can be safely omitted 2045 because they are the default success codes. 2047 8.9.3 MOVE and the Overwrite Header 2049 If a resource exists at the destination and the Overwrite header is 2050 "T" then prior to performing the move the server MUST perform a 2051 DELETE with "Depth: infinity" on the destination resource. If the 2052 Overwrite header is set to "F" then the operation will fail. 2054 8.9.4 Status Codes 2056 201 (Created) - The source resource was successfully moved, and a 2057 new resource was created at the destination. 2059 204 (No Content) - The source resource was successfully moved to a 2060 pre-existing destination resource. 2062 403 (Forbidden) _ The source and destination URIs are the same. 2064 409 (Conflict) _ A resource cannot be created at the destination 2065 until one or more intermediate collections have been created. 2067 412 (Precondition Failed) - The server was unable to maintain the 2068 liveness of the properties listed in the propertybehavior XML 2069 element or the Overwrite header is "F" and the state of the 2070 destination resource is non-null. 2072 423 (Locked) - The source or the destination resource was locked. 2074 502 (Bad Gateway) - This may occur when the destination is on 2075 another server and the destination server refuses to accept the 2076 resource. 2078 8.9.5 Example - MOVE of a Non-Collection 2080 This example shows resource 2081 http://www.ics.uci.edu/~fielding/index.html being moved to the 2082 location http://www.ics.uci.edu/users/f/fielding/index.html. The 2083 contents of the destination resource would have been overwritten if 2084 the destination resource had been non-null. In this case, since 2085 there was nothing at the destination resource, the response code is 2086 201 (Created). 2088 >>Request 2090 MOVE /~fielding/index.html HTTP/1.1 2091 Host: www.ics.uci.edu 2092 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 2094 >>Response 2096 HTTP/1.1 201 Created 2097 Location: http://www.ics.uci.edu/users/f/fielding/index.html 2099 8.9.6 Example - MOVE of a Collection 2101 >>Request 2103 MOVE /container/ HTTP/1.1 2104 Host: www.foo.bar 2105 Destination: http://www.foo.bar/othercontainer/ 2106 Overwrite: F 2107 If: () 2108 () 2109 Content-Type: text/xml; charset="utf-8" 2110 Content-Length: xyz 2112 2113 2114 * 2115 2117 >>Response 2119 HTTP/1.1 207 Multi-Status 2120 Content-Type: text/xml; charset="utf-8" 2121 Content-Length: zzz 2123 2124 2125 2126 http://www.foo.bar/othercontainer/C2/ 2127 HTTP/1.1 423 Locked 2128 2129 2131 In this example the client has submitted a number of lock tokens 2132 with the request. A lock token will need to be submitted for every 2133 resource, both source and destination, anywhere in the scope of the 2134 method, that is locked. In this case the proper lock token was not 2135 submitted for the destination http://www.foo.bar/othercontainer/C2/. 2136 This means that the resource /container/C2/ could not be moved. 2137 Because there was an error copying /container/C2/, none of 2138 /container/C2's members were copied. However no errors were listed 2139 for those members due to the error minimization rules given in 2140 section 8.8.3. User agent authentication has previously occurred 2141 via a mechanism outside the scope of the HTTP protocol, in an 2142 underlying transport layer. 2144 8.10 LOCK Method 2146 The following sections describe the LOCK method, which is used to 2147 take out a lock of any access type. These sections on the LOCK 2148 method describe only those semantics that are specific to the LOCK 2149 method and are independent of the access type of the lock being 2150 requested. 2152 Any resource which supports the LOCK method MUST, at minimum, 2153 support the XML request and response formats defined herein. 2155 8.10.1 Operation 2157 A LOCK method invocation creates the lock specified by the lockinfo 2158 XML element on the Request-URI. Lock method requests SHOULD have a 2159 XML request body which contains an owner XML element for this lock 2160 request, unless this is a refresh request. The LOCK request may have 2161 a Timeout header. 2163 Clients MUST assume that locks may arbitrarily disappear at any 2164 time, regardless of the value given in the Timeout header. The 2165 Timeout header only indicates the behavior of the server if 2166 "extraordinary" circumstances do not occur. For example, an 2167 administrator may remove a lock at any time or the system may crash 2168 in such a way that it loses the record of the lock's existence. The 2169 response MUST contain the value of the lockdiscovery property in a 2170 prop XML element. 2172 In order to indicate the lock token associated with a newly created 2173 lock, a Lock-Token response header MUST be included in the response 2174 for every successful LOCK request for a new lock. Note that the 2175 Lock-Token header would not be returned in the response for a 2176 successful refresh LOCK request because a new lock was not created. 2178 8.10.2 The Effect of Locks on Properties and Collections 2180 The scope of a lock is the entire state of the resource, including 2181 its body and associated properties. As a result, a lock on a 2182 resource MUST also lock the resource's properties. 2184 For collections, a lock also affects the ability to add or remove 2185 members. The nature of the effect depends upon the type of access 2186 control involved. 2188 8.10.3 Locking Replicated Resources 2190 A resource may be made available through more than one URI. However 2191 locks apply to resources, not URIs. Therefore a LOCK request on a 2192 resource MUST NOT succeed if can not be honored by all the URIs 2193 through which the resource is addressable. 2195 8.10.4 Depth and Locking 2197 The Depth header may be used with the LOCK method. Values other 2198 than 0 or infinity MUST NOT be used with the Depth header on a LOCK 2199 method. All resources that support the LOCK method MUST support the 2200 Depth header. 2202 A Depth header of value 0 means to just lock the resource specified 2203 by the Request-URI. 2205 If the Depth header is set to infinity then the resource specified 2206 in the Request-URI along with all its internal members, all the way 2207 down the hierarchy, are to be locked. A successful result MUST 2208 return a single lock token which represents all the resources that 2209 have been locked. If an UNLOCK is successfully executed on this 2210 token, all associated resources are unlocked. If the lock cannot be 2211 granted to all resources, a 409 (Conflict) status code MUST be 2212 returned with a response entity body containing a multistatus XML 2213 element describing which resource(s) prevented the lock from being 2214 granted. Hence, partial success is not an option. Either the 2215 entire hierarchy is locked or no resources are locked. 2217 If no Depth header is submitted on a LOCK request then the request 2218 MUST act as if a "Depth:infinity" had been submitted. 2220 8.10.5 Interaction with other Methods 2222 The interaction of a LOCK with various methods is dependent upon the 2223 lock type. However, independent of lock type, a successful DELETE 2224 of a resource MUST cause all of its locks to be removed. 2226 8.10.6 Lock Compatibility Table 2228 The table below describes the behavior that occurs when a lock 2229 request is made on a resource. 2231 Current lock state/ | Shared Lock | Exclusive 2232 Lock request | | Lock 2233 =====================+=================+=============== 2234 None | True | True 2235 ---------------------+-----------------+--------------- 2236 Shared Lock | True | False 2237 ---------------------+-----------------+--------------- 2238 Exclusive Lock | False | False* 2239 ------------------------------------------------------- 2241 Legend: True = lock may be granted. False = lock MUST NOT be 2242 granted. *=It is illegal for a principal to request the same lock 2243 twice. 2245 The current lock state of a resource is given in the leftmost 2246 column, and lock requests are listed in the first row. The 2247 intersection of a row and column gives the result of a lock request. 2248 For example, if a shared lock is held on a resource, and an 2249 exclusive lock is requested, the table entry is "false", indicating 2250 the lock must not be granted. 2252 8.10.7 Status Codes 2254 200 (OK) - The lock request succeeded and the value of the 2255 lockdiscovery property is included in the body. 2257 412 (Precondition Failed) - The included lock token was not 2258 enforceable on this resource or the server could not satisfy the 2259 request in the lockinfo XML element. 2261 423 (Locked) - The resource is locked, so the method has been 2262 rejected. 2264 8.10.8 Example - Simple Lock Request 2266 >>Request 2268 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2269 Host: webdav.sb.aol.com 2270 Timeout: Infinite, Second-4100000000 2271 Content-Type: text/xml; charset="utf-8" 2272 Content-Length: xyz 2273 Authorization: Digest username="ejw", 2274 realm="ejw@webdav.sb.aol.com", nonce="...", 2275 uri="/workspace/webdav/proposal.doc", 2276 response="...", opaque="..." 2278 2279 2280 2281 2282 2283 http://www.ics.uci.edu/~ejw/contact.html 2284 2285 2286 >>Response 2288 HTTP/1.1 200 OK 2289 Content-Type: text/xml; charset="utf-8" 2290 Content-Length: xxxxx 2292 2293 2294 2295 2296 2297 2298 Infinity 2299 2300 2301 http://www.ics.uci.edu/~ejw/contact.html 2302 2303 2304 Second-604800 2305 2306 2307 opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2308 2309 2310 2311 2312 2314 This example shows the successful creation of an exclusive write 2315 lock on resource 2316 http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The 2317 resource http://www.ics.uci.edu/~ejw/contact.html contains contact 2318 information for the owner of the lock. The server has an activity- 2319 based timeout policy in place on this resource, which causes the 2320 lock to automatically be removed after 1 week (604800 seconds). 2321 Note that the nonce, response, and opaque fields have not been 2322 calculated in the Authorization request header. 2324 8.10.9 Example - Refreshing a Write Lock 2326 >>Request 2328 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2329 Host: webdav.sb.aol.com 2330 Timeout: Infinite, Second-4100000000 2331 If: () 2332 Authorization: Digest username="ejw", 2333 realm="ejw@webdav.sb.aol.com", nonce="...", 2334 uri="/workspace/webdav/proposal.doc", 2335 response="...", opaque="..." 2337 >>Response 2339 HTTP/1.1 200 OK 2340 Content-Type: text/xml; charset="utf-8" 2341 Content-Length: xxxxx 2343 2344 2345 2346 2347 2348 2349 Infinity 2350 2351 2352 http://www.ics.uci.edu/~ejw/contact.html 2353 2354 2355 Second-604800 2356 2357 2358 opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2359 2360 2361 2362 2363 2365 This request would refresh the lock, resetting any time outs. 2366 Notice that the client asked for an infinite time out but the server 2367 choose to ignore the request. In this example, the nonce, response, 2368 and opaque fields have not been calculated in the Authorization 2369 request header. 2371 8.10.10 Example - Multi-Resource Lock Request 2373 >>Request 2375 LOCK /webdav/ HTTP/1.1 2376 Host: webdav.sb.aol.com 2377 Timeout: Infinite, Second-4100000000 2378 Depth: infinity 2379 Content-Type: text/xml; charset="utf-8" 2380 Content-Length: xxxxx 2381 Authorization: Digest username="ejw", 2382 realm="ejw@webdav.sb.aol.com", nonce="...", 2383 uri="/workspace/webdav/proposal.doc", 2384 response="...", opaque="..." 2386 2387 2388 2389 2390 2391 http://www.ics.uci.edu/~ejw/contact.html 2392 2393 2395 >>Response 2397 HTTP/1.1 207 Multi-Status 2398 Content-Type: text/xml; charset="utf-8" 2399 Content-Length: xxxxx 2401 2402 2403 2404 http://webdav.sb.aol.com/webdav/secret 2405 HTTP/1.1 403 Forbidden 2406 2407 2408 http://webdav.sb.aol.com/webdav/ 2409 2410 2411 HTTP/1.1 424 Failed Dependency 2412 2413 2414 2416 This example shows a request for an exclusive write lock on a 2417 collection and all its children. In this request, the client has 2418 specified that it desires an infinite length lock, if available, 2419 otherwise a timeout of 4.1 billion seconds, if available. The 2420 request entity body contains the contact information for the 2421 principal taking out the lock, in this case a web page URL. 2423 The error is a 403 (Forbidden) response on the resource 2424 http://webdav.sb.aol.com/webdav/secret. Because this resource could 2425 not be locked, none of the resources were locked. Note also that 2426 the lockdiscovery property for the Request-URI has been included as 2427 required. In this example the lockdiscovery property is empty which 2428 means that there are no outstanding locks on the resource. 2430 In this example, the nonce, response, and opaque fields have not 2431 been calculated in the Authorization request header. 2433 8.11 UNLOCK Method 2435 The UNLOCK method removes the lock identified by the lock token in 2436 the Lock-Token request header from the Request-URI, and all other 2437 resources included in the lock. If all resources which have been 2438 locked under the submitted lock token can not be unlocked then the 2439 UNLOCK request MUST fail. 2441 Any DAV compliant resource which supports the LOCK method MUST 2442 support the UNLOCK method. 2444 8.11.1 Example - UNLOCK 2446 >>Request 2448 UNLOCK /workspace/webdav/info.doc HTTP/1.1 2449 Host: webdav.sb.aol.com 2450 Lock-Token: 2451 Authorization: Digest username="ejw", 2452 realm="ejw@webdav.sb.aol.com", nonce="...", 2453 uri="/workspace/webdav/proposal.doc", 2454 response="...", opaque="..." 2456 >>Response 2458 HTTP/1.1 204 No Content 2460 In this example, the lock identified by the lock token 2461 "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is 2462 successfully removed from the resource 2463 http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock 2464 included more than just one resource, the lock is removed from all 2465 resources included in the lock. The 204 (No Content) status code is 2466 used instead of 200 (OK) because there is no response entity body. 2468 In this example, the nonce, response, and opaque fields have not 2469 been calculated in the Authorization request header. 2471 9 HTTP Headers for Distributed Authoring 2473 9.1 DAV Header 2475 DAV = "DAV" ":" "1" ["," "2"] ["," 1#extend] 2477 This header indicates that the resource supports the DAV schema and 2478 protocol as specified. All DAV compliant resources MUST return the 2479 DAV header on all OPTIONS responses. 2481 The value is a list of all compliance classes that the resource 2482 supports. Note that above a comma has already been added to the 2. 2483 This is because a resource can not be level 2 compliant unless it is 2484 also level 1 compliant. Please refer to section 15 for more details. 2485 In general, however, support for one compliance class does not 2486 entail support for any other. 2488 9.2 Depth Header 2490 Depth = "Depth" ":" ("0" | "1" | "infinity") 2492 The Depth header is used with methods executed on resources which 2493 could potentially have internal members to indicate whether the 2494 method is to be applied only to the resource ("Depth: 0"), to the 2495 resource and its immediate children, ("Depth: 1"), or the resource 2496 and all its progeny ("Depth: infinity"). 2498 The Depth header is only supported if a method's definition 2499 explicitly provides for such support. 2501 The following rules are the default behavior for any method that 2502 supports the Depth header. A method may override these defaults by 2503 defining different behavior in its definition. 2505 Methods which support the Depth header may choose not to support all 2506 of the header's values and may define, on a case by case basis, the 2507 behavior of the method if a Depth header is not present. For 2508 example, the MOVE method only supports "Depth: infinity" and if a 2509 Depth header is not present will act as if a "Depth: infinity" 2510 header had been applied. 2512 Clients MUST NOT rely upon methods executing on members of their 2513 hierarchies in any particular order or on the execution being atomic 2514 unless the particular method explicitly provides such guarantees. 2516 Upon execution, a method with a Depth header will perform as much of 2517 its assigned task as possible and then return a response specifying 2518 what it was able to accomplish and what it failed to do. 2520 So, for example, an attempt to COPY a hierarchy may result in some 2521 of the members being copied and some not. 2523 Any headers on a method that has a defined interaction with the 2524 Depth header MUST be applied to all resources in the scope of the 2525 method except where alternative behavior is explicitly defined. For 2526 example, an If-Match header will have its value applied against 2527 every resource in the method's scope and will cause the method to 2528 fail if the header fails to match. 2530 If a resource, source or destination, within the scope of the method 2531 with a Depth header is locked in such a way as to prevent the 2532 successful execution of the method, then the lock token for that 2533 resource MUST be submitted with the request in the If request 2534 header. 2536 The Depth header only specifies the behavior of the method with 2537 regards to internal children. If a resource does not have internal 2538 children then the Depth header MUST be ignored. 2540 Please note, however, that it is always an error to submit a value 2541 for the Depth header that is not allowed by the method's definition. 2542 Thus submitting a "Depth: 1" on a COPY, even if the resource does 2543 not have internal members, will result in a 400 (Bad Request). The 2544 method should fail not because the resource doesn't have internal 2545 members, but because of the illegal value in the header. 2547 9.3 Destination Header 2549 Destination = "Destination" ":" absoluteURI 2551 The Destination header specifies a destination resource for methods 2552 such as COPY and MOVE, which take two URIs as parameters. Note that 2553 the absoluteURI production is defined in [RFC2396]. 2555 9.4 If Header 2557 If = "If" ":" ( 1*No-tag-list | 1*Tagged-list) 2558 No-tag-list = List 2559 Tagged-list = Resource 1*List 2560 Resource = Coded-url 2561 List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")" 2562 State-token = Coded-URL 2563 Coded-URL = "<" absoluteURI ">" 2565 The If header is intended to have similar functionality to the If- 2566 Match header defined in section 14.25 of [RFC2068]. However the If 2567 header is intended for use with any URI which represents state 2568 information, referred to as a state token, about a resource as well 2569 as ETags. A typical example of a state token is a lock token, and 2570 lock tokens are the only state tokens defined in this specification. 2572 All DAV compliant resources MUST honor the If header. 2574 The If header's purpose is to describe a series of state lists. If 2575 the state of the resource to which the header is applied does not 2576 match any of the specified state lists then the request MUST fail 2577 with a 412 (Precondition Failed). If one of the described state 2578 lists matches the state of the resource then the request may 2579 succeed. 2581 Note that the absoluteURI production is defined in [RFC2396]. 2583 9.4.1 No-tag-list Production 2585 The No-tag-list production describes a series of state tokens and 2586 ETags. If multiple No-tag-list productions are used then one only 2587 needs to match the state of the resource for the method to be 2588 allowed to continue. 2590 If a method, due to the presence of a Depth or Destination header, 2591 is applied to multiple resources then the No-tag-list production 2592 MUST be applied to each resource the method is applied to. 2594 9.4.1.1 Example - No-tag-list If Header 2596 If: ( ["I am an ETag"]) (["I am 2597 another ETag"]) 2599 The previous header would require that any resources within the 2600 scope of the method must either be locked with the specified lock 2601 token and in the state identified by the "I am an ETag" ETag or in 2602 the state identified by the second ETag "I am another ETag". To put 2603 the matter more plainly one can think of the previous If header as 2604 being in the form (or (and ["I am an 2605 ETag"]) (and ["I am another ETag"])). 2607 9.4.2 Tagged-list Production 2609 The tagged-list production scopes a list production. That is, it 2610 specifies that the lists following the resource specification only 2611 apply to the specified resource. The scope of the resource 2612 production begins with the list production immediately following the 2613 resource production and ends with the next resource production, if 2614 any. 2616 When the If header is applied to a particular resource, the Tagged- 2617 list productions MUST be searched to determine if any of the listed 2618 resources match the operand resource(s) for the current method. If 2619 none of the resource productions match the current resource then the 2620 header MUST be ignored. If one of the resource productions does 2621 match the name of the resource under consideration then the list 2622 productions following the resource production MUST be applied to the 2623 resource in the manner specified in the previous section. 2625 The same URI MUST NOT appear more than once in a resource production 2626 in an If header. 2628 9.4.2.1 Example - Tagged List If header 2630 COPY /resource1 HTTP/1.1 2631 Host: www.foo.bar 2632 Destination: http://www.foo.bar/resource2 2633 If: ( 2634 [W/"A weak ETag"]) (["strong ETag"]) 2635 (["another strong ETag"]) 2637 In this example http://www.foo.bar/resource1 is being copied to 2638 http://www.foo.bar/resource2. When the method is first applied to 2639 http://www.foo.bar/resource1, resource1 must be in the state 2640 specified by "( [W/"A weak ETag"]) 2641 (["strong ETag"])", that is, it either must be locked with a lock 2642 token of "locktoken:a-write-lock-token" and have a weak entity tag 2643 W/"A weak ETag" or it must have a strong entity tag "strong ETag". 2645 That is the only success condition since the resource 2646 http://www.bar.bar/random never has the method applied to it (the 2647 only other resource listed in the If header) and 2648 http://www.foo.bar/resource2 is not listed in the If header. 2650 9.4.3 not Production 2652 Every state token or ETag is either current, and hence describes the 2653 state of a resource, or is not current, and does not describe the 2654 state of a resource. The boolean operation of matching a state token 2655 or ETag to the current state of a resource thus resolves to a true 2656 or false value. The not production is used to reverse that value. 2657 The scope of the not production is the state-token or entity-tag 2658 immediately following it. 2660 If: (Not ) 2662 When submitted with a request, this If header requires that all 2663 operand resources must not be locked with locktoken:write1 and must 2664 be locked with locktoken:write2. 2666 9.4.4 Matching Function 2668 When performing If header processing, the definition of a matching 2669 state token or entity tag is as follows. 2671 Matching entity tag: Where the entity tag matches an entity tag 2672 associated with that resource. 2674 Matching state token: Where there is an exact match between the 2675 state token in the If header and any state token on the resource. 2677 9.4.5 If Header and Non-DAV Compliant Proxies 2679 Non-DAV compliant proxies will not honor the If header, since they 2680 will not understand the If header, and HTTP requires non-understood 2681 headers to be ignored. When communicating with HTTP/1.1 proxies, 2682 the "Cache-Control: no-cache" request header MUST be used so as to 2683 prevent the proxy from improperly trying to service the request from 2684 its cache. When dealing with HTTP/1.0 proxies the "Pragma: no- 2685 cache" request header MUST be used for the same reason. 2687 9.5 Lock-Token Header 2689 Lock-Token = "Lock-Token" ":" Coded-URL 2691 The Lock-Token request header is used with the UNLOCK method to 2692 identify the lock to be removed. The lock token in the Lock-Token 2693 request header MUST identify a lock that contains the resource 2694 identified by Request-URI as a member. 2696 The Lock-Token response header is used with the LOCK method to 2697 indicate the lock token created as a result of a successful LOCK 2698 request to create a new lock. 2700 9.6 Overwrite Header 2702 Overwrite = "Overwrite" ":" ("T" | "F") 2704 The Overwrite header specifies whether the server should overwrite 2705 the state of a non-null destination resource during a COPY or MOVE. 2706 A value of "F" states that the server must not perform the COPY or 2707 MOVE operation if the state of the destination resource is non-null. 2708 If the overwrite header is not included in a COPY or MOVE request 2709 then the resource MUST treat the request as if it has an overwrite 2710 header of value "T". While the Overwrite header appears to duplicate 2711 the functionality of the If-Match: * header of HTTP/1.1, If-Match 2712 applies only to the Request-URI, and not to the Destination of a 2713 COPY or MOVE. 2715 If a COPY or MOVE is not performed due to the value of the Overwrite 2716 header, the method MUST fail with a 412 (Precondition Failed) status 2717 code. 2719 All DAV compliant resources MUST support the Overwrite header. 2721 9.7 Status-URI Response Header 2723 The Status-URI response header may be used with the 102 (Processing) 2724 status code to inform the client as to the status of a method. 2726 Status-URI = "Status-URI" ":" *(Status-Code Coded-URL) ; Status-Code 2727 is defined in 6.1.1 of [RFC2068] 2728 The URIs listed in the header are source resources which have been 2729 affected by the outstanding method. The status code indicates the 2730 resolution of the method on the identified resource. So, for 2731 example, if a MOVE method on a collection is outstanding and a 102 2732 (Processing) response with a Status-URI response header is returned, 2733 the included URIs will indicate resources that have had move 2734 attempted on them and what the result was. 2736 9.8 Timeout Request Header 2738 TimeOut = "Timeout" ":" 1#TimeType 2739 TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other) 2740 DAVTimeOutVal = 1*digit 2741 Other = Extend field-value ; See section 4.2 of [RFC2068] 2743 Clients may include Timeout headers in their LOCK requests. 2744 However, the server is not required to honor or even consider these 2745 requests. Clients MUST NOT submit a Timeout request header with any 2746 method other than a LOCK method. 2748 A Timeout request header MUST contain at least one TimeType and may 2749 contain multiple TimeType entries. The purpose of listing multiple 2750 TimeType entries is to indicate multiple different values and value 2751 types that are acceptable to the client. The client lists the 2752 TimeType entries in order of preference. 2754 Timeout response valuse MUST use a Second value, Infinite, or a 2755 TimeType the client has indicated familiarity with. The server may 2756 assume a client is familiar with any TimeType submitted in a Timeout 2757 header. 2759 The "Second" TimeType specifies the number of seconds that will 2760 elapse between granting of the lock at the server, and the automatic 2761 removal of the lock. The timeout value for timetype "Second" MUST 2762 NOT be greater than 2^32-1. 2764 The timeout counter SHOULD be restarted any time an owner of the 2765 lock sends a method to any member of the lock, including unsupported 2766 methods, or methods which are unsuccessful. However the lock MUST 2767 be refreshed if a refresh LOCK method is successfully received. 2769 If the timeout expires then the lock may be lost. Specifically, if 2770 the server wishes to harvest the lock upon time-out, the server 2771 SHOULD act as if an UNLOCK method was executed by the server on the 2772 resource using the lock token of the timed-out lock, performed with 2773 its override authority. Thus logs should be updated with the 2774 disposition of the lock, notifications should be sent, etc., just as 2775 they would be for an UNLOCK request. 2777 Servers are advised to pay close attention to the values submitted 2778 by clients, as they will be indicative of the type of activity the 2779 client intends to perform. For example, an applet running in a 2780 browser may need to lock a resource, but because of the instability 2781 of the environment within which the applet is running, the applet 2782 may be turned off without warning. As a result, the applet is 2783 likely to ask for a relatively small timeout value so that if the 2784 applet dies, the lock can be quickly harvested. However, a document 2785 management system is likely to ask for an extremely long timeout 2786 because its user may be planning on going off-line. 2788 A client MUST NOT assume that just because the time-out has expired 2789 the lock has been lost. 2791 10 Status Code Extensions to HTTP/1.1 2793 The following status codes are added to those defined in HTTP/1.1 2794 [RFC2068]. 2796 10.1 102 Processing 2798 The 102 (Processing) status code is an interim response used to 2799 inform the client that the server has accepted the complete request, 2800 but has not yet completed it. This status code SHOULD only be sent 2801 when the server has a reasonable expectation that the request will 2802 take significant time to complete. As guidance, if a method is 2803 taking longer than 20 seconds (a reasonable, but arbitrary value) to 2804 process the server SHOULD return a 102 (Processing) response. The 2805 server MUST send a final response after the request has been 2806 completed. 2808 Methods can potentially take a long period of time to process, 2809 especially methods that support the Depth header. In such cases the 2810 client may time-out the connection while waiting for a response. To 2811 prevent this the server may return a 102 (Processing) status code to 2812 indicate to the client that the server is still processing the 2813 method. 2815 10.2 207 Multi-Status 2817 The 207 (Multi-Status) status code provides status for multiple 2818 independent operations (see section 11 for more information). 2820 10.3 422 Unprocessable Entity 2822 The 422 (Unprocessable Entity) status code means the server 2823 understands the content type of the request entity (hence a 2824 415(Unsupported Media Type) status code is inappropriate), and the 2825 syntax of the request entity is correct (thus a 400 (Bad Request) 2826 status code is inappropriate) but was unable to process the 2827 contained instructions. For example, this error condition may occur 2828 if an XML request body contains well-formed (i.e., syntactically 2829 correct), but semantically erroneous XML instructions. 2831 10.4 423 Locked 2833 The 423 (Locked) status code means the source or destination 2834 resource of a method is locked. 2836 10.5 424 Failed Dependency 2838 The 424 (Failed Dependency) status code means that the method could 2839 not be performed on the resource because the requested action 2840 depended on another action and that action failed. For example, if 2841 a command in a PROPPATCH method fails then, at minimum, the rest of 2842 the commands will also fail with 424 (Failed Dependency). 2844 10.6 507 Insufficient Storage 2846 The 507 (Insufficient Storage) status code means the method could 2847 not be performed on the resource because the server is unable to 2848 store the representation needed to successfully complete the 2849 request. This condition is considered to be temporary. If the 2850 request which received this status code was the result of a user 2851 action, the request MUST NOT be repeated until it is requested by a 2852 separate user action. 2854 11 Multi-Status Response 2856 The default 207 (Multi-Status) response body is a text/xml or 2857 application/xml HTTP entity that contains a single XML element 2858 called multistatus, which contains a set of XML elements called 2859 response which contain 200, 300, 400, and 500 series status codes 2860 generated during the method invocation. 100 series status codes 2861 SHOULD NOT be recorded in a response XML element. 2863 12 XML Element Definitions 2865 In the section below, the final line of each section gives the 2866 element type declaration using the format defined in [REC-XML]. The 2867 "Value" field, where present, specifies futher restrictions on the 2868 allowable contents of the XML element using BNF (i.e., to further 2869 restrict the values of a PCDATA element). 2871 12.1 activelock XML Element 2873 Name: activelock 2874 Namespace: DAV: 2875 Purpose: Describes a lock on a resource. 2877 2880 12.1.1 depth XML Element 2882 Name: depth 2883 Namespace: DAV: 2884 Purpose: The value of the Depth header. 2885 Value: "0" | "1" | "infinity" 2887 2889 12.1.2 locktoken XML Element 2891 Name: locktoken 2892 Namespace: DAV: 2893 Purpose: The lock token associated with a lock. 2894 Description: The href contains one or more opaque lock token URIs 2895 which all refer to the same lock (i.e., the OpaqueLockToken-URI 2896 production in section 6.4). 2898 2900 12.1.3 timeout XML Element 2902 Name: timeout 2903 Namespace: DAV: 2904 Purpose: The timeout associated with a lock 2905 Value: TimeType ;Defined in section 9.8 2907 2909 12.2 collection XML Element 2911 Name: collection 2912 Namespace: DAV: 2913 Purpose: Identifies the associated resource as a collection. The 2914 resourcetype property of a collection resource MUST have this value. 2916 2918 12.3 href XML Element 2920 Name: href 2921 Namespace: DAV: 2922 Purpose: Identifies the content of the element as a URI. 2923 Value: URI ; See section 3.2.1 of [RFC2068] 2925 2927 12.4 link XML Element 2929 Name: link 2930 Namespace: DAV: 2931 Purpose: Identifies the property as a link and contains the 2932 source and destination of that link. 2933 Description: The link XML element is used to provide the sources and 2934 destinations of a link. The name of the property containing the 2935 link XML element provides the type of the link. Link is a multi- 2936 valued element, so multiple links may be used together to indicate 2937 multiple links with the same type. The values in the href XML 2938 elements inside the src and dst XML elements of the link XML element 2939 MUST NOT be rejected if they point to resources which do not exist. 2941 2943 12.4.1 dst XML Element 2945 Name: dst 2946 Namespace: DAV: 2947 Purpose: Indicates the destination of a link 2948 Value: URI 2950 2952 12.4.2 src XML Element 2954 Name: src 2955 Namespace: DAV: 2956 Purpose: Indicates the source of a link. 2957 Value: URI 2959 2961 12.5 lockentry XML Element 2963 Name: lockentry 2964 Namespace: DAV: 2965 Purpose: Defines the types of locks that can be used with the 2966 resource. 2968 2970 12.6 lockinfo XML Element 2972 Name: lockinfo 2973 Namespace: DAV: 2974 Purpose: The lockinfo XML element is used with a LOCK method to 2975 specify the type of lock the client wishes to have created. 2977 2979 12.7 lockscope XML Element 2981 Name: lockscope 2982 Namespace: DAV: 2983 Purpose: Specifies whether a lock is an exclusive lock, or a 2984 shared lock. 2986 2988 12.7.1 exclusive XML Element 2990 Name: exclusive 2991 Namespace: DAV: 2992 Purpose: Specifies an exclusive lock 2994 2996 12.7.2 shared XML Element 2998 Name: shared 2999 Namespace: DAV: 3000 Purpose: Specifies a shared lock 3002 3004 12.8 locktype XML Element 3006 Name: locktype 3007 Namespace: DAV: 3008 Purpose: Specifies the access type of a lock. At present, this 3009 specification only defines one lock type, the write lock. 3011 3013 12.8.1 write XML Element 3015 Name: write 3016 Namespace: DAV: 3017 Purpose: Specifies a write lock. 3019 3021 12.9 multistatus XML Element 3023 Name: multistatus 3024 Namespace: DAV: 3025 Purpose: Contains multiple response messages. 3026 Description: The responsedescription at the top level is used to 3027 provide a general message describing the overarching nature of the 3028 response. If this value is available an application may use it 3029 instead of presenting the individual response descriptions contained 3030 within the responses. 3032 3034 12.9.1 response XML Element 3036 Name: response 3037 Namespace: DAV: 3038 Purpose: Holds a single response describing the effect of a 3039 method on resource and/or its properties. 3040 Description: A particular href MUST NOT appear more than once as the 3041 child of a response XML element under a multistatus XML element. 3042 This requirement is necessary in order to keep processing costs for 3043 a response to linear time. Essentially, this prevents having to 3044 search in order to group together all the responses by href. There 3045 are, however, no requirements regarding ordering based on href 3046 values. 3048 3051 12.9.1.1 propstat XML Element 3053 Name: propstat 3054 Namespace: DAV: 3055 Purpose: Groups together a prop and status element that is 3056 associated with a particular href element. 3057 Description: The propstat XML element MUST contain one prop XML 3058 element and one status XML element. The contents of the prop XML 3059 element MUST only list the names of properties to which the result 3060 in the status element applies. 3062 3064 12.9.1.2 status XML Element 3066 Name: status 3067 Namespace: DAV: 3068 Purpose: Holds a single HTTP status-line 3069 Value: status-line ;status-line defined in [RFC2068] 3071 3073 12.9.2 responsedescription XML Element 3075 Name: responsedescription 3076 Namespace: DAV: 3077 Purpose: Contains a message that can be displayed to the user 3078 explaining the nature of the response. 3079 Description: This XML element provides information suitable to be 3080 presented to a user. 3082 3084 12.10 owner XML Element 3086 Name: owner 3087 Namespace: DAV: 3088 Purpose: Provides information about the principal taking out a 3089 lock. 3090 Description: The owner XML element provides information sufficient 3091 for either directly contacting a principal (such as a telephone 3092 number or Email URI), or for discovering the principal (such as the 3093 URL of a homepage) who owns a lock. 3095 3097 12.11 prop XML element 3099 Name: prop 3100 Namespace: DAV: 3101 Purpose: Contains properties related to a resource. 3102 Description: The prop XML element is a generic container for 3103 properties defined on resources. All elements inside a prop XML 3104 element MUST define properties related to the resource. No other 3105 elements may be used inside of a prop element. 3107 3109 12.12 propertybehavior XML element 3111 Name: propertybehavior 3112 Namespace: DAV: 3113 Purpose: Specifies how properties are handled during a COPY or 3114 MOVE. 3115 Description: The propertybehavior XML element specifies how 3116 properties are handled during a COPY or MOVE. If this XML element 3117 is not included in the request body then the server is expected to 3118 act as defined by the default property handling behavior of the 3119 associated method. All WebDAV compliant resources MUST support the 3120 propertybehavior XML element. 3122 3124 12.12.1 keepalive XML element 3126 Name: keepalive 3127 Namespace: DAV: 3128 Purpose: Specifies requirements for the copying/moving of live 3129 properties. 3130 Description: If a list of URIs is included as the value of keepalive 3131 then the named properties MUST be "live" after they are copied 3132 (moved) to the destination resource of a COPY (or MOVE). If the 3133 value "*" is given for the keepalive XML element, this designates 3134 that all live properties on the source resource MUST be live on the 3135 destination. If the requirements specified by the keepalive element 3136 can not be honored then the method MUST fail with a 412 3137 (Precondition Failed). All DAV compliant resources MUST support the 3138 keepalive XML element for use with the COPY and MOVE methods. 3139 Value: "*" ; #PCDATA value can only be "*" 3141 3143 12.12.2 omit XML element 3145 Name: omit 3146 Namespace: DAV: 3147 Purpose: The omit XML element instructs the server that it should 3148 use best effort to copy properties but a failure to copy a property 3149 MUST NOT cause the method to fail. 3150 Description: The default behavior for a COPY or MOVE is to copy/move 3151 all properties or fail the method. In certain circumstances, such 3152 as when a server copies a resource over another protocol such as 3153 FTP, it may not be possible to copy/move the properties associated 3154 with the resource. Thus any attempt to copy/move over FTP would 3155 always have to fail because properties could not be moved over, even 3156 as dead properties. All DAV compliant resources MUST support the 3157 omit XML element on COPY/MOVE methods. 3159 3161 12.13 propertyupdate XML element 3163 Name: propertyupdate 3164 Namespace: DAV: 3165 Purpose: Contains a request to alter the properties on a 3166 resource. 3167 Description: This XML element is a container for the information 3168 required to modify the properties on the resource. This XML element 3169 is multi-valued. 3171 3173 12.13.1 remove XML element 3175 Name: remove 3176 Namespace: DAV: 3177 Purpose: Lists the DAV properties to be removed from a resource. 3178 Description: Remove instructs that the properties specified in prop 3179 should be removed. Specifying the removal of a property that does 3180 not exist is not an error. All the XML elements in a prop XML 3181 element inside of a remove XML element MUST be empty, as only the 3182 names of properties to be removed are required. 3184 3186 12.13.2 set XML element 3188 Name: set 3189 Namespace: DAV: 3190 Purpose: Lists the DAV property values to be set for a resource. 3191 Description: The set XML element MUST contain only a prop XML 3192 element. The elements contained by the prop XML element inside the 3193 set XML element MUST specify the name and value of properties that 3194 are set on the Request-URI. If a property already exists then its 3195 value is replaced. Language tagging information in the property's 3196 value (in the "xml:lang" attribute, if present) MUST be persistently 3197 stored along with the property, and MUST be subsequently retrievable 3198 using PROPFIND. 3200 3202 12.14 propfind XML Element 3204 Name: propfind 3205 Namespace: DAV: 3206 Purpose: Specifies the properties to be returned from a PROPFIND 3207 method. Two special elements are specified for use with propfind, 3208 allprop and propname. If prop is used inside propfind it MUST only 3209 contain property names, not values. 3211 3213 12.14.1 allprop XML Element 3215 Name: allprop 3216 Namespace: DAV: 3217 Purpose: The allprop XML element specifies that all property 3218 names and values on the resource are to be returned. 3220 3222 12.14.2 propname XML Element 3224 Name: propname 3225 Namespace: DAV: 3226 Purpose: The propname XML element specifies that only a list of 3227 property names on the resource is to be returned. 3229 3231 13 DAV Properties 3233 For DAV properties, the name of the property is also the same as the 3234 name of the XML element that contains its value. In the section 3235 below, the final line of each section gives the element type 3236 declaration using the format defined in [REC-XML]. The "Value" 3237 field, where present, specifies futher restrictions on the allowable 3238 contents of the XML element using BNF (i.e., to further restrict the 3239 values of a PCDATA element). 3241 13.1 creationdate Property 3243 Name: creationdate 3244 Namespace: DAV: 3245 Purpose: Records the time and date the resource was created. 3246 Value: date-time ; See Appendix 2 3247 Description: The creationdate property should be defined on all DAV 3248 compliant resources. If present, it contains a timestamp of the 3249 moment when the resource was created (i.e., the moment it had non- 3250 null state). 3252 3254 13.2 displayname Property 3256 Name: displayname 3257 Namespace: DAV: 3258 Purpose: Provides a name for the resource that is suitable for 3259 presentation to a user. 3260 Description: The displayname property should be defined on all DAV 3261 compliant resources. If present, the property contains a 3262 description of the resource that is suitable for presentation to a 3263 user. 3265 3267 13.3 getcontentlanguage Property 3269 Name: getcontentlanguage 3270 Namespace: DAV: 3271 Purpose: Contains the Content-Language header returned by a GET 3272 without accept headers 3273 Description: The getcontentlanguage property MUST be defined on any 3274 DAV compliant resource that returns the Content-Language header on a 3275 GET. 3276 Value: language-tag ;language-tag is defined in section 14.13 3277 of [RFC2068] 3279 3281 13.4 getcontentlength Property 3283 Name: getcontentlength 3284 Namespace: DAV: 3285 Purpose: Contains the Content-Length header returned by a GET 3286 without accept headers. 3287 Description: The getcontentlength property MUST be defined on any 3288 DAV compliant resource that returns the Content-Length header in 3289 response to a GET. 3290 Value: content-length ; see section 14.14 of [RFC2068] 3292 3294 13.5 getcontenttype Property 3296 Name: getcontenttype 3297 Namespace: DAV: 3298 Purpose: Contains the Content-Type header returned by a GET 3299 without accept headers. 3300 Description: This getcontenttype property MUST be defined on any DAV 3301 compliant resource that returns the Content-Type header in response 3302 to a GET. 3303 Value: media-type ; defined in section 3.7 of [RFC2068] 3305 3307 13.6 getetag Property 3309 Name: getetag 3310 Namespace: DAV: 3311 Purpose: Contains the ETag header returned by a GET without 3312 accept headers. 3313 Description: The getetag property MUST be defined on any DAV 3314 compliant resource that returns the Etag header. 3315 Value: entity-tag ; defined in section 3.11 of [RFC2068] 3317 3319 13.7 getlastmodified Property 3321 Name: getlastmodified 3322 Namespace: DAV: 3323 Purpose: Contains the Last-Modified header returned by a GET 3324 method without accept headers. 3325 Description: Note that the last-modified date on a resource may 3326 reflect changes in any part of the state of the resource, not 3327 necessarily just a change to the response to the GET method. For 3328 example, a change in a property may cause the last-modified date to 3329 change. The getlastmodified property MUST be defined on any DAV 3330 compliant resource that returns the Last-Modified header in response 3331 to a GET. 3332 Value: HTTP-date ; defined in section 3.3.1 of [RFC2068] 3334 3336 13.8 lockdiscovery Property 3338 Name: lockdiscovery 3339 Namespace: DAV: 3340 Purpose: Describes the active locks on a resource 3341 Description: The lockdiscovery property returns a listing of who has 3342 a lock, what type of lock he has, the timeout type and the time 3343 remaining on the timeout, and the associated lock token. The server 3344 is free to withhold any or all of this information if the requesting 3345 principal does not have sufficient access rights to see the 3346 requested data. 3348 3350 13.8.1 Example - Retrieving the lockdiscovery Property 3352 >>Request 3354 PROPFIND /container/ HTTP/1.1 3355 Host: www.foo.bar 3356 Content-Length: xxxx 3357 Content-Type: text/xml; charset="utf-8" 3359 3360 3361 3362 3363 >>Response 3365 HTTP/1.1 207 Multi-Status 3366 Content-Type: text/xml; charset="utf-8" 3367 Content-Length: xxxxx 3369 3370 3371 3372 http://www.foo.bar/container/ 3373 3374 3375 3376 3377 3378 3379 0 3380 Jane Smith 3381 Infinite 3382 3383 3384 opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76 3385 3386 3387 3388 3389 3390 HTTP/1.1 200 OK 3391 3392 3393 3395 This resource has a single exclusive write lock on it, with an 3396 infinite timeout. 3398 13.9 resourcetype Property 3400 Name: resourcetype 3401 Namespace: DAV: 3402 Purpose: Specifies the nature of the resource. 3403 Description: The resourcetype property MUST be defined on all DAV 3404 compliant resources. The default value is empty. 3406 3408 13.10 source Property 3410 Name: source 3411 Namespace: DAV: 3412 Purpose: The destination of the source link identifies the 3413 resource that contains the unprocessed source of the link's source. 3414 Description: The source of the link (src) is typically the URI of 3415 the output resource on which the link is defined, and there is 3416 typically only one destination (dst) of the link, which is the URI 3417 where the unprocessed source of the resource may be accessed. When 3418 more than one link destination exists, this specification asserts no 3419 policy on ordering. 3421 3423 13.10.1 Example - A source Property 3425 3426 3427 3428 3429 Source 3430 http://foo.bar/program 3431 http://foo.bar/src/main.c 3432 3433 3434 Library 3435 http://foo.bar/program 3436 http://foo.bar/src/main.lib 3437 3438 3439 Makefile 3440 http://foo.bar/program 3441 http://foo.bar/src/makefile 3442 3443 3444 3446 In this example the resource http://foo.bar/program has a source 3447 property that contains three links. Each link contains three 3448 elements, two of which, src and dst, are part of the DAV schema 3449 defined in this document, and one which is defined by the schema 3450 http://www.foocorp.com/project/ (Source, Library, and Makefile). A 3451 client which only implements the elements in the DAV spec will not 3452 understand the foocorp elements and will ignore them, thus seeing 3453 the expected source and destination links. An enhanced client may 3454 know about the foocorp elements and be able to present the user with 3455 additional information about the links. This example demonstrates 3456 the power of XML markup, allowing element values to be enhanced 3457 without breaking older clients. 3459 13.11 supportedlock Property 3461 Name: supportedlock 3462 Namespace: DAV: 3463 Purpose: To provide a listing of the lock capabilities supported 3464 by the resource. 3465 Description: The supportedlock property of a resource returns a 3466 listing of the combinations of scope and access types which may be 3467 specified in a lock request on the resource. Note that the actual 3468 contents are themselves controlled by access controls so a server is 3469 not required to provide information the client is not authorized to 3470 see. 3472 3474 13.11.1 Example - Retrieving the supportedlock Property 3476 >>Request 3478 PROPFIND /container/ HTTP/1.1 3479 Host: www.foo.bar 3480 Content-Length: xxxx 3481 Content-Type: text/xml; charset="utf-8" 3483 3484 3485 3486 3487 >>Response 3489 HTTP/1.1 207 Multi-Status 3490 Content-Type: text/xml; charset="utf-8"Content-Length: xxxxx 3492 3493 3494 3495 http://www.foo.bar/container/ 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 HTTP/1.1 200 OK 3510 3511 3512 3514 14 Instructions for Processing XML in DAV 3516 All DAV compliant resources MUST ignore any unknown XML element and 3517 all its children encountered while processing a DAV method that uses 3518 XML as its command language. 3520 This restriction also applies to the processing, by clients, of DAV 3521 property values where unknown XML elements SHOULD be ignored unless 3522 the property's schema declares otherwise. 3524 This restriction does not apply to setting dead DAV properties on 3525 the server where the server MUST record unknown XML elements. 3527 Additionally, this restriction does not apply to the use of XML 3528 where XML happens to be the content type of the entity body, for 3529 example, when used as the body of a PUT. 3531 15 DAV Compliance Classes 3533 A DAV compliant resource can choose from two classes of compliance. 3534 A client can discover the compliance classes of a resource by 3535 executing OPTIONS on the resource, and examining the "DAV" header 3536 which is returned. 3538 Since this document describes extensions to the HTTP/1.1 protocol, 3539 minimally all DAV compliant resources, clients, and proxies MUST be 3540 compliant with [RFC2068]. 3542 Compliance classes are not necessarily sequential. A resource that 3543 is class 2 compliant must also be class 1 compliant; but if 3544 additional compliance classes are defined later, a resource that is 3545 class 1, 2, and 4 compliant might not be class 3 compliant. Also 3546 note that identifiers other than numbers may be used as compliance 3547 class identifiers. 3549 15.1 Class 1 3551 A class 1 compliant resource MUST meet all "MUST" requirements in 3552 all sections of this document. 3554 Class 1 compliant resources MUST return, at minimum, the value "1" 3555 in the DAV header on all responses to the OPTIONS method. 3557 15.2 Class 2 3559 A class 2 compliant resource MUST meet all class 1 requirements and 3560 support the LOCK method, the supportedlock property, the 3561 lockdiscovery property, the Time-Out response header and the Lock- 3562 Token request header. A class "2" compliant resource SHOULD also 3563 support the Time-Out request header and the owner XML element. 3565 Class 2 compliant resources MUST return, at minimum, the values "1" 3566 and "2" in the DAV header on all responses to the OPTIONS method. 3568 16 Internationalization Considerations 3570 In the realm of internationalization, this specification complies 3571 with the IETF Character Set Policy [RFC2277]. In this specification, 3572 human-readable fields can be found either in the value of a 3573 property, or in an error message returned in a response entity body. 3574 In both cases, the human-readable content is encoded using XML, 3575 which has explicit provisions for character set tagging and 3576 encoding, and requires that XML processors read XML elements 3577 encoded, at minimum, using the UTF-8 [UTF-8] encoding of the ISO 3578 10646 multilingual plane. XML examples in this specification 3579 demonstrate use of the charset parameter of the Content-Type header, 3580 as defined in [RFC2376], as well as the XML "encoding" attribute, 3581 which together provide charset identification information for MIME 3582 and XML processors. 3584 XML also provides a language tagging capability for specifying the 3585 language of the contents of a particular XML element. XML uses 3586 either IANA registered language tags (see [RFC1766]) or ISO 639 3587 language tags [ISO-639] in the "xml:lang" attribute of an XML 3588 element to identify the language of its content and attributes. 3590 WebDAV applications MUST support the character set tagging, 3591 character set encoding, and the language tagging functionality of 3592 the XML specification. Implementors of WebDAV applications are 3593 strongly encouraged to read "XML Media Types" [RFC2376] for 3594 instruction on which MIME media type to use for XML transport, and 3595 on use of the charset parameter of the Content-Type header. 3597 Names used within this specification fall into three categories: 3598 names of protocol elements such as methods and headers, names of XML 3599 elements, and names of properties. Naming of protocol elements 3600 follows the precedent of HTTP, using English names encoded in 3601 USASCII for methods and headers. Since these protocol elements are 3602 not visible to users, and are in fact simply long token identifiers, 3603 they do not need to support encoding in multiple character sets. 3604 Similarly, though the names of XML elements used in this 3605 specification are English names encoded in UTF-8, these names are 3606 not visible to the user, and hence do not need to support multiple 3607 character set encodings. 3609 The name of a property defined on a resource is a URI. Although 3610 some applications (e.g., a generic property viewer) will display 3611 property URIs directly to their users, it is expected that the 3612 typical application will use a fixed set of properties, and will 3613 provide a mapping from the property name URI to a human-readable 3614 field when displaying the property name to a user. It is only in 3615 the case where the set of properties is not known ahead of time that 3616 an application need display a property name URI to a user. We 3617 recommend that applications provide human-readable property names 3618 wherever feasible. 3620 For error reporting, we follow the convention of HTTP/1.1 status 3621 codes, including with each status code a short, English description 3622 of the code (e.g., 423 (Locked)). While the possibility exists that 3623 a poorly crafted user agent would display this message to a user, 3624 internationalized applications will ignore this message, and display 3625 an appropriate message in the user's language and character set. 3627 Since interoperation of clients and servers does not require locale 3628 information, this specification does not specify any mechanism for 3629 transmission of this information. 3631 17 Security Considerations 3633 This section is provided to detail issues concerning security 3634 implications of which WebDAV applications need to be aware. 3636 All of the security considerations of HTTP/1.1 (discussed in 3637 [RFC2068]) and XML (discussed in [RFC2376]) also apply to WebDAV. In 3638 addition, the security risks inherent in remote authoring require 3639 stronger authentication technology, introduce several new privacy 3640 concerns, and may increase the hazards from poor server design. 3641 These issues are detailed below. 3643 17.1 Authentication of Clients 3645 Due to their emphasis on authoring, WebDAV servers need to use 3646 authentication technology to protect not just access to a network 3647 resource, but the integrity of the resource as well. Furthermore, 3648 the introduction of locking functionality requires support for 3649 authentication. 3651 A password sent in the clear over an insecure channel is an 3652 inadequate means for protecting the accessibility and integrity of a 3653 resource as the password may be intercepted. Since Basic 3654 authentication for HTTP/1.1 performs essentially clear text 3655 transmission of a password, Basic authentication MUST NOT be used to 3656 authenticate a WebDAV client to a server unless the connection is 3657 secure. Furthermore, a WebDAV server MUST NOT send Basic 3658 authentication credentials in a WWW-Authenticate header unless the 3659 connection is secure. Examples of secure connections include a 3660 Transport Layer Security (TLS) connection employing a strong cipher 3661 suite with mutual authentication of client and server, or a 3662 connection over a network which is physically secure, for example, 3663 an isolated network in a building with restricted access. 3665 WebDAV applications MUST support the Digest authentication scheme 3666 [RFC2069]. Since Digest authentication verifies that both parties to 3667 a communication know a shared secret, a password, without having to 3668 send that secret in the clear, Digest authentication avoids the 3669 security problems inherent in Basic authentication while providing a 3670 level of authentication which is useful in a wide range of 3671 scenarios. 3673 17.2 Denial of Service 3675 Denial of service attacks are of special concern to WebDAV servers. 3676 WebDAV plus HTTP enables denial of service attacks on every part of 3677 a system's resources. 3679 The underlying storage can be attacked by PUTting extremely large 3680 files. 3682 Asking for recursive operations on large collections can attack 3683 processing time. 3685 Making multiple pipelined requests on multiple connections can 3686 attack network connections. 3688 WebDAV servers need to be aware of the possibility of a denial of 3689 service attack at all levels. 3691 17.3 Security through Obscurity 3693 WebDAV provides, through the PROPFIND method, a mechanism for 3694 listing the member resources of a collection. This greatly 3695 diminishes the effectiveness of security or privacy techniques that 3696 rely only on the difficulty of discovering the names of network 3697 resources. Users of WebDAV servers are encouraged to use access 3698 control techniques to prevent unwanted access to resources, rather 3699 than depending on the relative obscurity of their resource names. 3701 17.4 Privacy Issues Connected to Locks 3703 When submitting a lock request a user agent may also submit an owner 3704 XML field giving contact information for the person taking out the 3705 lock (for those cases where a person, rather than a robot, is taking 3706 out the lock). This contact information is stored in a lockdiscovery 3707 property on the resource, and can be used by other collaborators to 3708 begin negotiation over access to the resource. However, in many 3709 cases this contact information can be very private, and should not 3710 be widely disseminated. Servers SHOULD limit read access to the 3711 lockdiscovery property as appropriate. Furthermore, user agents 3712 SHOULD provide control over whether contact information is sent at 3713 all, and if contact information is sent, control over exactly what 3714 information is sent. 3716 17.5 Privacy Issues Connected to Properties 3718 Since property values are typically used to hold information such as 3719 the author of a document, there is the possibility that privacy 3720 concerns could arise stemming from widespread access to a resource's 3721 property data. To reduce the risk of inadvertent release of private 3722 information via properties, servers are encouraged to develop access 3723 control mechanisms that separate read access to the resource body 3724 and read access to the resource's properties. This allows a user to 3725 control the dissemination of their property data without overly 3726 restricting access to the resource's contents. 3728 17.6 Reduction of Security due to Source Link 3730 HTTP/1.1 warns against providing read access to script code because 3731 it may contain sensitive information. Yet WebDAV, via its source 3732 link facility, can potentially provide a URL for script resources so 3733 they may be authored. For HTTP/1.1, a server could reasonably 3734 prevent access to source resources due to the predominance of read- 3735 only access. WebDAV, with its emphasis on authoring, encourages 3736 read and write access to source resources, and provides the source 3737 link facility to identify the source. This reduces the security 3738 benefits of eliminating access to source resources. Users and 3739 administrators of WebDAV servers should be very cautious when 3740 allowing remote authoring of scripts, limiting read and write access 3741 to the source resources to authorized principals. 3743 17.7 Implications of XML External Entities 3745 XML supports a facility known as "external entities", defined in 3746 section 4.2.2 of [REC-XML], which instruct an XML processor to 3747 retrieve and perform an inline include of XML located at a 3748 particular URI. An external XML entity can be used to append or 3749 modify the document type declaration (DTD) associated with an XML 3750 document. An external XML entity can also be used to include XML 3751 within the content of an XML document. For non-validating XML, such 3752 as the XML used in this specification, including an external XML 3753 entity is not required by [REC-XML]. However, [REC-XML] does state 3754 that an XML processor may, at its discretion, include the external 3755 XML entity. 3757 External XML entities have no inherent trustworthiness and are 3758 subject to all the attacks that are endemic to any HTTP GET request. 3759 Furthermore, it is possible for an external XML entity to modify the 3760 DTD, and hence affect the final form of an XML document, in the 3761 worst case significantly modifying its semantics, or exposing the 3762 XML processor to the security risks discussed in [RFC2376]. 3763 Therefore, implementers must be aware that external XML entities 3764 should be treated as untrustworthy. 3766 There is also the scalability risk that would accompany a widely 3767 deployed application which made use of external XML entities. In 3768 this situation, it is possible that there would be significant 3769 numbers of requests for one external XML entity, potentially 3770 overloading any server which fields requests for the resource 3771 containing the external XML entity. 3773 17.8 Risks Connected with Lock Tokens 3775 This specification, in section 6.4, requires the use of Globally 3776 Unique Identifiers (GUIDs) for lock tokens, in order to guarantee 3777 their uniqueness across space and time. GUIDs, as defined in [ISO- 3778 11578], contain a "node" field which "consists of the IEEE address, 3779 usually the host address. For systems with multiple IEEE 802 nodes, 3780 any available node address can be used." Since a WebDAV server will 3781 issue many locks over its lifetime, the implication is that it will 3782 also be publicly exposing its IEEE 802 address. 3784 There are several risks associated with exposure of IEEE 802 3785 addresses. Using the IEEE 802 address: 3787 * It is possible to track the movement of hardware from subnet to 3788 subnet. 3790 * It may be possible to identify the manufacturer of the hardware 3791 running a WebDAV server. 3793 * It may be possible to determine the number of each type of 3794 computer running WebDAV. 3795 Section 6.4.1 of this specification details an alternate mechanism 3796 for generating the "node" field of a GUID without using an IEEE 802 3797 address, which alleviates the risks associated with exposure of IEEE 3798 802 addresses by using an alternate source of uniqueness. 3800 18 IANA Considerations 3802 This document defines two namespaces, the namespace of property 3803 names, and the namespace of WebDAV-specific XML elements used within 3804 property values. 3806 URLs are used for both names, for several reasons. Assignment of a 3807 URL does not require a request to a central naming authority, and 3808 hence allow WebDAV property names and XML elements to be quickly 3809 defined by any WebDAV user or application. URLs also provide a 3810 unique address space, ensuring that the distributed users of WebDAV 3811 will not have collisions among the property names and XML elements 3812 they create. 3814 This specification defines a distinguished set of property names and 3815 XML elements that are understood by all WebDAV applications. The 3816 property names and XML elements in this specification are all 3817 derived from the base URI DAV: by adding a suffix to this URI, for 3818 example, DAV:creationdate for the "creationdate" property. 3820 This specification also defines a URI scheme for the encoding of 3821 lock tokens, the opaquelocktoken URI scheme described in section 3822 6.4. 3824 To ensure correct interoperation based on this specification, IANA 3825 must reserve the URI namespaces starting with "DAV:" and with 3826 "opaquelocktoken:" for use by this specification, its revisions, and 3827 related WebDAV specifications. 3829 19 Copyright 3831 The following copyright notice is copied from RFC 2026 [RFC2026], 3832 section 10.4, and describes the applicable copyright for this 3833 document. 3835 Copyright (C) The Internet Society 1998. All Rights Reserved. 3837 This document and translations of it may be copied and furnished to 3838 others, and derivative works that comment on or otherwise explain it 3839 or assist in its implementation may be prepared, copied, published 3840 and distributed, in whole or in part, without restriction of any 3841 kind, provided that the above copyright notice and this paragraph 3842 are included on all such copies and derivative works. However, this 3843 document itself may not be modified in any way, such as by removing 3844 the copyright notice or references to the Internet Society or other 3845 Internet organizations, except as needed for the purpose of 3846 developing Internet standards in which case the procedures for 3847 copyrights defined in the Internet Standards process must be 3848 followed, or as required to translate it into languages other than 3849 English. 3851 The limited permissions granted above are perpetual and will not be 3852 revoked by the Internet Society or its successors or assignees. 3854 This document and the information contained herein is provided on an 3855 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3856 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3857 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3858 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3859 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3861 20 Intellectual Property 3863 The following notice is copied from RFC 2026 [RFC2026], section 3864 10.4, and describes the position of the IETF concerning intellectual 3865 property claims made against this document. 3867 The IETF takes no position regarding the validity or scope of any 3868 intellectual property or other rights that might be claimed to 3869 pertain to the implementation or use other technology described in 3870 this document or the extent to which any license under such rights 3871 might or might not be available; neither does it represent that it 3872 has made any effort to identify any such rights. Information on the 3873 IETF's procedures with respect to rights in standards-track and 3874 standards-related documentation can be found in BCP-11. Copies of 3875 claims of rights made available for publication and any assurances 3876 of licenses to be made available, or the result of an attempt made 3877 to obtain a general license or permission for the use of such 3878 proprietary rights by implementors or users of this specification 3879 can be obtained from the IETF Secretariat. 3881 The IETF invites any interested party to bring to its attention any 3882 copyrights, patents or patent applications, or other proprietary 3883 rights which may cover technology that may be required to practice 3884 this standard. Please address the information to the IETF Executive 3885 Director. 3887 21 Acknowledgements 3889 A specification such as this thrives on piercing critical review and 3890 withers from apathetic neglect. The authors gratefully acknowledge 3891 the contributions of the following people, whose insights were so 3892 valuable at every stage of our work. 3894 Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan 3895 Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners- 3896 Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith 3897 Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee 3898 Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan 3899 Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis 3900 Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van 3901 der Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, 3902 Steven Martin, Larry Masinter, Michael Mealling, Keith Moore, Henrik 3903 Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff, Saveen 3904 Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike 3905 Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji 3906 Takahashi, Richard N. Taylor, Robert Thau, John Turner, Sankar 3907 Virdhagriswaran, Fabio Vitali, Gregory Woodhouse, and Lauren Wood. 3909 Two from this list deserve special mention. The contributions by 3910 Larry Masinter have been invaluable, both in helping the formation 3911 of the working group and in patiently coaching the authors along the 3912 way. In so many ways he has set high standards we have toiled to 3913 meet. The contributions of Judith Slein in clarifying the 3914 requirements, and in patiently reviewing draft after draft, both 3915 improved this specification and expanded our minds on document 3916 management. 3918 We would also like to thank John Turner for developing the XML DTD. 3920 22 References 3922 22.1 Normative References 3924 [RFC1766] H. T. Alvestrand, "Tags for the Identification of 3925 Languages." RFC 1766. Uninett. March, 1995. 3927 [RFC2277] H. T. Alvestrand, "IETF Policy on Character Sets and 3928 Languages." RFC 2277, BCP 18. Uninett. January, 1998. 3930 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate 3931 Requirement Levels." RFC 2119, BCP 14. Harvard 3932 University. March, 1997. 3934 [RFC2396] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform 3935 Resource Identifiers (URI): Generic Syntax." RFC 2396. 3936 MIT/LCS, U.C. Irvine, Xerox. August, 1998. 3938 [REC-XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen, "Extensible 3939 Markup Language (XML)." World Wide Web Consortium 3940 Recommendation REC-xml-19980210. 3941 http://www.w3.org/TR/1998/REC-xml-19980210. 3943 [RFC2069] J. Franks, P. Hallam-Baker, J. Hostetler, P. Leach, A. 3944 Luotonen, E. Sink, and L. Stewart. "An Extension to HTTP : 3945 Digest Access Authentication" RFC 2069. Northwestern 3946 University, CERN, Spyglass Inc., Microsoft Corp., Netscape 3947 Communications Corp., Spyglass Inc., Open Market Inc. 3948 January 1997. 3950 [RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners- 3951 Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. 3952 U.C. Irvine, DEC, MIT/LCS. January, 1997. 3954 [ISO-639] ISO (International Organization for Standardization). ISO 3955 639:1988. "Code for the representation of names of 3956 languages." 3958 [ISO-8601] ISO (International Organization for Standardization). ISO 3959 8601:1988. "Data elements and interchange formats - 3960 Information interchange - Representation of dates and 3961 times." 3963 [ISO-11578] ISO (International Organization for Standardization). 3964 ISO/IEC 11578:1996. "Information technology - Open Systems 3965 Interconnection - Remote Procedure Call (RPC)" 3967 [UTF-8] F. Yergeau, "UTF-8, a transformation format of Unicode and 3968 ISO 10646." RFC 2279. Alis Technologies. January, 1998. 3970 22.2 Informational References 3972 [RFC2026] S. Bradner, "The Internet Standards Process - Revision 3." 3973 RFC 2026, BCP 9. Harvard University. October, 1996. 3975 [WD-XML-NAMES] T. Bray, D. Hollander, A. Layman, "Name Spaces in 3976 XML" World Wide Web Consortium Working Draft, 3977 http://www.w3.org/TR/WD-xml-names. 3979 [RFC1807] R. Lasher, D. Cohen, "A Format for Bibliographic Records," 3980 RFC 1807. Stanford, Myricom. June, 1995. 3982 [USMARC] Network Development and MARC Standards, Office, ed. 1994. 3983 "USMARC Format for Bibliographic Data", 1994. Washington, 3984 DC: Cataloging Distribution Service, Library of Congress. 3986 [REC-PICS] J. Miller, T. Krauskopf, P. Resnick, W. Treese, "PICS 3987 Label Distribution Label Syntax and Communication 3988 Protocols" Version 1.1, World Wide Web Consortium 3989 Recommendation REC-PICS-labels-961031. 3990 http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html. 3992 [RFC2291] J. A. Slein, F. Vitali, E. J. Whitehead, Jr., D. Durand, 3993 "Requirements for Distributed Authoring and Versioning 3994 Protocol for the World Wide Web." RFC 2291. Xerox, Univ. 3995 of Bologna, U.C. Irvine, Boston Univ. February, 1998. 3997 [RFC2413] S. Weibel, J. Kunze, C. Lagoze, M. Wolf, "Dublin Core 3998 Metadata for Resource Discovery." RFC 2413. OCLC, UCSF, 3999 Cornell, Reuters. September, 1998. 4001 [RFC2376] E. Whitehead, M. Murata, "XML Media Types." RFC 2376. U.C. 4002 Irvine, Fuji Xerox Info. Systems. July 1998. 4004 23 Authors' Addresses 4006 Y. Y. Goland 4007 Microsoft Corporation 4008 One Microsoft Way 4009 Redmond, WA 98052-6399 4010 Email: yarong@microsoft.com 4012 E. J. Whitehead, Jr. 4013 Dept. Of Information and Computer Science 4014 University of California, Irvine 4015 Irvine, CA 92697-3425 4016 Email: ejw@ics.uci.edu 4018 A. Faizi 4019 Netscape 4020 685 East Middlefield Road 4021 Mountain View, CA 94043 4022 Email: asad@netscape.com 4024 S. R. Carter 4025 Novell 4026 1555 N. Technology Way 4027 M/S ORM F111 4028 Orem, UT 84097-2399 4029 Email: srcarter@novell.com 4031 D. Jensen 4032 Novell 4033 1555 N. Technology Way 4034 M/S ORM F111 4035 Orem, UT 84097-2399 4036 Email: dcjensen@novell.com 4038 24 Appendices 4040 24.1 Appendix 1 - WebDAV Document Type Definition 4042 This section provides a document type definition, following the 4043 rules in [REC-XML], for the XML elements used in the protocol stream 4044 and in the values of properties. It collects the element definitions 4045 given in sections 12 and 13. 4047 4051 4054 4055 4057 4058 4060 4061 4062 4064 4066 4068 4070 4072 4074 4075 4076 4078 4080 4082 4083 4084 4086 4088 4089 4090 4092 4093 4094 4096 4097 4098 4100 4102 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 ]> 4117 24.2 Appendix 2 - ISO 8601 Date and Time Profile 4119 The creationdate property specifies the use of the ISO 8601 date 4120 format [ISO-8601]. This section defines a profile of the ISO 8601 4121 date format for use with this specification. This profile is quoted 4122 verbatim from draft-newman-datetime-01.txt (expired). 4124 date-time = full-date "T" full-time 4126 full-date = date-fullyear "-" date-month "-" date-mday 4127 full-time = partial-time time-offset 4129 date-fullyear = 4DIGIT 4130 date-month = 2DIGIT ; 01-12 4131 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on 4132 month/year 4133 time-hour = 2DIGIT ; 00-23 4134 time-minute = 2DIGIT ; 00-59 4135 time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules 4136 time-secfrac = "." 1*DIGIT 4137 time-numoffset = ("+" / "-") time-hour ":" time-minute 4138 time-offset = "Z" / time-numoffset 4140 partial-time = time-hour ":" time-minute ":" time-second 4141 [time-secfrac] 4143 Numeric offsets are calculated as local time minus UTC (Coordinated 4144 Universal Time). So the equivalent time in UTC can be determined by 4145 subtracting the offset from the local time. For example, 18:50:00- 4146 04:00 is the same time as 22:58:00Z. 4148 If the time in UTC is known, but the offset to local time is 4149 unknown, this can be represented with an offset of "-00:00". This 4150 differs from an offset of "Z" which implies that UTC is the 4151 preferred reference point for the specified time. 4153 24.3 Appendix 3 - Notes on Processing XML Elements 4155 24.3.1 Notes on Empty XML Elements 4157 XML supports two mechanisms for indicating that an XML element does 4158 not have any content. The first is to declare an XML element of the 4159 form . The second is to declare an XML element of the form 4160 . The two XML elements are semantically identical. 4162 It is a violation of the XML specification to use the form 4163 if the associated DTD declares the element to be EMPTY (e.g., 4164 ). If such a statement is included, then the 4165 empty element format, must be used. If the element is not 4166 delcared to be EMPTY, then either form or may be used 4167 for empty elements. 4169 24.3.2 Notes on Illegal XML Processing 4171 XML is a flexible data format that makes it easy to submit data that 4172 appears legal but in fact is not. The philosophy of "Be flexible in 4173 what you accept and strict in what you send" still applies, but it 4174 must not be applied inappropriately. XML is extremely flexible in 4175 dealing with issues of white space, element ordering, inserting new 4176 elements, etc. This flexibility does not require extension, 4177 especially not in the area of the meaning of elements. 4179 There is no kindness in accepting illegal combinations of XML 4180 elements. At best it will cause an unwanted result and at worst it 4181 can cause real damage. 4183 24.3.2.1 Example - XML Syntax Error 4185 The following request body for a PROPFIND method is illegal. 4187 4188 4189 4190 4191 4192 The definition of the propfind element only allows for the allprop 4193 or the propname element, not both. Thus the above is an error and 4194 must be responded to with a 400 (Bad Request). 4196 Imagine, however, that a server wanted to be "kind" and decided to 4197 pick the allprop element as the true element and respond to it. A 4198 client running over a bandwidth limited line who intended to execute 4199 a propname would be in for a big surprise if the server treated the 4200 command as an allprop. 4202 Additionally, if a server were lenient and decided to reply to this 4203 request, the results would vary randomly from server to server, with 4204 some servers executing the allprop directive, and others executing 4205 the propname directive. This reduces interoperability rather than 4206 increasing it. 4208 24.3.2.2 Example - Unknown XML Element 4210 The previous example was illegal because it contained two elements 4211 that were explicitly banned from appearing together in the propfind 4212 element. However, XML is an extensible language, so one can imagine 4213 new elements being defined for use with propfind. Below is the 4214 request body of a PROPFIND and, like the previous example, must be 4215 rejected with a 400 (Bad Request) by a server that does not 4216 understand the expired-props element. 4218 4219 4221 4222 4224 To understand why a 400 (Bad Request) is returned let us look at the 4225 request body as the server unfamiliar with expired-props sees it. 4227 4228 4230 4232 As the server does not understand the expired-props element, 4233 according to the WebDAV-specific XML processing rules specified in 4234 section 14, it must ignore it. Thus the server sees an empty 4235 propfind, which by the definition of the propfind element is 4236 illegal. 4238 Please note that had the extension been additive it would not 4239 necessarily have resulted in a 400 (Bad Request). For example, 4240 imagine the following request body for a PROPFIND: 4242 4243 4245 4246 *boss* 4247 4249 The previous example contains the fictitious element leave-out. Its 4250 purpose is to prevent the return of any property whose name matches 4251 the submitted pattern. If the previous example were submitted to a 4252 server unfamiliar with leave-out, the only result would be that the 4253 leave-out element would be ignored and a propname would be executed. 4255 24.4 Appendix 4 -- XML Namespaces for WebDAV 4257 24.4.1 Introduction 4259 To provide a unique space of XML element names which has 4260 decentralized extensibility, this specification uses a feature of 4261 XML known as XML "namespaces". This appendix provides a normative 4262 reference for XML namespace functionality for implementations of 4263 this specification. All DAV compliant systems MUST support the XML 4264 namespace extension as specified in this appendix. 4266 The remainder of this appendix is intended to match, as closely as 4267 needed, the text in WD-xml-names-19980916, "Namespaces in XML", 4268 edited by Tim Bray, Dave Hollander, and Andrew Layman [WD-XML- 4269 NAMES]. To meet this goal, the text in this appendix is mostly 4270 quoted verbatim from sections 1-6 of that source. However, some 4271 minor changes were made, specifically to make the references match 4272 the style of this document, and a forward reference to appendix A 4273 (non-normative) of [REC-XML] was removed, as no appendices of [REC- 4274 XML] are duplicated here. 4276 24.4.2 Motivation and Summary 4278 We envision applications of Extensible Markup Language (XML) where a 4279 single XML document may contain elements and attributes that are 4280 defined for and used by multiple software modules. One motivation 4281 for this is modularity; if such a markup vocabulary exists which is 4282 well-understood and for which there is useful software available, it 4283 is better to re-use this markup rather than re-invent it. 4285 Such documents, containing multiple markup vocabularies, pose 4286 problems of recognition and collision. Software modules need to be 4287 able to recognize the tags and attributes which they are designed to 4288 process, even in the face of "collisions" occurring when markup 4289 intended for some other software package uses the same element type 4290 or attribute name. 4292 These considerations require that document constructs should have 4293 universal names, whose scope extends beyond their containing 4294 document. This specification describes a mechanism, XML namespaces, 4295 which accomplishes this. 4297 [Definition:] An XML namespace is a collection of names, identified 4298 by a URI, which are used in XML documents as element types and 4299 attribute names. XML namespaces differ from the "namespaces" 4300 conventionally used in computing disciplines in that the XML version 4301 has internal structure and is not, mathematically speaking, a set. 4303 Names from XML namespaces may appear as qualified names, which 4304 contain a single colon, separating the name into a namespace prefix 4305 and a local part. The prefix, which is mapped to a URI [RFC2396], 4306 selects a namespace. The combination of the universally managed URI 4307 namespace and the document's own namespace produces identifiers that 4308 are universally unique. Mechanisms are provided for prefix scoping 4309 and defaulting to avoid clutter and improve readability. 4311 URIs can contain characters not allowed in names, so cannot be used 4312 directly as namespace prefixes. Therefore, the namespace prefix 4313 serves as a proxy for a URI. An attribute-based syntax described 4314 below is used to declare the association of the namespace prefix 4315 with a URI; software which supports this namespace proposal must 4316 recognize and act on these declarations and prefixes. 4318 24.4.3 Declaring Namespaces 4320 Note that many of the nonterminals in the productions in section 24 4321 of this specification are defined not here but in the XML 4322 specification [REC-XML]. When nonterminals defined here have the 4323 same names as nonterminals defined in the XML specification, the 4324 productions here in all cases match a subset of the strings matched 4325 by the corresponding ones there. 4327 [Definition:] A namespace is declared using an attribute whose 4328 prefix is xmlns as follows: 4330 Namespace declaration using attributes 4332 [1] NSDecl ::= PrefixDef Eq AttValue [ NSC: Empty URI ] 4333 [2] PrefixDef ::= 'xmlns' (':' NCName)? [ NSC: Leading "XML" ] 4334 [3] NCName ::= (Letter | '_') (NCNameChar)* /* An XML Name, 4335 minus the ":" */ 4336 [4] NCNameChar ::= Letter | Digit | '.' | '-' | '_' | 4337 CombiningChar | Extender 4339 [Definition:] The AttValue in the NSDecl production is a URI which 4340 functions as a namespace name to identify the namespace. The 4341 namespace name, to serve its intended purpose, should have the 4342 characteristics of uniqueness and persistence. It is not a goal that 4343 it be directly usable for retrieval of a schema (if any exists). An 4344 example of a syntax that is designed with these goals in mind is 4345 that for Uniform Resource Names [RFC2141]. However, it should be 4346 noted that ordinary URLs can be managed in such a way as to achieve 4347 these same goals. 4349 [Definition:] In the PrefixDef production, if the optional colon and 4350 NCName are provided, then that NCName gives the namespace prefix, 4351 used to associate names with this namespace in the scope of the 4352 element to which the declaration is attached. 4354 [Definition:] If the colon and NCName are not provided, then the 4355 associated namespace name is that of the default namespace in the 4356 scope of the element to which the declaration is attached. 4358 Namespace Constraint: Empty URI 4359 The AttValue may be empty only if the PrefixDef is simply xmlns, 4360 i.e. is declaring a default namespace. Default namespaces and 4361 overriding of declarations are discussed in "5. Applying Namespaces 4362 to Elements and Attributes". 4364 Namespace Constraint: Leading "XML" 4365 Prefixes beginning with the three-letter sequence x, m, l, in any 4366 case combination, are reserved for use by XML and XML-related 4367 specifications. 4369 An example namespace declaration: 4371 4372 4373 4464 4465 Frobnostication 4466 Moved to 4467 here. 4468 4469 4471 Multiple namespace prefixes can be declared as attributes of a 4472 single element, as shown in this example: 4474 4475 4476 4478 Cheaper by the Dozen 4479 1568491379 4480 4482 24.4.6.2 Namespace Defaulting 4484 A default namespace is considered to apply to the element where it 4485 is declared (if that element has no namespace prefix), and to all 4486 elements with no prefix within the content of that element. If the 4487 URI in a default namespace declaration is empty, then unprefixed 4488 elements in the scope of the declaration are not considered to be in 4489 any namespace. Note that default namespaces do not apply directly to 4490 attributes. 4492 4493 4503 4505 Cheaper by the Dozen 4506 1568491379 4507 4509 A larger example of namespace scoping: 4511 4512 4513 4515 Cheaper by the Dozen 4516 1568491379 4517 4518 4519

4520 This is a funny book! 4521

4522 4523 4524 The default namespace, once declared, may be overridden: 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4541 4542
NameOriginDescription
HuntsmanBath, UK 4536
BitterFuggles 4537 Wonderful hop, light alcohol, good summer beer 4538 Fragile; excessive variance pub to pub 4539
4540
4543 4545 24.4.7 Uniqueness of Attributes 4547 In XML documents conforming to this specification, no start-tag may 4548 contain two attributes which: 4550 1. have identical names, or 4551 2. have qualified names with the same local part and with prefixes 4552 which have been bound to namespace names which are lexically 4553 equivalent. Note that namespace names are URIs, the governing RFCs 4554 for which contain rules for establishing lexical equivalence. 4556 For example, each of the bad start-tags is illegal in the following: 4558 4559 4561 4562 4563 4565 However, each of the following is legal: 4567 4568 4570 4571 4572 4574 24.4.8 Conformance 4576 In XML documents which conform to this specification, element types 4577 and attribute names must match the production either for NSDecl or 4578 QName and must satisfy the "Namespace Constraints". 4580 An XML document conforms to this specification if all other tokens 4581 in the document which are required, for XML conformance, to match 4582 the XML production for Name, match this specification's production 4583 for NCName. 4585 The effect of conformance is that in such a document: 4587 * All element types and attribute names contain either zero or one 4588 colon. 4590 * No entity names, PI targets, or notation names contain any colons. 4592 Strictly speaking, attribute values declared to be of types ID, 4593 IDREF(S), ENTITY(IES), and NOTATION are also Names, and thus should 4594 be colon-free. However, the declared type of attribute values is in 4595 principle only available in documents which have been validated. 4596 Thus, in well-formed XML documents, there can be no assurance that 4597 the contents of attribute values have been checked for conformance 4598 to this specification. 4600 24.4.9 Meaning of Qualified Names 4602 [Note to the reader: This section does not appear in [WD-XML-NAMES], 4603 but is necessary to avoid ambiguity for WebDAV XML processors.] 4605 WebDAV compliant XML processors MUST interpret a qualified name as a 4606 URI constructed by appending the LocalPart to the namespace name 4607 URI. 4609 Example 4611 4612 4613 Johnny Updraft 4614 4615 4616 4617 In this example, the qualified element name "del:glider" is 4618 interpreted as the URL "http://www.del.jensen.org/glider". 4620 4621 4622 Johnny Updraft 4623 4624 4625 4627 Even though this example is syntactically different from the 4628 previous example, it is semantically identical. Each instance of 4629 the namespace name "bar" is replaced with 4630 "http://www.del.jensen.org/" and then appended to the local name for 4631 each element tag. The resulting tag names in this example are 4632 exactly the same as for the previous example. 4634 4635 4636 Johnny Updraft 4637 4638 4639 4641 This example is semantically identical to the two previous ones. 4642 Each instance of the namespace name "foo" is replaced with 4643 "http://www.del.jensen.org/glide" which is then appended to the 4644 local name for each element tag, the resulting tag names are 4645 identical to those in the previous examples.