idnits 2.17.1 draft-ietf-webdav-protocol-08.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 12 longer pages, the longest (page 14) being 59 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 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 (April 7, 1998) is 9509 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 401, but not defined == Missing Reference: 'Extension' is mentioned on line 732, but not defined == Missing Reference: 'Spreberg-McQueen' is mentioned on line 4055, but not defined == Missing Reference: '1' is mentioned on line 4076, but not defined == Missing Reference: '2' is mentioned on line 4078, but not defined == Missing Reference: '3' is mentioned on line 4079, but not defined == Missing Reference: '4' is mentioned on line 4080, but not defined == Missing Reference: '5' is mentioned on line 4081, but not defined == Missing Reference: '6' is mentioned on line 4083, but not defined == Missing Reference: '7' is mentioned on line 4135, but not defined == Missing Reference: '8' is mentioned on line 4155, but not defined == Missing Reference: '9' is mentioned on line 4156, but not defined == Missing Reference: '10' is mentioned on line 4157, but not defined == Missing Reference: 'XML' is mentioned on line 4190, but not defined == Missing Reference: '11' is mentioned on line 4195, but not defined == Missing Reference: '12' is mentioned on line 4196, but not defined == Missing Reference: '13' is mentioned on line 4197, but not defined == Missing Reference: '15' is mentioned on line 4205, but not defined == Unused Reference: 'Hollander' is defined on line 3752, but no explicit reference was found in the text == Unused Reference: 'Layman' is defined on line 3752, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1807 (ref. '1995') -- Possible downref: Non-RFC (?) normative reference: ref. '1998' -- Possible downref: Non-RFC (?) normative reference: ref. 'Bray' -- Possible downref: Non-RFC (?) normative reference: ref. 'Paoli' -- Possible downref: Non-RFC (?) normative reference: ref. 'Sperberg-McQueen' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-639' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-8601' -- Possible downref: Non-RFC (?) normative reference: ref. 'Leach' -- Possible downref: Non-RFC (?) normative reference: ref. 'Salz' ** Obsolete normative reference: RFC 2279 (ref. 'Yergeau') (Obsoleted by RFC 3629) -- Duplicate reference: RFC2026, mentioned in '1996', was also mentioned in 'Bradner'. -- Duplicate reference: RFC1807, mentioned in 'Lasher', was also mentioned in '1995'. -- Duplicate reference: RFC1807, mentioned in 'Cohen', was also mentioned in 'Lasher'. Summary: 8 errors (**), 0 flaws (~~), 24 warnings (==), 14 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 April 7, 1998 8 Extensions for Distributed Authoring on the World Wide Web -- WEBDAV 10 Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, 14 and its working groups. Note that other groups may also distribute 15 working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or made obsolete by other 19 documents at any time. It is inappropriate to use Internet-Drafts as 20 reference material or to cite them other than as "work in progress". 22 To view the entire list of current Internet-Drafts, please check 23 the "1id-abstracts.txt" listing contained in the Internet-Drafts 24 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 25 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 26 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 27 (US West Coast). 29 Distribution of this document is unlimited. Please send comments to 30 the Distributed Authoring and Versioning (WEBDAV) working group at 31 , which may be joined by sending a message 32 with subject "subscribe" to . 34 Discussions of the WEBDAV working group are archived at 35 . 37 Abstract 39 This document specifies a set of methods, headers, and content-types 40 ancillary to HTTP/1.1 for the management of resource properties, 41 creation and management of resource collections, namespace 42 manipulation, and resource locking (collision avoidance). 44 Contents 46 STATUS OF THIS MEMO ..................................................1 47 ABSTRACT .............................................................1 48 CONTENTS .............................................................2 50 1 INTRODUCTION .......................................................7 52 2 NOTATIONAL CONVENTIONS .............................................8 54 3 DATA MODEL FOR RESOURCE PROPERTIES .................................8 55 3.1 The Resource Property Model .....................................8 56 3.2 Existing Metadata Proposals .....................................9 57 3.3 Properties and HTTP Headers ....................................10 58 3.4 Property Values ................................................10 59 3.5 Property Names .................................................10 60 3.6 Media Independent Links ........................................11 62 4 COLLECTIONS OF WEB RESOURCES ......................................11 63 4.1 Collection Resources ...........................................11 64 4.2 Creation and Retrieval of Collection Resources .................12 65 4.3 HTTP URL Namespace Model .......................................12 66 4.4 Source Resources and Output Resources ..........................12 68 5 LOCKING ...........................................................13 69 5.1 Exclusive Vs. Shared Locks .....................................14 70 5.2 Required Support ...............................................15 71 5.3 Lock Tokens ....................................................15 72 5.4 opaquelocktoken Lock Token URI Scheme ..........................15 73 5.5 Lock Capability Discovery ......................................16 74 5.6 Active Lock Discovery ..........................................16 75 5.7 Usage Considerations ...........................................16 77 6 WRITE LOCK ........................................................17 78 6.1 Methods Restricted by Write Locks ..............................17 79 6.2 Write Locks and Properties .....................................18 80 6.3 Write Locks and Null Resources .................................18 81 6.4 Write Locks and Collections ....................................18 82 6.5 Write Locks and the If Request Header ..........................19 83 6.5.1 Example - Write Lock .........................................19 84 6.6 Write Locks and COPY/MOVE ......................................20 85 6.7 Refreshing Write Locks .........................................20 87 7 HTTP METHODS FOR DISTRIBUTED AUTHORING ............................20 88 7.1 PROPFIND .......................................................21 89 7.1.1 Example - Retrieving Named Properties ........................22 90 7.1.2 Example - Using allprop to Retrieve All Properties ...........23 91 7.1.3 Example - Using propname to Retrieve all Property Names ......25 92 7.2 PROPPATCH ......................................................27 93 7.2.1 Status Codes for use with Multi-Status .......................27 94 7.2.2 Example - PROPPATCH ..........................................28 95 7.3 MKCOL Method ...................................................29 96 7.3.1 Request ......................................................29 97 7.3.2 Response Codes ...............................................30 98 7.3.3 Example - MKCOL ..............................................30 99 7.4 GET, HEAD for Collections ......................................31 101 7.5 POST for Collections ...........................................31 103 7.6 DELETE .........................................................31 104 7.6.1 DELETE for Non-Collection Resources ..........................31 105 7.6.2 DELETE for Collections .......................................31 107 7.7 PUT ............................................................32 108 7.7.1 PUT for Non-Collection Resources .............................32 109 7.7.2 PUT for Collections ..........................................33 111 7.8 COPY Method ....................................................33 112 7.8.1 COPY for HTTP/1.1 resources ..................................33 113 7.8.2 COPY for Properties ..........................................34 114 7.8.3 COPY for Collections .........................................34 115 7.8.4 COPY and the Overwrite Header ................................35 116 7.8.5 Status Codes .................................................35 117 7.8.6 Example - COPY with Overwrite ................................36 118 7.8.7 Example - COPY with No Overwrite .............................36 119 7.8.8 Example - COPY of a Collection ...............................36 121 7.9 MOVE Method ....................................................37 122 7.9.1 MOVE for Properties ..........................................37 123 7.9.2 MOVE for Collections .........................................38 124 7.9.3 MOVE and the Overwrite Header ................................38 125 7.9.4 Status Codes .................................................39 126 7.9.5 Example - MOVE of a Non-Collection ...........................39 127 7.9.6 Example - MOVE of a Collection ...............................39 129 7.10 LOCK Method ...................................................40 130 7.10.1 Operation ...................................................40 131 7.10.2 The Effect of Locks on Properties and Collections ...........41 132 7.10.3 Locking Replicated Resources ................................41 133 7.10.4 Depth and Locking ...........................................41 134 7.10.5 Interaction with other Methods ..............................42 135 7.10.6 Lock Compatibility Table ....................................42 136 7.10.7 Status Codes ................................................42 137 7.10.8 Example - Simple Lock Request ...............................43 138 7.10.9 Example - Refreshing a Write Lock ...........................44 139 7.10.10 Example - Multi-Resource Lock Request ......................45 141 7.11 UNLOCK Method .................................................46 142 7.11.1 Example - UNLOCK ............................................46 144 8 HTTP HEADERS FOR DISTRIBUTED AUTHORING ............................47 145 8.1 DAV Header .....................................................47 146 8.2 Depth Header ...................................................47 147 8.3 Destination Header .............................................48 148 8.4 If Header ......................................................48 149 8.4.1 No-tag-list Production .......................................49 150 8.4.2 Tagged-list Production .......................................49 151 8.4.3 not Production ...............................................50 152 8.4.4 Matching Function ............................................50 153 8.4.5 If Header and Non-DAV Compliant Proxies ......................51 154 8.5 Lock-Token Request Header ......................................51 155 8.6 Overwrite Header ...............................................51 156 8.7 Status-URI Response Header .....................................51 157 8.8 Timeout Request Header .........................................52 159 9 STATUS CODE EXTENSIONS TO HTTP/1.1 ................................53 160 9.1 102 Processing .................................................53 161 9.2 207 Multi-Status ...............................................53 162 9.3 422 Unprocessable Entity .......................................53 163 9.4 423 Locked .....................................................53 164 9.5 424 Method Failure .............................................53 165 9.6 425 Insufficient Space on Resource .............................53 167 10 MULTI-STATUS RESPONSE ............................................54 169 11 XML ELEMENT DEFINITIONS ..........................................54 170 11.1 activelock XML Element ........................................54 171 11.1.1 depth XML Element ...........................................54 172 11.1.2 locktoken XML Element .......................................54 173 11.1.3 timeout XML Element .........................................54 174 11.2 collection XML Element ........................................55 175 11.3 href XML Element ..............................................55 176 11.4 link XML Element ..............................................55 177 11.4.1 dst XML Element .............................................55 178 11.4.2 src XML Element .............................................55 179 11.5 lockentry XML Element .........................................56 180 11.6 lockinfo XML Element ..........................................56 181 11.7 lockscope XML Element .........................................56 182 11.7.1 exclusive XML Element .......................................56 183 11.7.2 shared XML Element ..........................................56 184 11.8 locktype XML Element ..........................................56 185 11.8.1 write XML Element ...........................................57 186 11.9 multistatus XML Element .......................................57 187 11.9.1 response XML Element ........................................57 188 11.9.2 responsedescription XML Element .............................58 189 11.10 owner XML Element ............................................58 190 11.11 prop XML element .............................................58 191 11.12 propertybehavior XML element .................................59 192 11.12.1 keepalive XML element ......................................59 193 11.12.2 omit XML element ...........................................59 194 11.13 propertyupdate XML element ...................................60 195 11.13.1 remove XML element .........................................60 196 11.13.2 set XML element ............................................60 197 11.14 propfind XML Element .........................................60 198 11.14.1 allprop XML Element ........................................61 199 11.14.2 propname XML Element .......................................61 201 12 DAV PROPERTIES ...................................................61 202 12.1 creationdate Property .........................................61 203 12.2 displayname Property ..........................................61 204 12.3 getcontentlanguage Property ...................................62 205 12.4 getcontentlength Property .....................................62 206 12.5 getcontenttype Property .......................................62 207 12.6 getetag Property ..............................................62 208 12.7 getlastmodified Property ......................................63 209 12.8 lockdiscovery Property ........................................63 210 12.8.1 Example - Retrieving the lockdiscovery Property .............63 211 12.9 resourcetype Property .........................................64 212 12.10 source Property ..............................................65 213 12.10.1 Example - A source Property ................................65 214 12.11 supportedlock Property .......................................66 215 12.11.1 Example - Retrieving the supportedlock Property ............66 217 13 DAV XML PROCESSING INSTRUCTIONS ..................................67 219 14 DAV COMPLIANCE CLASSES ...........................................67 220 14.1 Class 1 .......................................................68 221 14.2 Class 2 .......................................................68 223 15 INTERNATIONALIZATION CONSIDERATIONS ..............................68 225 16 SECURITY CONSIDERATIONS ..........................................69 226 16.1 Authentication of Clients .....................................69 227 16.2 Denial of Service .............................................70 228 16.3 Security through Obscurity ....................................70 229 16.4 Privacy Issues Connected to Locks .............................71 230 16.5 Privacy Issues Connected to Properties ........................71 231 16.6 Reduction of Security due to Source Link ......................71 233 17 IANA CONSIDERATIONS ..............................................71 234 18 TERMINOLOGY ......................................................72 235 19 COPYRIGHT ........................................................73 236 20 INTELLECTUAL PROPERTY ............................................73 237 21 ACKNOWLEDGEMENTS .................................................74 238 22 REFERENCES .......................................................75 239 22.1 Normative References ..........................................75 240 22.2 Informational References ......................................75 241 23 AUTHORS' ADDRESSES ...............................................77 242 24 APPENDICES .......................................................78 243 24.1 Appendix 1 - WebDAV Document Type Definition ..................78 244 24.2 Appendix 2 - ISO 8601 Date and Time Profile ...................79 245 24.3 Appendix 3 - Notes on Processing XML Elements .................80 246 24.3.1 Notes on Empty XML Elements .................................80 247 24.3.2 Notes on Illegal XML Processing .............................80 248 24.4 Appendix 4 -- XML Namespaces for WebDAV .......................82 249 24.4.1 Introduction ................................................82 250 24.4.2 Namespace Declaration PI ....................................83 251 24.4.3 Placing Declarations in Documents ...........................84 252 24.4.4 Prolog with Namespace Declarations ..........................84 253 24.4.5 Qualified Names .............................................84 254 24.4.6 Universal Names .............................................85 255 24.4.7 Using Qualified Names .......................................85 256 24.4.8 Processing instruction ......................................85 257 24.4.9 Scope and Meaning of Qualified Names ........................85 259 1 Introduction 261 This document describes an extension to the HTTP/1.1 protocol that 262 allows clients to perform remote web content authoring operations. 263 This extension provides a coherent set of methods, headers, request 264 entity body formats, and response entity body formats that provide 265 operations for: 267 Properties: The ability to create, remove, and query information 268 about Web pages, such as their authors, creation dates, etc. Also, 269 the ability to link pages of any media type to related pages. 271 Collections: The ability to create sets of related documents and to 272 retrieve a hierarchical membership listing (like a directory listing 273 in a file system). 275 Locking: The ability to keep more than one person from working on a 276 document at the same time. This prevents the "lost update problem," 277 in which modifications are lost as first one author then another 278 writes changes without merging the other author's changes. 280 Namespace Operations: The ability to instruct the server to copy and 281 move Web resources. 283 Requirements and rationale for these operations are described in a 284 companion document, "Requirements for a Distributed Authoring and 285 Versioning Protocol for the World Wide Web" [Slein et al., 1998]. 287 The sections below provide a detailed introduction to resource 288 properties (section 3), collections of resources (section 4), and 289 locking operations (section 5). These sections introduce the 290 abstractions manipulated by the WebDAV-specific HTTP methods 291 described in section 7, "HTTP Methods for Distributed Authoring". 293 In HTTP/1.1, method parameter information was exclusively encoded in 294 HTTP headers. Unlike HTTP/1.1, WebDAV, encodes method parameter 295 information either in an Extensible Markup Language (XML) [Bray, 296 Paoli, Sperberg-McQueen, 1998] request entity body, or in an HTTP 297 header. The use of XML to encode method parameters was motivated by 298 the ability to add extra XML elements to existing structures, 299 providing extensibility, and by XML's ability to encode information 300 in ISO 10646 character sets, providing internationalization support. 301 As a rule of thumb, parameters are encoded in XML entity bodies when 302 they have unbounded length, or when they may be shown to a human 303 user and hence require encoding in an ISO 10646 character set. 304 Otherwise, parameters are encoded within HTTP headers. Section 8 305 describes the new HTTP headers used with WebDAV methods. 307 In addition to encoding method parameters, XML is used in WebDAV to 308 encode the responses from methods, providing the extensibility and 309 internationalization advantages of XML for method output, as well as 310 input. 312 XML elements used in this specification are defined in section 11. 314 The XML namespace extension (Appendix 4) is also used in this 315 specification in order to allow for new XML elements to be added 316 without fear of colliding with other element names. 318 While the status codes provided by HTTP/1.1 are sufficient to 319 describe most error conditions encountered by WebDAV methods, there 320 are some errors that do not fall neatly into the existing 321 categories. New status codes developed for the WebDAV methods are 322 defined in section 9. Since some WebDAV methods may operate over 323 many resources, the Multi-Status response has been introduced to 324 return status information for multiple resources. The Multi-Status 325 response is described in section 10. 327 WebDAV employs the property mechanism to store information about the 328 current state of the resource. For example, when a lock is taken 329 out on a resource, a lock information property describes the current 330 state of the lock. Section 12 defines the properties used within the 331 WebDAV specification. 333 Finishing off the specification are sections on what it means to be 334 compliant with this specification (section 14), on 335 internationalization support (section 15), and on security (section 336 16). 338 2 Notational Conventions 340 Since this document describes a set of extensions to the HTTP/1.1 341 protocol, the augmented BNF used herein to describe protocol 342 elements is exactly the same as described in section 2.1 of 343 [Fielding et al., 1997]. Since this augmented BNF uses the basic 344 production rules provided in section 2.2 of [Fielding et al., 1997], 345 these rules apply to this document as well. 347 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 348 "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 349 document are to be interpreted as described in RFC 2119 [Bradner, 350 1997]. 352 3 Data Model for Resource Properties 354 3.1 The Resource Property Model 356 Properties are pieces of data that describe the state of a resource. 357 Properties are data about data. 359 Properties are used in distributed authoring environments to provide 360 for efficient discovery and management of resources. For example, a 361 'subject' property might allow for the indexing of all resources by 362 their subject, and an 'author' property might allow for the 363 discovery of what authors have written which documents. 365 The DAV property model consists of name/value pairs. The name of a 366 property identifies the property's syntax and semantics, and 367 provides an address by which to refer to its syntax and semantics. 369 There are two categories of properties: "live" and "dead". A live 370 property has its syntax and semantics enforced by the server. Live 371 properties include cases where a) the value of a property is read- 372 only, maintained by the server, and b) the value of the property is 373 maintained by the client, but the server performs syntax checking on 374 submitted values. A dead property has its syntax and semantics 375 enforced by the client; the server merely records the value of the 376 property verbatim. 378 3.2 Existing Metadata Proposals 380 Properties have long played an essential role in the maintenance of 381 large document repositories, and many current proposals contain some 382 notion of a property, or discuss web metadata more generally. These 383 include PICS [Miller et al., 1996], PICS-NG, XML, Web Collections, 384 and several proposals on representing relationships within HTML. 385 Work on PICS-NG and Web Collections has been subsumed by the 386 Resource Definition Framework (RDF) metadata activity of the World 387 Wide Web Consortium. RDF consists of a network-based data model and 388 an XML representation of that model. 390 Some proposals come from a digital library perspective. These 391 include the Dublin Core [Weibel et al., 1995] metadata set and the 392 Warwick Framework [Lagoze, 1996], a container architecture for 393 different metadata schemas. The literature includes many examples 394 of metadata, including MARC [MARC, 1994], a bibliographic metadata 395 format, and RFC 1807 [Lasher, Cohen, 1995], a technical report 396 bibliographic format employed by the Dienst system. Additionally, 397 the proceedings from the first IEEE Metadata conference describe 398 many community-specific metadata sets. 400 Participants of the 1996 Metadata II Workshop in Warwick, UK 401 [Lagoze, 1996], noted that "new metadata sets will develop as the 402 networked infrastructure matures" and "different communities will 403 propose, design, and be responsible for different types of 404 metadata." These observations can be corroborated by noting that 405 many community-specific sets of metadata already exist, and there is 406 significant motivation for the development of new forms of metadata 407 as many communities increasingly make their data available in 408 digital form, requiring a metadata format to assist data location 409 and cataloging. 411 3.3 Properties and HTTP Headers 413 Properties already exist, in a limited sense, in HTTP message 414 headers. However, in distributed authoring environments a 415 relatively large number of properties are needed to describe the 416 state of a resource, and setting/returning them all through HTTP 417 headers is inefficient. Thus a mechanism is needed which allows a 418 principal to identify a set of properties in which the principal is 419 interested and to set or retrieve just those properties. 421 3.4 Property Values 423 The value of a property is, at minimum, well formed XML. 425 XML has been chosen because it is a flexible, self-describing, 426 structured data format that supports rich schema definitions, and 427 because of its support for multiple character sets. XML's self- 428 describing nature allows any property's value to be extended by 429 adding new elements. Older clients will not break when they 430 encounter extensions because they will still have the data specified 431 in the original schema and will ignore elements they do not 432 understand. XML's support for multiple character sets allows any 433 human-readable property to be encoded and read in a character set 434 familiar to the user. 436 3.5 Property Names 438 A property name is a universally unique identifier that is 439 associated with a schema that provides information about the syntax 440 and semantics of the property. 442 Because a property's name is universally unique, clients can depend 443 upon consistent behavior for a particular property across multiple 444 resources, so long as that property is "live" on the resources in 445 question. 447 The XML namespace mechanism, which is based on URIs, is used to name 448 properties because it prevents namespace collisions and provides for 449 varying degrees of administrative control. 451 The property namespace is flat; that is, no hierarchy of properties 452 is explicitly recognized. Thus, if a property A and a property A/B 453 exist on a resource, there is no recognition of any relationship 454 between the two properties. It is expected that a separate 455 specification will eventually be produced which will address issues 456 relating to hierarchical properties. 458 Finally, it is not possible to define the same property twice on a 459 single resource, as this would cause a collision in the resource's 460 property namespace. 462 3.6 Media Independent Links 464 Although HTML resources support links to other resources, the Web 465 needs more general support for links between resources of any media 466 type. WebDAV provides such links. A WebDAV link is a special type 467 of property value, formally defined in section 11.4, that allows 468 typed connections to be established between resources of any media 469 type. The property value consists of source and destination Uniform 470 Resource Locators (URLs); the property name identifies the link 471 type. 473 4 Collections of Web Resources 475 This section provides a description of a new type of Web resource, 476 the collection, and discusses its interactions with the HTTP URL 477 namespace. The purpose of a collection resource is to model 478 collection-like objects (e.g., file system directories) within a 479 server's namespace. 481 All DAV compliant resources MUST support the HTTP URL namespace 482 model specified herein. 484 4.1 Collection Resources 486 A collection is a resource whose state consists of at least a list 487 of internal members and a set of properties, but which may have 488 additional state such as entity bodies returned by GET. An internal 489 member resource MUST have a URI that is immediately relative to the 490 base URI of the collection. That is, the internal member's URI is 491 equal to the parent collection's URI plus an additional segment 492 where segment is defined in section 3.2.1 of RFC 2068 [Fielding et 493 al., 1996]. 495 Any given internal member MUST only belong to the collection once, 496 i.e., it is illegal to have multiple instances of the same URI in a 497 collection. Properties defined on collections behave exactly as do 498 properties on non-collection resources. 500 WebDAV servers MUST treat HTTP URL namespaces as collections, 501 regardless of whether they were created with the MKCOL method 502 described in section 7.3. 504 There is a standing convention that when a collection is referred to 505 by its name without a trailing slash, the trailing slash is 506 automatically appended. Due to this, a resource may accept a URI 507 without a trailing "/" to point to a collection. In this case it 508 SHOULD return a content-location header in the response pointing to 509 the URL ending with the "/". For example, if a client invokes a 510 method on http://foo.bar/blah (no trailing slash), the resource 511 http://foo.bar/blah/ (trailing slash) may respond as if the 512 operation were invoked on it, and should return a content-location 513 header with http://foo.bar/blah/ in it. In general clients SHOULD 514 use the "/" form of collection names. 516 4.2 Creation and Retrieval of Collection Resources 518 This document specifies the MKCOL method to create new collection 519 resources, rather than using the existing HTTP/1.1 PUT or POST 520 method, for the following reasons: 522 In HTTP/1.1, the PUT method is defined to store the request body at 523 the location specified by the Request-URI. While a description 524 format for a collection can readily be constructed for use with PUT, 525 the implications of sending such a description to the server are 526 undesirable. For example, if a description of a collection that 527 omitted some existing resources were PUT to a server, this might be 528 interpreted as a command to remove those members. This would extend 529 PUT to perform DELETE functionality, which is undesirable since it 530 changes the semantics of PUT, and makes it difficult to control 531 DELETE functionality with an access control scheme based on methods. 533 While the POST method is sufficiently open-ended that a "create a 534 collection" POST command could be constructed, this is undesirable 535 because it would be difficult to separate access control for 536 collection creation from other uses of POST. 538 The exact definition of the behavior of GET and PUT on collections 539 is defined later in this document. 541 4.3 HTTP URL Namespace Model 543 The HTTP URL Namespace is a hierarchical namespace where the 544 hierarchy is delimited with the "/" character. DAV compliant 545 resources MUST maintain the consistency of the HTTP URL namespace. 546 For example, if the collection http://www.foo.bar.org/a/ exists, but 547 http://www.foo.bar.org/a/b/ does not exist, an attempt to create 548 http://www.foo.bar.org/a/b/c must fail. 550 4.4 Source Resources and Output Resources 552 For many resources, the entity returned by a GET method exactly 553 matches the persistent state of the resource, for example, a GIF 554 file stored on a disk. For this simple case, the URL at which a 555 resource is accessed is identical to the URL at which the source 556 (the persistent state) of the resource is accessed. This is also 557 the case for HTML source files that are not processed by the server 558 prior to transmission. 560 However, the server can sometimes process HTML resources before they 561 are transmitted as a return entity body. For example, a server- 562 side-include directive within an HTML file might instruct a server 563 to replace the directive with another value, such as the current 564 date. In this case, what is returned by GET (HTML plus date) 565 differs from the persistent state of the resource (HTML plus 566 directive). Typically there is no way to access the HTML resource 567 containing the unprocessed directive. 569 Sometimes the entity returned by GET is the output of a data- 570 producing process that is described by one or more source resources 571 (that may not even have a location in the URL namespace). A single 572 data-producing process may dynamically generate the state of a 573 potentially large number of output resources. An example of this is 574 a CGI script that describes a "finger" gateway process that maps 575 part of the namespace of a server into finger requests, such as 576 http://www.foo.bar.org/finger_gateway/user@host. 578 In the absence of distributed authoring capabilities, it is 579 acceptable to have no mapping of source resource(s) to the URI 580 namespace. In fact, preventing access to the source resource(s) has 581 desirable security benefits. However, if remote editing of the 582 source resource(s) is desired, the source resource(s) should be 583 given a location in the URI namespace. This source location should 584 not be one of the locations at which the generated output is 585 retrievable, since in general it is impossible for the server to 586 differentiate requests for source resources from requests for 587 process output resources. There is often a many-to-many 588 relationship between source resources and output resources. 590 On WebDAV compliant servers the URI of the source resource(s) may be 591 stored in a link on the output resource with type DAV:source (see 592 section 12.10 for a description of the source link property). 593 Storing the source URIs in links on the output resources places the 594 burden of discovering the source on the authoring client. Note that 595 the value of a source link is not guaranteed to point to the correct 596 source. Source links may break or incorrect values may be entered. 597 Also note that not all servers will allow the client to set the 598 source link value. For example a server which generates source 599 links on the fly for its CGI files will most likely not allow a 600 client to set the source link value. 602 5 Locking 604 The ability to lock a resource provides a mechanism for serializing 605 access to that resource. Using a lock, an authoring client can 606 provide a reasonable guarantee that another principal will not 607 modify a resource while it is being edited. In this way, a client 608 can prevent the "lost update" problem. 610 This specification allows locks to vary over two client-specified 611 parameters, the number of principals involved (exclusive vs. shared) 612 and the type of access to be granted. This document defines locking 613 for only one access type, write. However, the syntax is extensible, 614 and permits the eventual specification of locking for other access 615 types. 617 5.1 Exclusive Vs. Shared Locks 619 The most basic form of lock is an exclusive lock. This is a lock 620 where the access right in question is only granted to a single 621 principal. The need for this arbitration results from a desire to 622 avoid having to merge results. 624 However, there are times when the goal of a lock is not to exclude 625 others from exercising an access right but rather to provide a 626 mechanism for principals to indicate that they intend to exercise 627 their access rights. Shared locks are provided for this case. A 628 shared lock allows multiple principals to receive a lock. Hence any 629 principal with appropriate access can get the lock. 631 With shared locks there are two trust sets that affect a resource. 632 The first trust set is created by access permissions. Principals 633 who are trusted, for example, may have permission to write to the 634 resource. Among those who have access permission to write to the 635 resource, the set of principals who have taken out a shared lock 636 also must trust each other, creating a (typically) smaller trust set 637 within the access permission write set. 639 Starting with every possible principal on the Internet, in most 640 situations the vast majority of these principals will not have write 641 access to a given resource. Of the small number who do have write 642 access, some principals may decide to guarantee their edits are free 644 from overwrite conflicts by using exclusive write locks. Others may 645 decide they trust their collaborators will not overwrite their work 646 (the potential set of collaborators being the set of principals who 647 have write permission) and use a shared lock, which informs their 648 collaborators that a principal may be working on the resource. 650 The WebDAV extensions to HTTP do not need to provide all of the 651 communications paths necessary for principals to coordinate their 652 activities. When using shared locks, principals may use any out of 653 band communication channel to coordinate their work (e.g., face-to- 654 face interaction, written notes, post-it notes on the screen, 655 telephone conversation, Email, etc.) The intent of a shared lock is 656 to let collaborators know who else may be working on a resource. 658 Shared locks are included because experience from web distributed 659 authoring systems has indicated that exclusive locks are often too 660 rigid. An exclusive lock is used to enforce a particular editing 661 process: take out an exclusive lock, read the resource, perform 662 edits, write the resource, release the lock. This editing process 663 has the problem that locks are not always properly released, for 664 example when a program crashes, or when a lock owner leaves without 665 unlocking a resource. While both timeouts and administrative action 666 can be used to remove an offending lock, neither mechanism may be 667 available when needed; the timeout may be long or the administrator 668 may not be available. 670 5.2 Required Support 672 A WebDAV compliant server is not required to support locking in any 673 form. If the server does support locking it may choose to support 674 any combination of exclusive and shared locks for any access types. 676 The reason for this flexibility is that locking policy strikes to 677 the very heart of the resource management and versioning systems 678 employed by various storage repositories. These repositories 679 require control over what sort of locking will be made available. 680 For example, some repositories only support shared write locks while 681 others only provide support for exclusive write locks while yet 682 others use no locking at all. As each system is sufficiently 683 different to merit exclusion of certain locking features, this 684 specification leaves locking as the sole axis of negotiation within 685 WebDAV. 687 5.3 Lock Tokens 689 A lock token is a type of state token, represented as a URI, which 690 identifies a particular lock. A lock token is returned by every 691 successful LOCK operation in the lockdiscovery property in the 692 response body, and can also be found through lock discovery on a 693 resource. 695 Lock token URIs MUST be unique across all resources for all time. 696 This uniqueness constraint allows lock tokens to be submitted across 697 resources and servers without fear of confusion. 699 This specification provides a lock token URI scheme called 700 opaquelocktoken that meets the uniqueness requirements. However 701 resources are free to return any URI scheme so long as it meets the 702 uniqueness requirements. 704 Having a lock token provides no special access rights. Anyone can 705 find out anyone else's lock token by performing lock discovery. 706 Locks MUST be enforced based upon whatever authentication mechanism 707 is used by the server, not based on the secrecy of the token values. 709 5.4 opaquelocktoken Lock Token URI Scheme 711 The opaquelocktoken URI scheme is designed to be unique across all 712 resources for all time. Due to this uniqueness quality, a client 713 may submit an opaque lock token in an If header on a resource other 714 than the one that returned it. 716 All resources MUST recognize the opaquelocktoken scheme and, at 717 minimum, recognize that the lock token does not refer to an 718 outstanding lock on the resource. 720 In order to guarantee uniqueness across all resources for all time 721 the opaquelocktoken requires the use of the Universally Unique 722 Identifier (UUID, also known as a Globally Unique Identifier, or 723 GUID) mechanism, as described in [Leach, Salz, 1998]. 725 Opaquelocktoken generators, however, have a choice of how they 726 create these tokens. They can either generate a new UUID for every 727 lock token they create or they can create a single UUID and then add 728 extension characters. If the second method is selected then the 729 program generating the extensions MUST guarantee that the same 730 extension will never be used twice with the associated UUID. 732 OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The 733 UUID production is the string form of a UUID, as defined in [Leach, 734 Salz, 1998]. Note that white space (LWS) is not allowed between 735 elements of this production. 737 Extension = path ; path is defined in section 3.2.1 of RFC 2068 738 [Fielding et al., 1996] 740 5.5 Lock Capability Discovery 742 Since server lock support is optional, a client trying to lock a 743 resource on a server can either try the lock and hope for the best, 744 or perform some form of discovery to determine what lock 745 capabilities the server supports. This is known as lock capability 746 discovery. Lock capability discovery differs from discovery of 747 supported access control types, since there may be access control 748 types without corresponding lock types. A client can determine what 749 lock types the server supports by retrieving the supportedlock 750 property. 752 Any DAV compliant resource that supports the LOCK method MUST 753 support the supportedlock property. 755 5.6 Active Lock Discovery 757 If another principal locks a resource that a principal wishes to 758 access, it is useful for the second principal to be able to find out 759 who the first principal is. For this purpose the lockdiscovery 760 property is provided. This property lists all outstanding locks, 761 describes their type, and where available, provides their lock 762 token. 764 Any DAV compliant resource that supports the LOCK method MUST 765 support the lockdiscovery property. 767 5.7 Usage Considerations 769 Although the locking mechanisms specified here provide some help in 770 preventing lost updates, they cannot guarantee that updates will 771 never be lost. Consider the following scenario: 773 Two clients A and B are interested in editing the resource 774 'index.html'. Client A is an HTTP client rather than a WebDAV 775 client, and so does not know how to perform locking. 777 Client A doesn't lock the document, but does a GET and begins 778 editing. 779 Client B does LOCK, performs a GET and begins editing. 780 Client B finishes editing, performs a PUT, then an UNLOCK. 781 Client A performs a PUT, overwriting and losing all of B's changes. 783 There are several reasons why the WebDAV protocol itself cannot 784 prevent this situation. First, it cannot force all clients to use 785 locking because it must be compatible with HTTP clients that do not 786 comprehend locking. Second, it cannot require servers to support 787 locking because of the variety of repository implementations, some 788 of which rely on reservations and merging rather than on locking. 789 Finally, being stateless, it cannot enforce a sequence of operations 790 like LOCK / GET / PUT / UNLOCK. 792 WebDAV servers that support locking can reduce the likelihood that 793 clients will accidentally overwrite each other's changes by 794 requiring clients to lock resources before modifying them. Such 795 servers would effectively prevent HTTP 1.0 and HTTP 1.1 clients from 796 modifying resources. 798 WebDAV clients can be good citizens by using a lock / retrieve / 799 write /unlock sequence of operations (at least by default) whenever 800 they interact with a WebDAV server that supports locking. 802 HTTP 1.1 clients can be good citizens, avoiding overwriting other 803 clients' changes, by using entity tags in If-Match headers with any 804 requests that would modify resources. 806 Information managers may attempt to prevent overwrites by 807 implementing client-side procedures requiring locking before 808 modifying WebDAV resources. 810 6 Write Lock 812 This section describes the semantics specific to the write lock 813 type. The write lock is a specific instance of a lock type, and is 814 the only lock type described in this specification. 816 6.1 Methods Restricted by Write Locks 818 A write lock MUST prevent a principal without the lock from 819 successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, 820 DELETE, or MKCOL on the locked resource. All other current methods, 821 GET in particular, function independent of the lock. 823 Note, however, that as new methods are created it will be necessary 824 to specify how they interact with a write lock. 826 6.2 Write Locks and Properties 828 While those without a write lock may not alter a property on a 829 resource it is still possible for the values of live properties to 830 change, even while locked, due to the requirements of their schemas. 831 Only dead properties and live properties defined to respect locks 832 are guaranteed not to change while write locked. 834 6.3 Write Locks and Null Resources 836 It is possible to assert a write lock on a null resource in order to 837 lock the name. 839 A write locked null resource, referred to as a lock-null resource, 840 MUST respond with a 404 Not Found or 405 Method Not Allowed to any 841 HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, PROPFIND, 842 LOCK, and UNLOCK. A lock-null resource MUST appear as a member of 843 its parent collection. Additionally the lock-null resource MUST 844 have defined on it all mandatory DAV properties. Most of these 845 properties, such as all the get* properties, will have no value as a 846 lock-null resource does not support the GET method. Lock-Null 847 resources MUST have defined values for lockdiscovery and 848 supportedlock properties. 850 Until a method such as PUT or MKCOL is successfully executed on the 851 lock-null resource the resource MUST stay in the lock-null state. 852 However, once a PUT or MKCOL is successfully executed on a lock-null 853 resource the resources ceases to be in the lock-null state. 855 If the resource is unlocked, for any reason, without a PUT, MKCOL, 856 or similar method having been successfully executed upon it then the 857 resource MUST return to the null state. 859 6.4 Write Locks and Collections 861 A write lock on a collection prevents the addition or removal of 862 members of the collection by non-lock owners. As a consequence, 863 when a principal issues a request to create a new internal member of 864 a write locked collection using PUT or POST, or to remove an 865 existing internal member of a write locked collection using DELETE, 866 this request MUST fail if the principal does not have a write lock 867 on the collection. 869 However, if a write lock request is issued to a collection 870 containing internal member resources that are currently locked in a 871 manner which conflicts with the write lock, the request MUST fail 872 with a 423 Locked status code. 874 If a lock owner causes a resource to be added as an internal member 875 of a locked collection then the new resource MUST be automatically 876 added to the lock. This is the only mechanism that allows a 877 resource to be added to a write lock. Thus, for example, if the 878 collection /a/b/ is write locked and the resource /c is moved to 879 /a/b/c then /a/b/c will be added to the write lock. 881 6.5 Write Locks and the If Request Header 883 If a user agent is not required to have knowledge about a lock when 884 requesting an operation on a locked resource, the following scenario 885 might occur. Program A, run by User A, takes out a write lock on a 886 resource. Program B, also run by User A, has no knowledge of the 887 lock taken out by Program A, yet performs a PUT to the locked 888 resource. In this scenario, the PUT succeeds because locks are 889 associated with a principal, not a program, and thus program B, 890 because it is acting with principal A's credential, is allowed to 891 perform the PUT. However, had program B known about the lock, it 892 would not have overwritten the resource, preferring instead to 893 present a dialog box describing the conflict to the user. Due to 894 this scenario, a mechanism is needed to prevent different programs 895 from accidentally ignoring locks taken out by other programs with 896 the same authorization. 898 In order to prevent these collisions a lock token MUST be submitted 899 by an authorized principal in the If header for all locked resources 900 that a method may interact with or the method MUST fail. For 901 example, if a resource is to be moved and both the source and 902 destination are locked then two lock tokens must be submitted, one 903 for the source and the other for the destination. 905 6.5.1 Example - Write Lock 907 >>Request 909 COPY /~fielding/index.html HTTP/1.1 910 Host: www.ics.uci.edu 911 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 912 If: 913 () 915 >>Response 917 HTTP/1.1 204 No Content 919 In this example, even though both the source and destination are 920 locked, only one lock token must be submitted, for the lock on the 921 destination. This is because the source resource is not modified by 922 a COPY, and hence unaffected by the write lock. In this example, 923 user agent authentication has previously occurred via a mechanism 924 outside the scope of the HTTP protocol, in the underlying transport 925 layer. 927 6.6 Write Locks and COPY/MOVE 929 A COPY method invocation MUST NOT duplicate any write locks active 930 on the source. However, as previously noted, if the COPY copies the 931 resource into a collection that is depth locked then the resource 932 will be added to the lock. 934 A MOVE MUST NOT move the write lock with the resource although the 935 resource is subject to being added to an existing lock as specified 936 in section 6.4. For example, if the MOVE makes the resource a child 937 of a collection that is depth locked then the resource will be under 938 that collection's lock. Additionally, if a depth locked resource is 939 moved to a destination that is within the scope of the same depth 940 lock (e.g., within the namespace tree covered by the lock), the 941 moved resource will again be a member of the lock. In both these 942 examples, as specified in section 6.5, an If header must be 943 submitted containing a lock token for both the source and 944 destination. 946 6.7 Refreshing Write Locks 948 A client MUST NOT submit the same write lock request twice. Note 949 that a client is always aware it is resubmitting the same lock 950 request because it must include the lock token in the If header in 951 order to make the request for a resource that is already locked. 953 However, a client may submit a LOCK method with an If header but 954 without a body. This form of LOCK MUST only be used to "refresh" a 955 lock. Meaning, at minimum, that any timers associated with the lock 956 MUST be re-set. 958 A server may return a Timeout header with a lock refresh that is 959 different than the Timeout header returned when the lock was 960 originally requested. Additionally clients may submit Timeout 961 headers of arbitrary value with their lock refresh requests. 962 Servers, as always, may ignore Timeout headers submitted by the 963 client. 965 If an error is received in response to a refresh LOCK request the 966 client SHOULD assume that the lock was not refreshed. 968 7 HTTP Methods for Distributed Authoring 970 The following new HTTP methods use XML as a request and response 971 format. All DAV compliant clients and resources MUST use XML 972 parsers that are compliant with [Bray, Paoli, Sperberg-McQueen, 973 1998]. All XML used in either requests or responses MUST be, at 974 minimum, well formed. If a server receives ill-formed XML in a 975 request it MUST reject the entire request with a 400 Bad Request. 976 If a client receives ill-formed XML in a response then it MUST NOT 977 assume anything about the outcome of the executed method and SHOULD 978 treat the server as malfunctioning. 980 7.1 PROPFIND 982 The PROPFIND method retrieves properties defined on the Request-URI, 983 if the resource does not have any internal members, or on the 984 Request-URI and potentially its member resources, if the resource 985 does have internal members. All DAV compliant resources MUST 986 support the PROPFIND method and the propfind XML element (section 987 11.14) along with all XML elements defined for use with that 988 element. 990 A client may submit a Depth header with a value of "0", "1", or 991 "infinity" with a PROPFIND on a resource with internal members. DAV 992 compliant servers MUST support the "0", "1" and "infinity" 993 behaviors. By default, the PROPFIND method without a Depth header 994 MUST act as if a "Depth: infinity" header was included. 996 A client may submit a propfind XML element in the body of the 997 request method describing what information is being requested. It 998 is possible to request particular property values, all property 999 values, or a list of the names of the resource's properties. A 1000 client may choose not to submit a request body. An empty PROPFIND 1001 request body MUST be treated as a request for the names and values 1002 of all properties. 1004 All servers MUST support returning a response of content type 1005 text/xml that contains a multistatus XML element that describes the 1006 results of the attempts to retrieve the various properties. 1008 If there is an error retrieving a property then a proper error 1009 result MUST be included in the response. A request to retrieve the 1010 value of a property which does not exist is an error and MUST be 1011 noted, if the response uses a multistatus XML element, with a 1012 response XML element which contains a 404 Not Found status value. 1014 Consequently, the multistatus XML element for a resource with 1015 members MUST include a response XML element for each member of the 1016 resource, to whatever depth was requested. Each response XML element 1017 MUST contain an href XML element that identifies the resource on 1018 which the properties in the prop XML element are defined. Results 1019 for a PROPFIND on a resource with internal members are returned as a 1020 flat list whose order of entries is not significant. 1022 In the case of allprop and propname, if a principal does not have 1023 the right to know whether a particular property exists then the 1024 property should be silently excluded from the response. 1026 The results of this method SHOULD NOT be cached. 1028 7.1.1 Example - Retrieving Named Properties 1030 >>Request 1032 PROPFIND /file HTTP/1.1 1033 Host: www.foo.bar 1034 Content-type: text/xml 1035 Content-Length: xyz 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1049 >>Response 1051 HTTP/1.1 207 Multi-Status 1052 Content-Type: text/xml 1053 Content-Length: xxxxx 1055 1056 1057 1058 1059 1060 http://www.foo.bar/file 1061 1062 1063 1064 Box type A 1065 1066 1067 J.J. Johnson 1068 1069 1070 HTTP/1.1 200 OK 1071 1072 1073 1074 HTTP/1.1 403 Forbidden 1075 The user does not have access to 1076 the DingALing property. 1077 1078 1079 1080 There has been an access violation error. 1081 1082 1084 In this example, PROPFIND is executed on a non-collection resource 1085 http://www.foo.bar/file. The propfind XML element specifies the 1086 name of four properties whose values are being requested. In this 1087 case only two properties were returned, since the principal issuing 1088 the request did not have sufficient access rights to see the third 1090 and fourth properties. 1092 7.1.2 Example - Using allprop to Retrieve All Properties 1094 >>Request 1096 PROPFIND /container/ HTTP/1.1 1097 Host: www.foo.bar 1098 Depth: 1 1099 Content-Type: text/xml 1100 Content-Length: xxxxx 1102 1103 1104 1105 1106 1108 >>Response 1110 HTTP/1.1 207 Multi-Status 1111 Content-Type: text/xml 1112 Content-Length: xxxxx 1114 1115 1116 1117 1118 1119 http://www.foo.bar/container/ 1120 1121 1122 1123 Box type A 1124 1125 1126 Hadrian 1127 1128 1129 1997-12-01T17:42:21-08:00 1130 1131 1132 Example collection 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 HTTP/1.1 200 OK 1146 1147 1148 1149 http://www.foo.bar/container/front.html 1150 1151 1152 1153 Box type B 1154 1155 1156 1997-12-01T18:27:21-08:00 1157 1158 1159 Example HTML resource 1160 1161 1162 4525 1163 1164 1165 text/html 1166 1167 1168 zzyzx 1169 1170 1171 Monday, 12-Jan-98 09:25:56 GMT 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 HTTP/1.1 200 OK 1184 1185 1186 1187 In this example, PROPFIND was invoked on the resource 1188 http://www.foo.bar/container/ with a Depth header of 1, meaning the 1189 request applies to the resource and its children, and a propfind XML 1190 element containing the allprop XML element, meaning the request 1191 should return the name and value of all properties defined on each 1192 resource. 1194 The resource http://www.foo.bar/container/ has six properties 1195 defined on it: 1197 http://www.foo.bar/boxschema/bigbox, 1198 http://www.foo.bar/boxschema/author, DAV:creationdate, 1199 DAV:displayname, DAV:resourcetype, and DAV:supportedlock. 1201 The last four properties are WebDAV-specific, defined in section 12. 1202 Since GET is not supported on this resource, the get* properties 1203 (e.g., getcontentlength) are not defined on this resource. The DAV- 1204 specific properties assert that "container" was created on December 1205 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT 1206 (creationdate), has a name of "Example collection" (displayname), a 1207 collection resource type (resourcetype), and supports exclusive 1208 write and shared write locks (supportedlock). 1210 The resource http://www.foo.bar/container/front.html has nine 1211 properties defined on it: 1213 http://www.foo.bar/boxschema/bigbox (another instance of the 1214 "bigbox" property type), DAV:creationdate, DAV:displayname, 1215 DAV:getcontentlength, DAV:getcontenttype, DAV:getetag, 1216 DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. 1218 The DAV-specific properties assert that "front.html" was created on 1219 December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT 1220 (creationdate), has a name of "Example HTML resource" (displayname), 1221 a content length of 4525 bytes (getcontentlength), a MIME type of 1222 "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), 1223 was last modified on Monday, January 12, 1998, at 09:25:56 GMT 1224 (getlastmodified), has an empty resource type, meaning that it is 1225 not a collection (resourcetype), and supports both exclusive write 1226 and shared write locks (supportedlock). 1228 7.1.3 Example - Using propname to Retrieve all Property Names 1230 >>Request 1232 PROPFIND /container/ HTTP/1.1 1233 Host: www.foo.bar 1234 Content-Type: text/xml 1235 Content-Length: xxxxx 1236 1237 1238 1239 1240 1242 >>Response 1244 HTTP/1.1 207 Multi-Status 1245 Content-Type: text/xml 1246 Content-Length: xxxx 1248 1249 1250 1251 1252 1253 http://www.foo.bar/container/ 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 HTTP/1.1 200 OK 1264 1265 1266 1267 http://www.foo.bar/container/front.html 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 HTTP/1.1 200 OK 1281 1282 1283 1285 In this example, PROPFIND is invoked on the collection resource 1286 http://www.foo.bar/container/, with a propfind XML element 1287 containing the propname XML element, meaning the name of all 1288 properties should be returned. Since no depth header is present, it 1289 assumes its default value of "infinity", meaning the name of the 1290 properties on the collection and all its progeny should be returned. 1292 Consistent with the previous example, resource 1293 http://www.foo.bar/container/ has six properties defined on it, 1294 http://www.foo.bar/boxschema/bigbox, 1295 http://www.foo.bar/boxschema/author, DAV:creationdate, 1296 DAV:displayname, DAV:resourcetype, and DAV:supportedlock. 1298 The resource http://www.foo.bar/container/index.html, a member of 1299 the "container" collection, has nine properties defined on it, 1300 http://www.foo.bar/boxschema/bigbox, DAV:creationdate, 1301 DAV:displayname, DAV:getcontentlength, DAV:getcontenttype, 1302 DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and 1303 DAV:supportedlock. 1305 7.2 PROPPATCH 1307 The PROPPATCH method processes instructions specified in the request 1308 body to set and/or remove properties defined on the resource 1309 identified by the Request-URI. 1311 All DAV compliant resources MUST support the PROPPATCH method and 1312 MUST process instructions that are specified using the 1313 propertyupdate, set, and remove XML elements of the DAV schema. 1314 Execution of the directives in this method is, of course, subject to 1315 access control constraints. DAV compliant resources SHOULD support 1316 the setting of arbitrary dead properties. 1318 The request message body of a PROPPATCH method MUST contain the 1319 propertyupdate XML element. Instruction processing MUST occur in 1320 the order instructions are received (i.e., from top to bottom). 1321 Instructions MUST either all be executed or none executed. Thus if 1322 any error occurs during processing all executed instructions MUST be 1323 undone and a proper error result returned. Instruction processing 1324 details can be found in the definition of the set and remove 1325 instructions in section 11.13. 1327 7.2.1 Status Codes for use with Multi-Status 1329 The following are examples of response codes one would expect to be 1330 used in a Multi-Status response for this method. Note, however, 1331 that unless explicitly prohibited any 2/3/4/5xx series response code 1332 may be used in a Multi-Status response. 1334 200 OK - The command succeeded. As there can be a mixture of sets 1335 and removes in a body, a 201 Created seems inappropriate. 1337 403 Forbidden - The client, for reasons the server chooses not to 1338 specify, cannot alter one of the properties. 1340 409 Conflict - The client has provided a value whose semantics are 1341 not appropriate for the property. This includes trying to set read- 1342 only properties. 1344 423 Locked - The specified resource is locked and the client either 1345 is not a lock owner or the lock type requires a lock token to be 1346 submitted and the client did not submit it. 1348 425 Insufficient Space on Resource - The server did not have 1349 sufficient space to record the property. 1351 7.2.2 Example - PROPPATCH 1353 >>Request 1355 PROPPATCH /bar.html HTTP/1.1 1356 Host: www.foo.com 1357 Content-Type: text/xml 1358 Content-Length: xxxx 1360 1361 1362 1364 1365 1366 1367 1368 Jim Whitehead 1369 Roy Fielding 1370 1371 1372 1373 1374 1375 1376 1377 >>Response 1379 HTTP/1.1 207 Multi-Status 1380 Content-Type: text/xml 1381 Content-Length: xxxxx 1383 1384 1385 1387 1388 1389 http://www.foo.com/bar.html 1390 1391 1392 HTTP/1.1 424 Method Failure 1393 1394 1395 1396 HTTP/1.1 409 Conflict 1397 1398 Copyright Owner can not be deleted or 1399 altered. 1400 1401 1403 In this example, the client requests the server to set the value of 1404 the http://www.w3.com/standards/z39.50/Authors property, and to 1405 remove the property http://www.w3.com/standards/z39.50/Copyright- 1406 Owner. Since the Copyright-Owner property could not be removed, no 1407 property modifications occur. The Method Failure status code for 1408 the Authors property indicates this action would have succeeded if 1409 it were not for the conflict with removing the Copyright-Owner 1410 property. 1412 7.3 MKCOL Method 1414 The MKCOL method is used to create a new collection. All DAV 1415 compliant resources MUST support the MKCOL method. 1417 7.3.1 Request 1419 MKCOL creates a new collection resource at the location specified by 1420 the Request-URI. If the resource identified by the Request-URI is 1421 non-null then the MKCOL MUST fail. During MKCOL processing, a 1422 server MUST make the Request-URI a member of its parent collection, 1423 unless the Request-URI is "/". If no such ancestor exists, the 1424 method MUST fail. When the MKCOL operation creates a new collection 1425 resource, all ancestors MUST already exist, or the method MUST fail 1426 with a 409 Conflict status code. For example, if a request to 1427 create collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ 1428 exists, the request must fail. 1430 When MKCOL is invoked without a request body, the newly created 1431 collection SHOULD have no members. 1433 A MKCOL request message may contain a message body. The behavior of 1434 a MKCOL request when the body is present is limited to creating 1435 collections, members of a collection, bodies of members and 1436 properties on the collections or members. If the server receives a 1437 MKCOL request entity type it does not support or understand it MUST 1438 respond with a 415 Unsupported Media Type status code. The exact 1439 behavior of MKCOL for various request media types is undefined in 1440 this document, and will be specified in separate documents. 1442 7.3.2 Response Codes 1444 Responses from a MKCOL request MUST NOT be cached as MKCOL has non- 1445 idempotent semantics. 1447 201 Created - The collection or structured resource was created in 1448 its entirety. 1450 403 Forbidden - This indicates at least one of two conditions: 1) 1451 the server does not allow the creation of collections at the given 1452 location in its namespace, or 2) the parent collection of the 1453 Request-URI exists but cannot accept members. 1455 405 Method Not Allowed - MKCOL can only be executed on a 1456 deleted/non-existent resource. 1458 409 Conflict - A collection cannot be made at the Request-URI until 1459 one or more intermediate collections have been created. 1461 415 Unsupported Media Type- The server does not support the request 1462 type of the body. 1464 425 Insufficient Space on Resource - The resource does not have 1465 sufficient space to record the state of the resource after the 1466 execution of this method. 1468 7.3.3 Example - MKCOL 1470 This example creates a collection called /webdisc/xfiles/ on the 1471 server www.server.org. 1473 >>Request 1475 MKCOL /webdisc/xfiles/ HTTP/1.1 1476 Host: www.server.org 1478 >>Response 1480 HTTP/1.1 201 Created 1482 7.4 GET, HEAD for Collections 1484 The semantics of GET are unchanged when applied to a collection, 1485 since GET is defined as, "retrieve whatever information (in the form 1486 of an entity) is identified by the Request-URI" [Fielding et al., 1487 1997]. GET when applied to a collection may return the contents of 1488 an "index.html" resource, a human-readable view of the contents of 1489 the collection, or something else altogether. Hence it is possible 1490 that the result of a GET on a collection will bear no correlation to 1491 the membership of the collection. 1493 Similarly, since the definition of HEAD is a GET without a response 1494 message body, the semantics of HEAD are unmodified when applied to 1495 collection resources. 1497 7.5 POST for Collections 1499 Since by definition the actual function performed by POST is 1500 determined by the server and often depends on the particular 1501 resource, the behavior of POST when applied to collections cannot be 1502 meaningfully modified because it is largely undefined. Thus the 1503 semantics of POST are unmodified when applied to a collection. 1505 7.6 DELETE 1507 7.6.1 DELETE for Non-Collection Resources 1509 If the DELETE method is issued to a non-collection resource which is 1510 an internal member of a collection, then during DELETE processing a 1511 server MUST remove the Request-URI from its parent collection. 1513 7.6.2 DELETE for Collections 1515 The DELETE method on a collection MUST act as if a "Depth: infinity" 1516 header was used on it. A client MUST NOT submit a Depth header with 1517 a DELETE on a collection with any value but infinity. 1519 DELETE instructs that the collection specified in the request-URI 1520 and all its internal member resources are to be deleted. 1522 If any member cannot be deleted then all of the member's ancestors 1523 MUST NOT be deleted, so as to maintain the namespace. 1525 Any headers included with DELETE MUST be applied in processing every 1526 resource to be deleted. 1528 When the DELETE method has completed processing it MUST return a 1529 consistent namespace. 1531 If an error occurs with a resource other than the resource 1532 identified in the request URI then the response MUST be a 207 Multi- 1533 Status. 424 Method Failure errors SHOULD NOT be in the 207 Multi- 1534 Status. They can be safely left out because the client will know 1535 that the ancestors of a resource could not be deleted when the 1536 client receives an error for the ancestor's progeny. Additionally 1537 204 No Content errors SHOULD NOT be returned in the 207 Multi- 1538 Status. The reason for this prohibition is that 204 No Content is 1539 the default success code. 1541 7.6.2.1 Example - DELETE 1543 >>Request 1545 DELETE /container/ HTTP/1.1 1546 Host: www.foo.bar 1548 >>Response 1550 HTTP/1.1 207 Multi-Status 1551 Content-Type: text/xml 1552 Content-Length: xxxxx 1554 1555 1556 1557 1558 http://www.foo.bar/container/resource3 1559 HTTP/1.1 423 Locked 1560 1561 1563 In this example the attempt to delete 1564 http://www.foo.bar/container/resource3 failed because it is locked, 1565 and no lock token was submitted with the request. Consequently, the 1566 attempt to delete http://www.foo.bar/container/ also failed. Thus 1567 the client knows that the attempt to delete 1568 http://www.foo.bar/container/ must have also failed since the parent 1569 can not be deleted unless its child has also been deleted. Even 1570 though a Depth header has not been included, a depth of infinity is 1571 assumed because the method is on a collection. 1573 7.7 PUT 1575 7.7.1 PUT for Non-Collection Resources 1577 A PUT performed on an existing resource replaces the GET response 1578 entity of the resource. Properties defined on the resource may be 1579 recomputed during PUT processing but are not otherwise affected. 1580 For example, if a server recognizes the content type of the request 1581 body, it may be able to automatically extract information that could 1582 be profitably exposed as properties. 1584 A PUT that would result in the creation of a resource without an 1585 appropriately scoped parent collection MUST fail with a 409 1586 Conflict. 1588 7.7.2 PUT for Collections 1590 As defined in the HTTP/1.1 specification [Fielding et al., 1997], 1591 the "PUT method requests that the enclosed entity be stored under 1592 the supplied Request-URI." Since submission of an entity 1593 representing a collection would implicitly encode creation and 1594 deletion of resources, this specification intentionally does not 1595 define a transmission format for creating a collection using PUT. 1596 Instead, the MKCOL method is defined to create collections. 1598 When the PUT operation creates a new non-collection resource all 1599 ancestors MUST already exist. If all ancestors do not exist, the 1600 method MUST fail with a 409 Conflict status code. For example, if 1601 resource /a/b/c/d.html is to be created and /a/b/c/ does not exist, 1602 then the request must fail. 1604 7.8 COPY Method 1606 The COPY method creates a duplicate of the source resource, given by 1607 the Request-URI, in the destination resource, given by the 1608 Destination header. The Destination header MUST be present. The 1609 exact behavior of the COPY method depends on the type of the source 1610 resource. 1612 All WebDAV compliant resources MUST support the COPY method. 1613 However, support for the COPY method does not guarantee the ability 1614 to copy a resource. For example, separate programs may control 1615 resources on the same server. As a result, it may not be possible 1616 to copy a resource to a location that appears to be on the same 1617 server. 1619 7.8.1 COPY for HTTP/1.1 resources 1621 When the source resource is not a collection the result of the COPY 1622 method is the creation of a new resource at the destination whose 1623 state and behavior match that of the source resource as closely as 1624 possible. However, the exact state and behavior of the destination 1625 resource depend on what information the source resource is able to 1626 provide and what information the destination resource is able to 1627 accept. 1629 Subsequent alterations to the destination resource will not modify 1630 the source resource. Subsequent alterations to the source resource 1631 will not modify the destination resource. 1633 All properties on the source resource MUST be duplicated on the 1634 destination resource, subject to modifying headers and XML elements, 1635 following the definition for copying properties. 1637 7.8.2 COPY for Properties 1639 The following section defines how properties on a resource are 1640 handled during a COPY operation. 1642 Live properties SHOULD be duplicated as identically behaving live 1643 properties at the destination resource. If a property cannot be 1644 copied live, then its value MUST be duplicated, octet-for-octet, in 1645 an identically named, dead property on the destination resource 1646 subject to the effects of the propertybehavior XML element. 1648 The propertybehavior XML element can specify that properties are 1649 copied on best effort, that all live properties must be successfully 1650 copied or the method must fail, or that a specified list of live 1651 properties must be successfully copied or the method must fail. The 1652 propertybehavior XML element is defined in section 11.12. 1654 7.8.3 COPY for Collections 1656 The COPY method on a collection without a Depth header MUST act as 1657 if a Depth header with value "infinity" was included. A client may 1658 submit a Depth header on a COPY on a collection with a value of "0" 1659 or "infinity". DAV compliant servers MUST support the "0" and 1660 "infinity" Depth header behaviors. 1662 A COPY of depth infinity instructs that the collection specified in 1663 the Request-URI is to be copied to the location specified in the 1664 Destination header, and all its internal member resources are to be 1665 copied to a location relative to it, recursively through all levels 1666 of the collection hierarchy. 1668 A COPY of depth "0" only instructs that the collection and its 1669 properties but not its internal members, are to be copied. 1671 Any headers included with a COPY MUST be applied in processing every 1672 resource to be copied with the exception of the Destination header. 1674 The Destination header only specifies the destination for the 1675 Request-URI. When applied to members of the collection specified in 1676 the request-URI the value of Destination is to be modified to 1677 reflect the current location in the hierarchy. So, if the request- 1678 URI is /a/ and the destination is /b/ then when /a/c/d is processed 1679 it must use a destination of /b/c/d. 1681 When the COPY method has completed processing it MUST have created a 1682 consistent namespace at the destination. However, if an error 1683 occurs while copying an internal member collection, the server MUST 1684 NOT copy any members of this collection. After detecting an error, 1685 the COPY operation SHOULD try to finish as much of the original copy 1686 operation as possible. So, for example, if an infinite depth copy 1687 operation is performed on collection /a/, which contains collections 1688 /a/b/ and /a/c/, and an error occurs copying /a/b/, an attempt 1689 should still be made to copy /a/c/. Similarly, after encountering an 1690 error copying a non-collection resource as part of an infinite depth 1691 copy, the server SHOULD try to finish as much of the original copy 1692 operation as possible. 1694 If an error in executing the COPY method occurs with a resource 1695 other than the resource identified in the request URI then the 1696 response MUST be a 207 Multi-Status. 1698 424 Method Failure errors SHOULD NOT be returned in the 207 Multi- 1699 Status from a COPY method. These responses can be safely omitted 1700 because the client will know that the progeny of a resource could 1701 not be copied when the client receives an error for the parent. 1702 Additionally 201 Created/204 No Content response codes SHOULD NOT be 1703 returned as values in 207 Multi-Status responses from COPY methods. 1704 They, too, can be safely omitted because they are the default 1705 success codes. 1707 7.8.4 COPY and the Overwrite Header 1709 If a resource exists at the destination and the Overwrite header is 1710 "T" then prior to performing the copy the server MUST perform a 1711 DELETE with Depth Infinity on the destination resource. If the 1712 Overwrite header is set to "F" then the operation will fail. 1714 7.8.5 Status Codes 1716 201 Created - The source resource was successfully copied. The copy 1717 operation resulted in the creation of a new resource. 1719 204 No Content - The source resource was successfully copied to a 1720 pre-existing destination resource. 1722 412 Precondition Failed - The server was unable to maintain the 1723 liveness of the properties listed in the propertybehavior XML 1724 element or the Overwrite header is "F" and the state of the 1725 destination resource is non-null. 1727 423 Locked - The destination resource was locked. 1729 425 Insufficient Space on Resource - The destination resource does 1730 not have sufficient space to record the state of the resource after 1731 the execution of this method. 1733 502 Bad Gateway - This may occur when the destination is on another 1734 server and the destination server refuses to accept the resource. 1736 7.8.6 Example - COPY with Overwrite 1738 This example shows resource 1739 http://www.ics.uci.edu/~fielding/index.html being copied to the 1740 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1741 204 No Content status code indicates the existing resource at the 1742 destination was overwritten. 1744 >>Request 1746 COPY /~fielding/index.html HTTP/1.1 1747 Host: www.ics.uci.edu 1748 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1750 >>Response 1752 HTTP/1.1 204 No Content 1754 7.8.7 Example - COPY with No Overwrite 1756 The following example shows the same copy operation being performed, 1757 but with the Overwrite header set to "F." A response of 412 1758 Precondition Failed is returned because the destination resource has 1759 a non-null state. 1761 >>Request 1763 COPY /~fielding/index.html HTTP/1.1 1764 Host: www.ics.uci.edu 1765 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1766 Overwrite: F 1768 >>Response 1770 HTTP/1.1 412 Precondition Failed 1772 7.8.8 Example - COPY of a Collection 1774 >>Request 1776 COPY /container/ HTTP/1.1 1777 Host: www.foo.bar 1778 Destination: http://www.foo.bar/othercontainer/ 1779 Depth: infinity 1780 Content-Type: text/xml 1781 Content-Length: xxxxx 1783 1784 1785 1786 * 1787 1788 >>Response 1790 HTTP/1.1 207 Multi-Status 1791 Content-Type: text/xml 1792 Content-Length: xxxxx 1794 1795 1796 1797 1798 http://www.foo.bar/othercontainer/R2/ 1799 HTTP/1.1 412 Precondition Failed 1800 1801 1803 The Depth header is unnecessary as the default behavior of COPY on a 1804 collection is to act as if a "Depth: infinity" header had been 1805 submitted. In this example most of the resources, along with the 1806 collection, were copied successfully. However the collection R2 1807 failed, most likely due to a problem with maintaining the liveness 1808 of properties (this is specified by the propertybehavior XML 1809 element). Because there was an error copying R2, none of R2's 1810 members were copied. However no errors were listed for those 1811 members due to the error minimization rules given in section 7.8.3. 1813 7.9 MOVE Method 1815 The MOVE operation on a non-collection resource is the logical 1816 equivalent of a copy (COPY) followed by a delete of the source, 1817 where the actions are performed atomically. Consequently, the 1818 Destination header MUST be present on all MOVE methods and MUST 1819 follow all COPY requirements for the COPY part of the MOVE method. 1820 All DAV compliant resources MUST support the MOVE method. However, 1821 support for the MOVE method does not guarantee the ability to move a 1822 resource to a particular destination. 1824 For example, separate programs may actually control different sets 1825 of resources on the same server. Therefore, it may not be possible 1826 to move a resource within a namespace that appears to belong to the 1827 same server. 1829 If a resource exists at the destination, the destination resource 1830 will be DELETEd as a side-effect of the MOVE operation, subject to 1831 the restrictions of the Overwrite header. 1833 7.9.1 MOVE for Properties 1835 The behavior of properties on a MOVE, including the effects of the 1836 propertybehavior XML element, MUST be the same as specified in 1837 section 7.8.2. 1839 7.9.2 MOVE for Collections 1841 A MOVE of depth infinity instructs that the collection specified in 1842 the Request-URI be moved to the location specified in the 1843 Destination header, and all its internal member resources are to be 1844 moved to locations relative to it, recursively through all levels of 1845 the collection hierarchy. 1847 The MOVE method on a collection MUST act as if a Depth "infinity" 1848 header was used on it. A client MUST NOT submit a Depth header on a 1849 MOVE on a collection with any value but "infinity". 1851 Any headers included with MOVE MUST be applied in processing every 1852 resource to be moved with the exception of the Destination header. 1854 The behavior of the Destination header is the same as given for COPY 1855 on collections. 1857 When the MOVE method has completed processing it MUST have created a 1858 consistent namespace on both the source and destination. However, if 1859 an error occurs while moving an internal member collection, the 1860 server MUST NOT move any members of the failed collection.. In this 1861 case, after detecting the error, the move operation SHOULD try to 1862 finish as much of the original move as possible. So, for example, 1863 if an infinite depth move is performed on collection /a/, which 1864 contains collections /a/b/ and /a/c/, and an error occurs moving 1865 /a/b/, an attempt should still be made to try moving /a/c/. 1866 Similarly, after encountering an error moving a non-collection 1867 resource as part of an infinite depth move, the server SHOULD try to 1868 finish as much of the original move operation as possible. 1870 If an error occurs with a resource other than the resource 1871 identified in the request URI then the response MUST be a 207 Multi- 1872 Status. 1874 424 Method Failure errors SHOULD NOT be returned as values in the 1875 207 Multi-Status from a MOVE method. These errors can be safely 1876 omitted because the client will know that the progeny of a resource 1877 could not be moved when the client receives an error for the parent. 1878 Additionally 201 Created/204 No Content responses SHOULD NOT be 1879 returned as values in 207 Multi-Status responses from MOVES. These 1880 responses can be safely omitted because they are the default success 1881 codes. 1883 7.9.3 MOVE and the Overwrite Header 1885 If a resource exists at the destination and the Overwrite header is 1886 "T" then prior to performing the move the server MUST perform a 1887 DELETE with Depth infinity on the destination resource. If the 1888 Overwrite header is set to "F" then the operation will fail. 1890 7.9.4 Status Codes 1892 201 Created - The source resource was successfully moved, and a new 1893 resource was created at the destination. 1895 204 No Content - The source resource was successfully moved to a 1896 pre-existing destination resource. 1898 412 Precondition Failed - The server was unable to maintain the 1899 liveness of the properties listed in the propertybehavior XML 1900 element or the Overwrite header is "F" and the state of the 1901 destination resource is non-null. 1903 423 Locked - The source or the destination resource was locked. 1905 502 Bad Gateway - This may occur when the destination is on another 1906 server and the destination server refuses to accept the resource. 1908 7.9.5 Example - MOVE of a Non-Collection 1910 This example shows resource 1911 http://www.ics.uci.edu/~fielding/index.html being moved to the 1912 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1913 contents of the destination resource would have been overwritten if 1914 the destination resource had been non-null. In this case, since 1915 there was nothing at the destination resource, the response code is 1916 201 Created. 1918 >>Request 1920 MOVE /~fielding/index.html HTTP/1.1 1921 Host: www.ics.uci.edu 1922 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1924 >>Response 1926 HTTP/1.1 201 Created 1927 Content-Location: http://www.ics.uci.edu/users/f/fielding/index.html 1929 7.9.6 Example - MOVE of a Collection 1931 >>Request 1933 MOVE /container/ HTTP/1.1 1934 Host: www.foo.bar 1935 Destination: http://www.foo.bar/othercontainer/ 1936 Overwrite: F 1937 If: () 1938 () 1939 Content-Type: text/xml 1940 Content-Length: xyz 1942 1943 1944 1945 * 1946 1948 >>Response 1950 HTTP/1.1 207 Multi-Status 1951 Content-Type: text/xml 1952 Content-Length: zzz 1954 1955 1956 1957 1958 http://www.foo.bar/othercontainer/C2/ 1959 HTTP/1.1 423 Locked 1960 1961 1963 In this example the client has submitted a number of lock tokens 1964 with the request. A lock token will need to be submitted for every 1965 resource, both source and destination, anywhere in the scope of the 1966 method, that is locked. In this case the proper lock token was not 1967 submitted for the destination http://www.foo.bar/othercontainer/C2/. 1968 This means that the resource /container/C2/ could not be moved. 1969 Because there was an error copying /container/C2/, none of 1970 /container/C2's members were copied. However no errors were listed 1971 for those members due to the error minimization rules given in 1972 section 7.8.3. User agent authentication has previously occurred 1973 via a mechanism outside the scope of the HTTP protocol, in an 1974 underlying transport layer. 1976 7.10 LOCK Method 1978 The following sections describe the LOCK method, which is used to 1979 take out a lock of any access type. These sections on the LOCK 1980 method describe only those semantics that are specific to the LOCK 1981 method and are independent of the access type of the lock being 1982 requested. 1984 Any resource which supports the LOCK method MUST, at minimum, 1985 support the XML request and response formats defined herein. 1987 7.10.1 Operation 1989 A LOCK method invocation creates the lock specified by the lockinfo 1990 XML element on the Request-URI. Lock method requests SHOULD have a 1991 XML request body which contains an owner XML element for this lock 1992 request, unless this is a refresh request. The LOCK request may have 1993 a Timeout header. 1995 Clients MUST assume that locks may arbitrarily disappear at any 1996 time, regardless of the value given in the Timeout header. The 1997 Timeout header only indicates the behavior of the server if 1998 "extraordinary" circumstances do not occur. For example, an 1999 administrator may remove a lock at any time or the system may crash 2000 in such a way that it loses the record of the lock's existence. The 2001 response MUST contain the value of the lockdiscovery property in a 2002 prop XML element. 2004 7.10.2 The Effect of Locks on Properties and Collections 2006 The scope of a lock is the entire state of the resource, including 2007 its body and associated properties. As a result, a lock on a 2008 resource MUST also lock the resource's properties. 2010 For collections, a lock also affects the ability to add or remove 2011 members. The nature of the effect depends upon the type of access 2012 control involved. 2014 7.10.3 Locking Replicated Resources 2016 Some servers automatically replicate resources across multiple URLs. 2017 In such a circumstance the server MUST only accept a lock on one of 2018 the URLs if the server can guarantee that the lock will be honored 2019 across all the URLs. 2021 7.10.4 Depth and Locking 2023 The Depth header may be used with the LOCK method. Values other 2024 than 0 or infinity MUST NOT be used with the Depth header on a LOCK 2025 method. All resources that support the LOCK method MUST support the 2026 Depth header. 2028 A Depth header of value 0 means to just lock the resource specified 2029 by the request-URI. 2031 If the Depth header is set to infinity then the resource specified 2032 in the request-URI along with all its internal members, all the way 2033 down the hierarchy, are to be locked. A successful result MUST 2034 return a single lock token which represents all the resources that 2035 have been locked. If an UNLOCK is successfully executed on this 2036 token, all associated resources are unlocked. If the lock cannot be 2037 granted to all resources, a 409 Conflict status code MUST be 2038 returned with a response entity body containing a multistatus XML 2039 element describing which resource(s) prevented the lock from being 2040 granted. Hence, partial success is not an option. Either the 2041 entire hierarchy is locked or no resources are locked. 2043 If no depth header is submitted on a LOCK request then the request 2044 MUST act as if a Depth of infinity had been submitted. 2046 7.10.5 Interaction with other Methods 2048 The interaction of a LOCK with various methods is dependent upon the 2049 lock type. However, independent of lock type, a successful DELETE 2050 of a resource MUST cause all of its locks to be removed. 2052 7.10.6 Lock Compatibility Table 2054 The table below describes the behavior that occurs when a lock 2055 request is made on a resource. 2057 Current lock state/ Shared Lock Exclusive 2058 Lock request Lock 2059 None True True 2060 Shared Lock True False 2061 Exclusive Lock False False* 2063 Legend: True = lock may be granted. False = lock MUST NOT be 2064 granted. *=It is illegal for a principal to request the same lock 2065 twice. 2067 The current lock state of a resource is given in the leftmost 2068 column, and lock requests are listed in the first row. The 2069 intersection of a row and column gives the result of a lock request. 2070 For example, if a shared lock is held on a resource, and an 2071 exclusive lock is requested, the table entry is "false", indicating 2072 the lock must not be granted. 2074 7.10.7 Status Codes 2076 200 Success - The lock request succeeded and the value of the 2077 lockdiscovery property is included in the body. 2079 412 Precondition Failed - The included lock token was not 2080 enforceable on this resource or the server could not satisfy the 2081 request in the lockinfo XML element. 2083 423 Locked - The resource is locked, so the method has been 2084 rejected. 2086 7.10.8 Example - Simple Lock Request 2088 >>Request 2090 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2091 Host: webdav.sb.aol.com 2092 Timeout: Infinite, Second-4100000000 2093 Content-Type: text/xml 2094 Content-Length: xyz 2095 Authorization: Digest username="ejw", 2096 realm="ejw@webdav.sb.aol.com", nonce="...", 2097 uri="/workspace/webdav/proposal.doc", 2098 response="...", opaque="..." 2100 2101 2102 2103 2104 2105 2106 http://www.ics.uci.edu/~ejw/contact.html 2107 2108 2110 >>Response 2112 HTTP/1.1 200 OK 2113 Content-Type: text/xml 2114 Content-Length: xxxxx 2116 2117 2118 2119 2120 2121 2122 2123 Infinity 2124 2125 2126 http://www.ics.uci.edu/~ejw/contact.html 2127 2128 2129 Second-604800 2130 2131 2132 opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2133 2134 2135 2136 2137 2138 This example shows the successful creation of an exclusive write 2139 lock on resource 2140 http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The 2141 resource http://www.ics.uci.edu/~ejw/contact.html contains contact 2142 information for the owner of the lock. The server has an activity- 2143 based timeout policy in place on this resource, which causes the 2144 lock to automatically be removed after 1 week (604800 seconds). 2145 Note that the nonce, response, and opaque fields have not been 2146 calculated in the Authorization request header. 2148 7.10.9 Example - Refreshing a Write Lock 2150 >>Request 2152 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2153 Host: webdav.sb.aol.com 2154 Timeout: Infinite, Second-4100000000 2155 If: () 2156 Authorization: Digest username="ejw", 2157 realm="ejw@webdav.sb.aol.com", nonce="...", 2158 uri="/workspace/webdav/proposal.doc", 2159 response="...", opaque="..." 2161 >>Response 2163 HTTP/1.1 200 OK 2164 Content-Type: text/xml 2165 Content-Length: xxxxx 2167 2168 2169 2170 2171 2172 2173 2174 Infinity 2175 2176 2177 http://www.ics.uci.edu/~ejw/contact.html 2178 2179 2180 Second-604800 2181 2182 2183 opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 2184 2185 2186 2187 2188 2189 This request would refresh the lock, resetting any time outs. 2190 Notice that the client asked for an infinite time out but the server 2191 choose to ignore the request. In this example, the nonce, response, 2192 and opaque fields have not been calculated in the Authorization 2193 request header. 2195 7.10.10 Example - Multi-Resource Lock Request 2197 >>Request 2199 LOCK /webdav/ HTTP/1.1 2200 Host: webdav.sb.aol.com 2201 Timeout: Infinite, Second-4100000000 2202 Depth: infinity 2203 Authorization: Digest username="ejw", 2204 realm="ejw@webdav.sb.aol.com", nonce="...", 2205 uri="/workspace/webdav/proposal.doc", 2206 response="...", opaque="..." 2208 2209 2210 2211 2212 2213 2214 http://www.ics.uci.edu/~ejw/contact.html 2215 2216 2218 >>Response 2220 HTTP/1.1 207 Multi-Status 2221 Content-Type: text/xml 2222 Content-Length: xxxxx 2224 2225 2226 2227 2228 http://webdav.sb.aol.com/webdav/secret 2229 HTTP/1.1 403 Forbidden 2230 2231 2232 http://webdav.sb.aol.com/webdav/ 2233 2234 2235 HTTP/1.1 424 Method Failure 2236 2237 2238 2239 This example shows a request for an exclusive write lock on a 2240 collection and all its children. In this request, the client has 2241 specified that it desires an infinite length lock, if available, 2242 otherwise a timeout of 4.1 billion seconds, if available. The 2243 request entity body contains the contact information for the 2244 principal taking out the lock, in this case a web page URL. 2246 The error is a 403 Forbidden response on the resource 2247 http://webdav.sb.aol.com/webdav/secret. Because this resource could 2248 not be locked, none of the resources were locked. Note also that 2249 the lockdiscovery property for the Request-URI has been included as 2250 required. In this example the lockdiscovery property is empty which 2251 means that there are no outstanding locks on the resource. 2253 In this example, the nonce, response, and opaque fields have not 2254 been calculated in the Authorization request header. 2256 7.11 UNLOCK Method 2258 The UNLOCK method removes the lock identified by the lock token in 2259 the Lock-Token request header from the Request-URI, and all other 2260 resources included in the lock. If all resources which have been 2261 locked under the submitted lock token can not be unlocked then the 2262 UNLOCK request MUST fail. 2264 Any DAV compliant resource which supports the LOCK method MUST 2265 support the UNLOCK method. 2267 7.11.1 Example - UNLOCK 2269 >>Request 2271 UNLOCK /workspace/webdav/info.doc HTTP/1.1 2272 Host: webdav.sb.aol.com 2273 Lock-Token: 2274 Authorization: Digest username="ejw", 2275 realm="ejw@webdav.sb.aol.com", nonce="...", 2276 uri="/workspace/webdav/proposal.doc", 2277 response="...", opaque="..." 2279 >>Response 2281 HTTP/1.1 204 No Content 2283 In this example, the lock identified by the lock token 2284 "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is 2285 successfully removed from the resource 2286 http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock 2287 included more than just one resource, the lock is removed from all 2288 resources included in the lock. The 204 status code is used instead 2289 of 200 OK because there is no response entity body. 2291 In this example, the nonce, response, and opaque fields have not 2292 been calculated in the Authorization request header. 2294 8 HTTP Headers for Distributed Authoring 2296 8.1 DAV Header 2298 DAV = "DAV" ":" "1" ["," "2"] ["," 1#extend] 2300 This header indicates that the resource supports the DAV schema and 2301 protocol as specified. All DAV compliant resources MUST return the 2303 DAV header on all OPTIONS responses. 2305 The value is a list of all compliance classes that the resource 2306 supports. Note that above a comma has already been added to the 2. 2307 This is because a resource can not be level 2 compliant unless it is 2308 also level 1 compliant. Please refer to section 14 for more details. 2309 In general, however, support for one compliance class does not 2310 entail support for any other. 2312 8.2 Depth Header 2314 Depth = "Depth" ":" ("0" | "1" | "infinity") 2316 The Depth header is used with methods executed on resources which 2317 could potentially have internal members to indicate whether the 2318 method is to be applied only to the resource (Depth = 0), to the 2319 resource and its immediate children, (Depth = 1), or the resource 2320 and all its progeny (Depth = infinity). 2322 The Depth header is only supported if a method's definition 2323 explicitly provides for such support. 2325 The following rules are the default behavior for any method that 2326 supports the Depth header. A method may override these defaults by 2327 defining different behavior in its definition. 2329 Methods which support the Depth header may choose not to support all 2330 of the header's values and may define, on a case by case basis, the 2331 behavior of the method if a Depth header is not present. For 2332 example, the MOVE method only supports Depth = infinity and if a 2333 Depth header is not present will act as if a Depth = infinity header 2334 had been applied. 2336 Clients MUST NOT rely upon methods executing on members of their 2337 hierarchies in any particular order or on the execution being atomic 2338 unless the particular method explicitly provides such guarantees. 2340 Upon execution, a method with a Depth header will perform as much of 2341 its assigned task as possible and then return a response specifying 2342 what it was able to accomplish and what it failed to do. 2344 So, for example, an attempt to COPY a hierarchy may result in some 2345 of the members being copied and some not. 2347 Any headers on a method that has a defined interaction with the 2348 Depth header MUST be applied to all resources in the scope of the 2349 method except where alternative behavior is explicitly defined. For 2350 example, an If-Match header will have its value applied against 2351 every resource in the method's scope and will cause the method to 2352 fail if the header fails to match. 2354 If a resource, source or destination, within the scope of the method 2355 with a depth header is locked in such a way as to prevent the 2356 successful execution of the method, then the lock token for that 2357 resource MUST be submitted with the request in the If request 2358 header. 2360 The Depth header only specifies the behavior of the method with 2361 regards to internal children. If a resource does not have internal 2362 children then the Depth header MUST be ignored. 2364 Please note, however, that it is always an error to submit a value 2365 for the Depth header that is not allowed by the method's definition. 2366 Thus submitting a "Depth: 1" on a COPY, even if the resource does 2367 not have internal members, will result in a 400 Bad Request. The 2368 method should fail not because the resource doesn't have internal 2369 members, but because of the illegal value in the header. 2371 8.3 Destination Header 2373 Destination = "Destination" ":" URI 2375 The Destination header specifies a destination resource for methods 2376 such as COPY and MOVE, which take two URIs as parameters. 2378 8.4 If Header 2380 If = "If" ":" ( 1*No-tag-list | 1*Tagged-list) 2381 No-tag-list = List 2382 Tagged-list = Resource 1*List 2383 Resource = Coded-url 2384 List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")" 2385 State-token = Coded-url 2386 Coded-url = "<" URI ">" 2388 The If header is intended to have similar functionality to the If- 2389 Match header defined in section 14.25 of [Fielding et al., 1997]. 2390 However the If header is intended for use with any URI which 2391 represents state information, referred to as a state token, about a 2392 resource as well as e-tags. A typical example of a state token is a 2393 lock token, and lock tokens are the only state tokens defined in 2394 this specification. 2396 All DAV compliant resources MUST honor the If header. 2398 The If header's purpose is to describe a series of state lists. If 2399 the state of the resource to which the header is applied does not 2400 match any of the specified state lists then the request MUST fail 2401 with a 412 Precondition Failed. If one of the described state lists 2402 matches the state of the resource then the request may succeed. 2404 8.4.1 No-tag-list Production 2406 The No-tag-list production describes a series of state tokens and e- 2407 tags. If multiple No-tag-list productions are used then only one 2409 needs to match the state of the resource for the method to be 2410 allowed to continue. 2412 If a method, due to the presence of a Depth or Destination header, 2413 is applied to multiple resources then the No-tag-list production 2414 MUST be applied to each resource the method is applied to. 2416 8.4.1.1 Example - No-tag-list If Header 2418 If: ( ["I am an e-tag"]) (["I am 2419 another e-tag"]) 2421 The previous header would require that any resources within the 2422 scope of the method must either be locked with the specified lock 2423 token and in the state identified by the "I am an e-tag" e-tag or in 2424 the state identified by the second e-tag "I am another e-tag". To 2425 put the matter more plainly one can think of the previous If header 2426 as being in the form (or (and ["I am 2427 an e-tag"]) (and ["I am another e-tag"])). 2429 8.4.2 Tagged-list Production 2431 The tagged-list production scopes a list production. That is, it 2432 specifies that the lists following the resource specification only 2433 apply to the specified resource. The scope of the resource 2434 production begins with the list production immediately following the 2435 resource production and ends with the next resource production, if 2436 any. 2438 When the If header is applied to a particular resource, the Tagged- 2439 list productions MUST be searched to determine if any of the listed 2440 resources match the operand resource(s) for the current method. If 2441 none of the resource productions match the current resource then the 2442 header MUST be ignored. If one of the resource productions does 2443 match the name of the resource under consideration then the list 2444 productions following the resource production MUST be applied to the 2445 resource in the manner specified in the previous section. 2447 The same URI MUST NOT appear more than once in a resource production 2448 in an If header. 2450 8.4.2.1 Example - Tagged List If header 2452 COPY /resource1 HTTP/1.1 2453 Host: www.foo.bar 2454 Destination: http://www.foo.bar/resource2 2455 If: ( 2456 [W/"A weak e-tag"]) (["strong e-tag"]) 2457 (["another strong e-tag"]) 2459 In this example http://www.foo.bar/resource1 is being copied to 2460 http://www.foo.bar/resource2. When the method is first applied to 2461 http://www.foo.bar/resource1, resource1 must be in the state 2462 specified by "( [W/"A weak e-tag"]) 2463 (["strong e-tag"])", that is, it either must be locked with a lock 2464 token of "locktoken:a-write-lock-token" and have a weak entity tag 2465 W/"A weak e-tag" or it must have a strong entity tag "strong e-tag". 2467 That is the only success condition since the resource 2468 http://www.bar.bar/random never has the method applied to it (the 2469 only other resource listed in the If header) and 2470 http://www.foo.bar/resource2 is not listed in the If header. 2472 8.4.3 not Production 2474 Every state token or e-tag is either current, and hence describes 2475 the state of a resource, or is not current, and does not describe 2476 the state of a resource. The boolean operation of matching a state 2477 token or e-tag to the current state of a resource thus resolves to a 2478 true or false value. The not production is used to reverse that 2479 value. The scope of the not production is the state-token or 2480 entity-tag immediately following it. 2482 If: (Not ) 2484 When submitted with a request, this If header requires that all 2485 operand resources must not be locked with locktoken:write1 and must 2486 be locked with locktoken:write2. 2488 8.4.4 Matching Function 2490 When performing If header processing, the definition of a matching 2491 state token or entity tag is as follows. 2493 Matching entity tag: Where the entity tag matches an entity tag 2494 associated with that resource. 2496 Matching state token: Where there is an exact match between the 2497 state token in the If header and any state token on the resource. 2499 8.4.5 If Header and Non-DAV Compliant Proxies 2501 Non-DAV compliant proxies will not honor the If header, since they 2502 will not understand the If header, and HTTP requires non-understood 2503 headers to be ignored. When communicating with HTTP/1.1 proxies, 2504 the "Cache-Control: no-cache" request header MUST be used so as to 2505 prevent the proxy from improperly trying to service the request from 2506 its cache. When dealing with HTTP/1.0 proxies the "Pragma: no- 2507 cache" request header MUST be used for the same reason. 2509 8.5 Lock-Token Request Header 2511 Lock-Token = "Lock-Token" ":" Coded-URL 2513 The Lock-Token request header is used with the UNLOCK method to 2514 identify the lock to be removed. The lock token in the Lock-Token 2515 request header MUST identify a lock that contains the resource 2516 identified by Request-URI as a member. 2518 8.6 Overwrite Header 2520 Overwrite = "Overwrite" ":" ("T" | "F") 2522 The Overwrite header specifies whether the server should overwrite 2523 the state of a non-null destination resource during a COPY or MOVE. 2524 A value of "F" states that the server must not perform the COPY or 2525 MOVE operation if the state of the destination resource is non-null. 2527 If the overwrite header is not included in a COPY or MOVE request 2528 then the resource MUST treat the request as if it has an overwrite 2529 header of value "T". While the Overwrite header appears to duplicate 2530 the functionality of the If-Match: * header of HTTP/1.1, If-Match 2531 applies only to the Request-URI, and not to the Destination of a 2532 COPY or MOVE. 2534 If a COPY or MOVE is not performed due to the value of the Overwrite 2535 header, the method MUST fail with a 409 Conflict status code. 2537 All DAV compliant resources MUST support the Overwrite header. 2539 8.7 Status-URI Response Header 2541 The Status-URI response header may be used with the 102 Processing 2542 status code to inform the client as to the status of a method. 2544 Status-URI = "Status-URI" ":" *(Status-Code "<" URI ">") ; Status- 2545 Code is defined in 6.1.1 of [Fielding et al., 1997] 2547 The URIs listed in the header are source resources which have been 2548 affected by the outstanding method. The status code indicates the 2549 resolution of the method on the identified resource. So, for 2550 example, if a MOVE method on a collection is outstanding and a 102 2551 "Processing" response with a Status-URI response header is returned, 2552 the included URIs will indicate resources that have had move 2553 attempted on them and what the result was. 2555 8.8 Timeout Request Header 2557 TimeOut = "Timeout" ":" 1#TimeType 2558 TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other) 2559 DAVTimeOutVal = 1*digit 2560 Other = Extend field-value ; See section 4.2 of [Fielding et al., 2561 1997] 2563 Clients may include Timeout headers in their LOCK requests. 2564 However, the server is not required to honor or even consider these 2565 requests. Clients MUST NOT submit a Timeout request header with any 2566 method other than a LOCK method. 2568 A Timeout request header MUST contain at least one TimeType and may 2569 contain multiple TimeType entries. The purpose of listing multiple 2570 TimeType entries is to indicate multiple different values and value 2571 types that are acceptable to the client. The client lists the 2572 TimeType entries in order of preference. 2574 Timeout response valuse MUST use a Second value, Infinite, or a 2575 TimeType the client has indicated familiarity with. The server may 2576 assume a client is familiar with any TimeType submitted in a Timeout 2577 header. 2579 The "Second" TimeType specifies the number of seconds that will 2580 elapse between granting of the lock at the server, and the automatic 2581 removal of the lock. The timeout value for timetype "Second" MUST 2582 NOT be greater than 2^32-1. 2584 The timeout counter SHOULD be restarted any time an owner of the 2585 lock sends a method to any member of the lock, including unsupported 2586 methods, or methods which are unsuccessful. However the lock MUST 2587 be refreshed if a refresh LOCK method is successfully received. 2589 If the timeout expires then the lock may be lost. Specifically, if 2590 the server wishes to harvest the lock upon time-out, the server 2591 SHOULD act as if an UNLOCK method was executed by the server on the 2592 resource using the lock token of the timed-out lock, performed with 2593 its override authority. Thus logs should be updated with the 2594 disposition of the lock, notifications should be sent, etc., just as 2595 they would be for an UNLOCK request. 2597 Servers are advised to pay close attention to the values submitted 2598 by clients, as they will be indicative of the type of activity the 2599 client intends to perform. For example, an applet running in a 2600 browser may need to lock a resource, but because of the instability 2601 of the environment within which the applet is running, the applet 2602 may be turned off without warning. As a result, the applet is 2603 likely to ask for a relatively small timeout value so that if the 2604 applet dies, the lock can be quickly harvested. However, a document 2605 management system is likely to ask for an extremely long timeout 2606 because its user may be planning on going off-line. 2608 A client MUST NOT assume that just because the time-out has expired 2609 the lock has been lost. 2611 9 Status Code Extensions to HTTP/1.1 2613 The following status codes are added to those defined in HTTP/1.1 2614 [Fielding et al., 1997]. 2616 9.1 102 Processing 2618 Methods can potentially take a long period of time to process, 2619 especially methods that support the Depth header. In such cases the 2620 client may time-out the connection while waiting for a response. To 2621 prevent this the server may return a 102 status code to indicate to 2622 the client that the server is still processing the method. 2624 If a method is taking longer than 20 seconds (a reasonable, but 2625 arbitrary value) to process the server SHOULD return a 102 2626 "Processing" response. 2628 9.2 207 Multi-Status 2630 The response provides status for multiple independent operations. 2632 9.3 422 Unprocessable Entity 2634 The server understands the content type of the request entity, but 2635 was unable to process the contained instructions. 2637 9.4 423 Locked 2639 The source or destination resource of a method is locked. 2641 9.5 424 Method Failure 2643 The method was not executed on a particular resource within its 2644 scope because some part of the method's execution failed causing the 2645 entire method to be aborted. For example, if a command in a 2646 PROPPATCH method fails then, at minimum, the rest of the commands 2647 will also fail with 424 Method Failure. 2649 9.6 425 Insufficient Space on Resource 2651 The resource does not have sufficient space to record the state of 2652 the resource after the execution of this method. 2654 10 Multi-Status Response 2656 The default 207 Multi-Status response body is a text/xml HTTP entity 2657 that contains a single XML element called multistatus, which 2658 contains a set of XML elements called response which contain 200, 2659 300, 400, and 500 series status codes generated during the method 2660 invocation. 100 series status codes SHOULD NOT be recorded in a 2661 response XML element. 2663 11 XML Element Definitions 2665 In the section below, the final line of each section gives the 2666 element type declaration using the format defined in [Bray, Paoli, 2667 Sperberg-McQueen, 1998]. The "Value" field, where present, specifies 2668 futher restrictions on the allowable contents of the XML element 2669 using BNF (i.e., to further restrict the values of a PCDATA 2670 element). 2672 11.1 activelock XML Element 2674 Name: activelock 2675 Namespace: DAV: 2676 Purpose: Describes a lock on a resource. 2678 2681 11.1.1 depth XML Element 2683 Name: depth 2684 Namespace: DAV: 2685 Purpose: The value of the depth header used to create a lock. 2686 Value: "0" | "infinity" 2688 2690 11.1.2 locktoken XML Element 2692 Name: locktoken 2693 Namespace: DAV: 2694 Purpose: The lock token associated with a lock. 2695 Description: The href contains one or more opaque lock token URIs 2696 which all refer to the same lock (i.e., the OpaqueLockToken-URI 2697 production in section 5.4). 2699 2701 11.1.3 timeout XML Element 2703 Name: timeout 2704 Namespace: DAV: 2705 Purpose: The timeout associated with a lock 2706 Value: TimeType ;Defined in section 8.8 2708 2710 11.2 collection XML Element 2712 Name: collection 2713 Namespace: DAV: 2714 Purpose: Identifies the associated resource as a collection. The 2715 resourcetype property of a collection resource MUST have this value. 2717 2719 11.3 href XML Element 2721 Name: href 2722 Namespace: DAV: 2723 Purpose: Identifies the content of the element as a URI. 2724 Value: URI ; See section 3.2.1 of [Fielding et al., 1997] 2726 2728 11.4 link XML Element 2730 Name: link 2731 Namespace: DAV: 2732 Purpose: Identifies the property as a link and contains the 2733 source and destination of that link. 2734 Description: The link XML element is used to provide the sources and 2735 destinations of a link. The name of the property containing the 2736 link XML element provides the type of the link. Link is a multi- 2737 valued element, so multiple links may be used together to indicate 2738 multiple links with the same type. The values in the href XML 2739 elements inside the src and dst XML elements of the link XML element 2740 MUST NOT be rejected if they point to resources which do not exist. 2742 2744 11.4.1 dst XML Element 2746 Name: dst 2747 Namespace: DAV: 2748 Purpose: Indicates the destination of a link 2749 Value: URI 2751 2753 11.4.2 src XML Element 2755 Name: src 2756 Namespace: DAV: 2757 Purpose: Indicates the source of a link. 2759 Value: URI 2761 2763 11.5 lockentry XML Element 2765 Name: lockentry 2766 Namespace: DAV: 2767 Purpose: Defines the types of locks that can be used with the 2768 resource. 2770 2772 11.6 lockinfo XML Element 2774 Name: lockinfo 2775 Namespace: DAV: 2776 Purpose: The lockinfo XML element is used with a LOCK method to 2777 specify the type of lock the client wishes to have created. 2779 2781 11.7 lockscope XML Element 2783 Name: lockscope 2784 Namespace: DAV: 2785 Purpose: Specifies whether a lock is an exclusive lock, or a 2786 shared lock. 2788 2790 11.7.1 exclusive XML Element 2792 Name: exclusive 2793 Namespace: DAV: 2794 Purpose: Specifies an exclusive lock 2796 2798 11.7.2 shared XML Element 2800 Name: shared 2801 Namespace: DAV: 2802 Purpose: Specifies a shared lock 2804 2806 11.8 locktype XML Element 2808 Name: locktype 2809 Namespace: DAV: 2811 Purpose: Specifies the access type of a lock. At present, this 2812 specification only defines one lock type, the write lock. 2814 2816 11.8.1 write XML Element 2818 Name: write 2819 Namespace: DAV: 2820 Purpose: Specifies a write lock. 2822 2824 11.9 multistatus XML Element 2826 Name: multistatus 2827 Namespace: DAV: 2828 Purpose: Contains multiple response messages. 2829 Description: The responsedescription at the top level is used to 2830 provide a general message describing the overarching nature of the 2831 response. If this value is available an application may use it 2832 instead of presenting the individual response descriptions contained 2833 within the responses. 2835 2837 11.9.1 response XML Element 2839 Name: response 2840 Namespace: DAV: 2841 Purpose: Holds a single response describing the effect of a 2842 method on resource and/or its properties. 2843 Description: A particular href MUST NOT appear more than once as the 2844 child of a response XML element under a multistatus XML element. 2845 This requirement is necessary in order to keep processing costs for 2846 a response to linear time. Essentially, this prevents having to 2847 search in order to group together all the responses by href. There 2848 are, however, no requirements regarding ordering based on href 2849 values. 2851 2854 11.9.1.1 propstat XML Element 2856 Name: propstat 2857 Namespace: DAV: 2858 Purpose: Groups together a prop and status element that is 2859 associated with a particular href element. 2860 Description: The propstat XML element MUST contain one prop XML 2861 element and one status XML element. The contents of the prop XML 2862 element MUST only list the names of properties to which the result 2863 in the status element applies. 2865 2867 11.9.1.2 status XML Element 2869 Name: status 2870 Namespace: DAV: 2871 Purpose: Holds a single HTTP status-line 2872 Value: status-line ;status-line defined in [Fielding et al., 2873 1997] 2875 2877 11.9.2 responsedescription XML Element 2879 Name: responsedescription 2880 Namespace: DAV: 2881 Purpose: Contains a message that can be displayed to the user 2882 explaining the nature of the response. 2883 Description: This XML element provides information suitable to be 2884 presented to a user. 2886 2888 11.10 owner XML Element 2890 Name: owner 2891 Namespace: DAV: 2892 Purpose: Provides information about the principal taking out a 2893 lock. 2894 Description: The owner XML element provides information sufficient 2895 for either directly contacting a principal (such as a telephone 2896 number or Email URI), or for discovering the principal (such as the 2897 URL of a homepage) who owns a lock. 2899 2901 11.11 prop XML element 2903 Name: prop 2904 Namespace: DAV: 2905 Purpose: Contains properties related to a resource. 2906 Description: The prop XML element is a generic container for 2907 properties defined on resources. All elements inside a prop XML 2908 element MUST define properties related to the resource. No other 2909 elements may be used inside of a prop element. 2911 2913 11.12 propertybehavior XML element 2915 Name: propertybehavior 2916 Namespace: DAV: 2917 Purpose: Specifies how properties are handled during a COPY or 2918 MOVE. 2919 Description: The propertybehavior XML element specifies how 2920 properties are handled during a COPY or MOVE. If this XML element 2921 is not included in the request body then the server is expected to 2922 act as defined by the default property handling behavior of the 2923 associated method. All WebDAV compliant resources MUST support the 2924 propertybehavior XML element. 2926 2928 11.12.1 keepalive XML element 2930 Name: keepalive 2931 Namespace: DAV: 2932 Purpose: Specifies requirements for the copying/moving of live 2933 properties. 2934 Description: If a list of URIs is included as the value of keepalive 2935 then the named properties MUST be "live" after they are copied 2936 (moved) to the destination resource of a COPY (or MOVE). If the 2937 value "*" is given for the keepalive XML element, this designates 2938 that all live properties on the source resource MUST be live on the 2939 destination. If the requirements specified by the keepalive element 2940 can not be honored then the method MUST fail with a 412 Precondition 2941 Failed. All DAV compliant resources MUST support the keepalive XML 2942 element for use with the COPY and MOVE methods. 2943 Value: "*" ; #PCDATA value can only be "*" 2945 2947 11.12.2 omit XML element 2949 Name: omit 2950 Namespace: DAV: 2951 Purpose: The omit XML element instructs the server that it should 2952 use best effort to copy properties but a failure to copy a property 2953 MUST NOT cause the method to fail. 2954 Description: The default behavior for a COPY or MOVE is to copy/move 2955 all properties or fail the method. In certain circumstances, such 2956 as when a server copies a resource over another protocol such as 2957 FTP, it may not be possible to copy/move the properties associated 2958 with the resource. Thus any attempt to copy/move over FTP would 2959 always have to fail because properties could not be moved over, even 2960 as dead properties. All DAV compliant resources MUST support the 2961 omit XML element on COPY/MOVE methods. 2963 2965 11.13 propertyupdate XML element 2967 Name: propertyupdate 2968 Namespace: DAV: 2969 Purpose: Contains a request to alter the properties on a 2970 resource. 2971 Description: This XML element is a container for the information 2972 required to modify the properties on the resource. This XML element 2973 is multi-valued. 2975 2977 11.13.1 remove XML element 2979 Name: remove 2980 Namespace: DAV: 2981 Purpose: Lists the DAV properties to be removed from a resource. 2982 Description: Remove instructs that the properties specified in prop 2983 should be removed. Specifying the removal of a property that does 2984 not exist is not an error. All the XML elements in a prop XML 2985 element inside of a remove XML element MUST be empty, as only the 2986 names of properties to be removed are required. 2988 2990 11.13.2 set XML element 2992 Name: set 2993 Namespace: DAV: 2994 Purpose: Lists the DAV property values to be set for a resource. 2995 Description: The set XML element MUST contain only a prop XML 2996 element. The elements contained by the prop XML element inside the 2997 set XML element MUST specify the name and value of properties that 2998 are set on the Request-URI. If a property already exists then its 2999 value is replaced. 3001 3003 11.14 propfind XML Element 3005 Name: propfind 3006 Namespace: DAV: 3007 Purpose: Specifies the properties to be returned from a PROPFIND 3008 method. Two special elements are specified for use with propfind, 3009 allprop and propname. If prop is used inside propfind it MUST only 3010 contain property names, not values. 3012 3014 11.14.1 allprop XML Element 3016 Name: allprop 3017 Namespace: DAV: 3018 Purpose: The allprop XML element specifies that all property 3020 names and values on the resource are to be returned. 3022 3024 11.14.2 propname XML Element 3026 Name: propname 3027 Namespace: DAV: 3028 Purpose: The propname XML element specifies that only a list of 3029 property names on the resource is to be returned. 3031 3033 12 DAV Properties 3035 For DAV properties, the name of the property is also the same as the 3036 name of the XML element that contains its value. In the section 3037 below, the final line of each section gives the element type 3038 declaration using the format defined in [Bray, Paoli, Sperberg- 3039 McQueen, 1998]. The "Value" field, where present, specifies futher 3040 restrictions on the allowable contents of the XML element using BNF 3041 (i.e., to further restrict the values of a PCDATA element). 3043 12.1 creationdate Property 3045 Name: creationdate 3046 Namespace: DAV: 3047 Purpose: Records the time and date the resource was created. 3048 Value: date-time ; See Appendix 2 3049 Description: The creationdate property should be defined on all DAV 3050 compliant resources. If present, it contains a timestamp of the 3051 moment when the resource was created (i.e., the moment it had non- 3052 null state). 3054 3056 12.2 displayname Property 3058 Name: displayname 3059 Namespace: DAV: 3060 Purpose: Provides a name for the resource that is suitable for 3061 presentation to a user. 3062 Description: The displayname property should be defined on all DAV 3063 compliant resources. If present, the property contains a 3064 description of the resource that is suitable for presentation to a 3065 user. 3067 3069 12.3 getcontentlanguage Property 3071 Name: getcontentlanguage 3072 Namespace: DAV: 3073 Purpose: Contains the Content-Language header returned by a GET 3074 without accept headers 3075 Description: The getcontentlanguage property MUST be defined on any 3076 DAV compliant resource that returns the Content-Language header on a 3077 GET. 3078 Value: language-tag ;language-tag is defined in section 14.13 3079 of [Fielding et al., 1997] 3081 3083 12.4 getcontentlength Property 3085 Name: getcontentlength 3086 Namespace: DAV: 3087 Purpose: Contains the Content-Length header returned by a GET 3088 without accept headers. 3089 Description: The getcontentlength property MUST be defined on any 3090 DAV compliant resource that returns the Content-Length header in 3091 response to a GET. 3092 Value: content-length ; see section 14.14 of [Fielding et al., 3093 1997] 3095 3097 12.5 getcontenttype Property 3099 Name: getcontenttype 3100 Namespace: DAV: 3101 Purpose: Contains the Content-Type header returned by a GET 3102 without accept headers. 3103 Description: This getcontenttype property MUST be defined on any DAV 3104 compliant resource that returns the Content-Type header in response 3105 to a GET. 3106 Value: media-type ; defined in section 3.7 of [Fielding et 3107 al., 1997] 3109 3111 12.6 getetag Property 3113 Name: getetag 3114 Namespace: DAV: 3115 Purpose: Contains the ETag header returned by a GET without 3116 accept headers. 3117 Description: Note that the ETag on a resource may reflect changes in 3118 any part of the state of the resource, not necessarily just a change 3119 to the response to the GET method. For example, a change to a 3120 resource's access permissions may cause the ETag to change. The 3121 getetag property MUST be defined on any DAV compliant resource that 3122 returns the Etag header in response to a GET. 3123 Value: entity-tag ; defined in section 3.11 of [Fielding et 3124 al., 1997] 3126 3128 12.7 getlastmodified Property 3130 Name: getlastmodified 3131 Namespace: DAV: 3132 Purpose: Contains the Last-Modified header returned by a GET 3133 method without accept headers. 3134 Description: Note that the last-modified date on a resource may 3135 reflect changes in any part of the state of the resource, not 3136 necessarily just a change to the response to the GET method. For 3137 example, a change in a property may cause the last-modified date to 3138 change. The getlastmodified property MUST be defined on any DAV 3139 compliant resource that returns the Last-Modified header in response 3140 to a GET. 3141 Value: HTTP-date ; defined in section 3.3.1 of [Fielding et 3142 al., 1997] 3144 3146 12.8 lockdiscovery Property 3148 Name: lockdiscovery 3149 Namespace: DAV: 3150 Purpose: Describes the active locks on a resource 3151 Description: The lockdiscovery property returns a listing of who has 3152 a lock, what type of lock he has, the timeout type and the time 3153 remaining on the timeout, and the associated lock token. The server 3154 is free to withhold any or all of this information if the requesting 3155 principal does not have sufficient access rights to see the 3156 requested data. 3158 3160 12.8.1 Example - Retrieving the lockdiscovery Property 3162 >>Request 3164 PROPFIND /container/ HTTP/1.1 3165 Host: www.foo.bar 3166 Content-Length: xxxx 3167 Content-Type: text/xml 3169 3170 3171 3172 3173 3175 >>Response 3177 HTTP/1.1 207 Multi-Status 3178 Content-Type: text/xml 3179 Content-Length: xxxxx 3181 3182 3183 3184 3185 http://www.foo.bar/container/ 3186 3187 3188 3189 3190 3191 3192 0 3193 Jane Smith 3194 Infinite 3195 3196 3197 opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76 3198 3199 3200 3201 3202 3203 HTTP/1.1 200 OK 3204 3205 3206 3208 This resource has a single exclusive write lock on it, with an 3210 infinite timeout. 3212 12.9 resourcetype Property 3214 Name: resourcetype 3215 Namespace: DAV: 3216 Purpose: Specifies the nature of the resource. 3217 Description: The resourcetype property MUST be defined on all DAV 3218 compliant resources. The default value is empty. 3220 3222 12.10 source Property 3224 Name: source 3225 Namespace: DAV: 3226 Purpose: The destination of the source link identifies the 3227 resource that contains the unprocessed source of the link's source. 3228 Description: The source of the link (src) is typically the URI of 3229 the output resource on which the link is defined, and there is 3230 typically only one destination (dst) of the link, which is the URI 3231 where the unprocessed source of the resource may be accessed. When 3232 more than one link destination exists, this specification asserts no 3233 policy on ordering. 3235 3237 12.10.1 Example - A source Property 3239 3240 3241 3242 3244 3245 3246 Source 3247 http://foo.bar/program 3248 http://foo.bar/src/main.c 3249 3250 3251 Library 3252 http://foo.bar/program 3253 http://foo.bar/src/main.lib 3254 3255 3256 Makefile 3257 http://foo.bar/program 3258 http://foo.bar/src/makefile 3259 3260 3261 3263 In this example the resource http://foo.bar/program has a source 3264 property that contains three links. Each link contains three 3265 elements, two of which, src and dst, are part of the DAV schema 3266 defined in this document, and one which is defined by the schema 3267 http://www.foocorp.com/project/ (Source, Library, and Makefile). A 3268 client which only implements the elements in the DAV spec will not 3269 understand the foocorp elements and will ignore them, thus seeing 3270 the expected source and destination links. An enhanced client may 3271 know about the foocorp elements and be able to present the user with 3272 additional information about the links. This example demonstrates 3273 the power of XML markup, allowing element values to be enhanced 3274 without breaking older clients. 3276 12.11 supportedlock Property 3278 Name: supportedlock 3279 Namespace: DAV: 3280 Purpose: To provide a listing of the lock capabilities supported 3281 by the resource. 3282 Description: The supportedlock property of a resource returns a 3283 listing of the combinations of scope and access types which may be 3284 specified in a lock request on the resource. Note that the actual 3285 contents are themselves controlled by access controls so a server is 3286 not required to provide information the client is not authorized to 3287 see. 3289 3291 12.11.1 Example - Retrieving the supportedlock Property 3293 >>Request 3295 PROPFIND /container/ HTTP/1.1 3296 Host: www.foo.bar 3297 Content-Length: xxxx 3298 Content-Type: text/xml 3300 3301 3302 3303 3304 3305 >>Response 3307 HTTP/1.1 207 Multi-Status 3308 Content-Type: text/xml 3309 Content-Length: xxxxx 3311 3312 3313 3314 3315 http://www.foo.bar/container/ 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 HTTP/1.1 200 OK 3330 3331 3332 3334 13 DAV XML Processing Instructions 3336 All DAV compliant resources MUST ignore any unknown XML element and 3337 all its children encountered while processing a DAV method that uses 3338 XML as its command language. 3340 This restriction also applies to the processing, by clients, of DAV 3341 property values where unknown XML elements SHOULD be ignored unless 3342 the property's schema declares otherwise. 3344 This restriction does not apply to setting dead DAV properties on 3345 the server where the server MUST record unknown XML elements. 3347 Additionally, this restriction does not apply to the use of XML 3348 where XML happens to be the content type of the entity body, for 3349 example, when used as the body of a PUT. 3351 14 DAV Compliance Classes 3353 A DAV compliant resource can choose from two classes of compliance. 3354 A client can discover the compliance classes of a resource by 3355 executing OPTIONS on the resource, and examining the "DAV" header 3356 which is returned. 3358 Since this document describes extensions to the HTTP/1.1 protocol, 3359 minimally all DAV compliant resources, clients, and proxies MUST be 3360 compliant with [Fielding et al., 1997]. 3362 Compliance classes are not necessarily sequential. A resource that 3363 is class 2 compliant must also be class 1 compliant; but if 3364 additional compliance classes are defined later, a resource that is 3365 class 1, 2, and 4 compliant might not be class 3 compliant. Also 3366 note that identifiers other than numbers may be used as compliance 3367 class identifiers. 3369 14.1 Class 1 3371 A class 1 compliant resource MUST meet all "MUST" requirements in 3372 all sections of this document. 3374 Class 1 compliant resources MUST return, at minimum, the value "1" 3375 in the DAV header on all responses to the OPTIONS method. 3377 14.2 Class 2 3379 A class 2 compliant resource MUST meet all class 1 requirements and 3380 support the LOCK method, the supportedlock property, the 3381 lockdiscovery property, the Time-Out response header and the Lock- 3382 Token request header. A class "2" compliant resource SHOULD also 3383 support the Time-Out request header and the owner XML element. 3385 Class 2 compliant resources MUST return, at minimum, the values "1" 3386 and "2" in the DAV header on all responses to the OPTIONS method. 3388 15 Internationalization Considerations 3390 In the realm of internationalization, this specification complies 3391 with the IETF Character Set Policy [Alvestrand, 1998]. In this 3392 specification, human-readable fields can be found either in the 3393 value of a property, or in an error message returned in a response 3394 entity body. In both cases, the human-readable content is encoded 3395 using XML, which has explicit provisions for character set tagging 3396 and encoding, and requires that XML processors read XML elements 3397 encoded, at minimum, using the UTF-8 [Yergeau, 1998] encoding of the 3398 ISO 10646 multilingual plane. 3400 XML also provides a language tagging capability for specifying the 3401 language of the contents of a particular XML element. XML uses 3402 either IANA registered language tags (see RFC 1766, [Alvestrand, 3403 1995]) or ISO 639 language tags [ISO-639] in the "xml:lang" 3404 attribute of an XML element to identify the language of its content 3405 and attributes. 3407 WebDAV applications MUST support the character set tagging, 3408 character set encoding, and the language tagging functionality of 3409 the XML specification. 3411 Names used within this specification fall into three categories: 3412 names of protocol elements such as methods and headers, names of XML 3413 elements, and names of properties. Naming of protocol elements 3414 follows the precedent of HTTP, using English names encoded in 3415 USASCII for methods and headers. Since these protocol elements are 3416 not visible to users, and are in fact simply long token identifiers, 3417 they do not need to support encoding in multiple character sets. 3418 Similarly, though the names of XML elements used in this 3419 specification are English names encoded in UTF-8, these names are 3420 not visible to the user, and hence do not need to support multiple 3421 character set encodings. 3423 The name of a property defined on a resource is a URI. Although 3424 some applications (e.g., a generic property viewer) will display 3425 property URIs directly to their users, it is expected that the 3426 typical application will use a fixed set of properties, and will 3427 provide a mapping from the property name URI to a human-readable 3428 field when displaying the property name to a user. It is only in 3429 the case where the set of properties is not known ahead of time that 3430 an application need display a property name URI to a user. We 3431 recommend that applications provide human-readable property names 3432 wherever feasible. 3434 For error reporting, we follow the convention of HTTP/1.1 status 3435 codes, including with each status code a short, English description 3437 of the code (e.g., 423 Locked). While the possibility exists that a 3438 poorly crafted user agent would display this message to a user, 3439 internationalized applications will ignore this message, and display 3440 an appropriate message in the user's language and character set. 3442 Since interoperation of clients and servers does not require locale 3443 information, this specification does not specify any mechanism for 3444 transmission of this information. 3446 16 Security Considerations 3448 This section is provided to detail issues concerning security 3449 implications of which WebDAV applications need to be aware. 3451 All of the security considerations of HTTP/1.1 also apply to WebDAV. 3452 In addition, the security risks inherent in remote authoring require 3453 stronger authentication technology, introduce several new privacy 3454 concerns, and may increase the hazards from poor server design. 3455 These issues are detailed below. 3457 16.1 Authentication of Clients 3458 Due to their emphasis on authoring, WebDAV servers need to use 3459 authentication technology to protect not just access to a network 3460 resource, but the integrity of the resource as well. Furthermore, 3461 the introduction of locking functionality requires support for 3462 authentication. 3464 A password sent in the clear over an insecure channel is an 3465 inadequate means for protecting the accessibility and integrity of a 3466 resource as the password may be intercepted. Since Basic 3467 authentication for HTTP/1.1 performs essentially clear text 3468 transmission of a password, Basic authentication MUST NOT be used to 3469 authenticate a WebDAV client to a server unless the connection is 3470 secure. Furthermore, a WebDAV server MUST NOT send Basic 3471 authentication credentials in a WWW-Authenticate header unless the 3472 connection is secure. Examples of secure connections include a 3473 Transport Layer Security (TLS) connection, or a connection over a 3474 network which is physically secure, for example, an isolated network 3475 in a building with restricted access. 3477 WebDAV applications MUST support the Digest authentication scheme 3478 [Franks et al., 1997]. Since Digest authentication verifies that 3479 both parties to a communication know a shared secret, a password, 3480 without having to send that secret in the clear, Digest 3481 authentication avoids the security problems inherent in Basic 3482 authentication while providing a level of authentication which is 3483 useful in a wide range of scenarios. 3485 16.2 Denial of Service 3487 Denial of service attacks are of special concern to WebDAV servers. 3488 WebDAV plus HTTP enables denial of service attacks on every part of 3489 a system's resources. 3491 The underlying storage can be attacked by PUTting extremely large 3492 files. 3494 Asking for recursive operations on large collections can attack 3495 processing time. 3497 Making multiple pipelined requests on multiple connections can 3498 attack network connections. 3500 WebDAV servers need to be aware of the possibility of a denial of 3501 service attack at all levels. 3503 16.3 Security through Obscurity 3505 WebDAV provides, through the PROPFIND method, a mechanism for 3506 listing the member resources of a collection. This greatly 3507 diminishes the effectiveness of security or privacy techniques that 3508 rely only on the difficulty of discovering the names of network 3509 resources. Users of WebDAV servers are encouraged to use access 3510 control techniques to prevent unwanted access to resources, rather 3511 than depending on the relative obscurity of their resource names. 3513 16.4 Privacy Issues Connected to Locks 3515 When submitting a lock request a user agent may also submit an owner 3516 XML field giving contact information for the person taking out the 3517 lock (for those cases where a person, rather than a robot, is taking 3518 out the lock). This contact information is stored in a lockdiscovery 3519 property on the resource, and can be used by other collaborators to 3520 begin negotiation over access to the resource. However, in many 3521 cases this contact information can be very private, and should not 3522 be widely disseminated. Servers SHOULD limit read access to the 3523 lockdiscovery property as appropriate. Furthermore, user agents 3524 SHOULD provide control over whether contact information is sent at 3525 all, and if contact information is sent, control over exactly what 3526 information is sent. 3528 16.5 Privacy Issues Connected to Properties 3530 Since property values are typically used to hold information such as 3531 the author of a document, there is the possibility that privacy 3532 concerns could arise stemming from widespread access to a resource's 3533 property data. To reduce the risk of inadvertent release of private 3534 information via properties, servers are encouraged to develop access 3535 control mechanisms that separate read access to the resource body 3536 and read access to the resource's properties. This allows a user to 3537 control the dissemination of their property data without overly 3538 restricting access to the resource's contents. 3540 16.6 Reduction of Security due to Source Link 3542 HTTP/1.1 warns against providing read access to script code because 3543 it may contain sensitive information. Yet WebDAV, via its source 3544 link facility, can potentially provide a URL for script resources so 3545 they may be authored. For HTTP/1.1, a server could reasonably 3546 prevent access to source resources due to the predominance of read- 3547 only access. WebDAV, with its emphasis on authoring, encourages 3548 read and write access to source resources, and provides the source 3549 link facility to identify the source. This reduces the security 3550 benefits of eliminating access to source resources. Users and 3551 administrators of WebDAV servers should be very cautious when 3552 allowing remote authoring of scripts, limiting read and write access 3553 to the source resources to authorized principals. 3555 17 IANA Considerations 3557 This document defines two namespaces, the namespace of property 3558 names, and the namespace of WebDAV-specific XML elements used within 3559 property values. 3561 URLs are used for both names, for several reasons. Assignment of a 3562 URL does not require a request to a central naming authority, and 3563 hence allow WebDAV property names and XML elements to be quickly 3564 defined by any WebDAV user or application. URLs also provide a 3565 unique address space, ensuring that the distributed users of WebDAV 3566 will not have collisions among the property names and XML elements 3567 they create. 3569 This specification defines a distinguished set of property names and 3570 XML elements that are understood by all WebDAV applications. The 3571 property names and XML elements in this specification are all 3572 derived from the base URI DAV: by adding a suffix to this URI, for 3573 example, DAV:creationdate for the "creationdate" property. 3575 This specification also defines a URI scheme for the encoding of 3576 lock tokens, the opaquelocktoken URI scheme described in section 3577 5.4. 3579 To ensure correct interoperation based on this specification, IANA 3580 must reserve the URI namespaces starting with "DAV:" and with 3581 "opaquelocktoken:" for use by this specification, its revisions, and 3582 related WebDAV specifications. 3584 18 Terminology 3586 Collection - A resource that contains member resources and meets the 3587 requirements in section 4 of this specification. 3589 Member Resource - A resource contained by a collection. 3591 Internal Member Resource - A member resource of a collection whose 3592 URI is relative to the URI of the collection. 3594 Property - A name/value pair that contains descriptive information 3595 about a resource. 3597 Live Property - A property whose semantics and syntax are enforced 3598 by the server. For example, a live "content-length" property would 3599 have its value, the length of the entity returned by a GET request, 3600 automatically calculated by the server. 3602 Dead Property - A property whose semantics and syntax are not 3603 enforced by the server. The server only records the value of a dead 3604 property; the client is responsible for maintaining the consistency 3605 of the syntax and semantics of a dead property. 3607 Null Resource - A resource which responds with a 404 Not Found to 3608 any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK. 3609 A NULL resource MUST NOT appear as a member of its parent 3610 collection. 3612 19 Copyright 3614 The following copyright notice is copied from RFC 2026 [Bradner, 3615 1996], section 10.4, and describes the applicable copyright for this 3616 document. 3618 Copyright (C) The Internet Society April 5, 1998. All Rights 3619 Reserved. 3621 This document and translations of it may be copied and furnished to 3622 others, and derivative works that comment on or otherwise explain it 3623 or assist in its implementation may be prepared, copied, published 3624 and distributed, in whole or in part, without restriction of any 3625 kind, provided that the above copyright notice and this paragraph 3626 are included on all such copies and derivative works. However, this 3627 document itself may not be modified in any way, such as by removing 3628 the copyright notice or references to the Internet Society or other 3629 Internet organizations, except as needed for the purpose of 3630 developing Internet standards in which case the procedures for 3631 copyrights defined in the Internet Standards process must be 3632 followed, or as required to translate it into languages other than 3633 English. 3635 The limited permissions granted above are perpetual and will not be 3636 revoked by the Internet Society or its successors or assignees. 3638 This document and the information contained herein is provided on an 3639 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3640 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3641 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3642 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3643 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3645 20 Intellectual Property 3647 The following notice is copied from RFC 2026 [Bradner, 1996], 3648 section 10.4, and describes the position of the IETF concerning 3649 intellectual property claims made against this document. 3651 The IETF takes no position regarding the validity or scope of any 3652 intellectual property or other rights that might be claimed to 3653 pertain to the implementation or use other technology described in 3654 this document or the extent to which any license under such rights 3655 might or might not be available; neither does it represent that it 3656 has made any effort to identify any such rights. Information on the 3657 IETF's procedures with respect to rights in standards-track and 3658 standards-related documentation can be found in BCP-11. Copies of 3659 claims of rights made available for publication and any assurances 3660 of licenses to be made available, or the result of an attempt made 3661 to obtain a general license or permission for the use of such 3662 proprietary rights by implementors or users of this specification 3663 can be obtained from the IETF Secretariat. 3665 The IETF invites any interested party to bring to its attention any 3666 copyrights, patents or patent applications, or other proprietary 3667 rights which may cover technology that may be required to practice 3668 this standard. Please address the information to the IETF Executive 3669 Director. 3671 21 Acknowledgements 3673 A specification such as this thrives on piercing critical review and 3674 withers from apathetic neglect. The authors gratefully acknowledge 3675 the contributions of the following people, whose insights were so 3676 valuable at every stage of our work. 3678 Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan 3679 Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners- 3680 Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith 3681 Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee 3682 Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan 3683 Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis 3684 Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van 3685 der Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, 3686 Steven Martin, Larry Masinter, Michael Mealling, Keith Moore, Henrik 3687 Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff, Saveen 3688 Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike 3689 Spreitzer, Einar Stefferud, Ralph Swick, Kenji Takahashi, Richard N. 3690 Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran, Fabio 3691 Vitali, Gregory Woodhouse, and Lauren Wood. 3693 Two from this list deserve special mention. The contributions by 3694 Larry Masinter have been invaluable, both in helping the formation 3695 of the working group and in patiently coaching the authors along the 3696 way. In so many ways he has set high standards we have toiled to 3697 meet. The contributions of Judith Slein in clarifying the 3698 requirements, and in patiently reviewing draft after draft, both 3699 improved this specification and expanded our minds on document 3700 management. 3702 We would also like to thank John Turner for developing the XML DTD. 3704 22 References 3706 22.1 Normative References 3708 [Alvestrand, 1995] H. T. Alvestrand, "Tags for the Identification of 3709 Languages." RFC 1766. Uninett. March, 1995. 3711 [Alvestrand, 1998] H. T. Alvestrand, "IETF Policy on Character Sets 3712 and Languages." RFC 2277, BCP 18. Uninett. January, 1998. 3714 [Bradner, 1997] S. Bradner, "Key words for use in RFCs to Indicate 3715 Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 3716 1997. 3718 [Bray, Paoli, Sperberg-McQueen, 1998] T. Bray, J. Paoli, C. M. 3719 Sperberg-McQueen, "Extensible Markup Language (XML)." World Wide Web 3720 Consortium Recommendation REC-xml-19980210. 3721 http://www.w3.org/TR/1998/REC-xml-19980210. 3723 [Franks et al., 1997] J. Franks, P. Hallam-Baker, J. Hostetler, P. 3724 Leach, A. Luotonen, E. Sink, and L. Stewart. "An Extension to HTTP : 3725 Digest Access Authentication" RFC 2069. Northwestern University, 3726 CERN, Spyglass Inc., Microsoft Corp., Netscape Communications Corp., 3727 Spyglass Inc., Open Market Inc. January 1997. 3729 [Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H. 3730 Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." 3731 RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997. 3733 [ISO-639] ISO (International Organization for Standardization). ISO 3734 639:1988. "Code for the representation of names of languages." 3736 [ISO-8601] ISO (International Organization for Standardization). ISO 3737 8601:1988. "Data elements and interchange formats - Information 3738 interchange - Representation of dates and times." 3740 [Leach, Salz, 1998] P. J. Leach, R. Salz, "UUIDs and GUIDs." 3741 Internet-draft, work-in-progress, February, 1998. 3742 ftp://ietf.org/internet-drafts/draft-leach-uuids-guids-01.txt 3744 [Yergeau, 1998] F. Yergeau, "UTF-8, a transformation format of 3745 Unicode and ISO 10646." RFC 2279. Alis Technologies. January, 1998. 3747 22.2 Informational References 3749 [Bradner, 1996] S. Bradner, "The Internet Standards Process - 3750 Revision 3." RFC 2026, BCP 9. Harvard University. October, 1996. 3752 [Bray, Hollander, Layman, 1998] T. Bray, D. Hollander, A. Layman, 3753 "Name Spaces in XML" World Wide Web Consortium Working Draft, 3754 http://www.w3.org/TR/WD-xml-names. 3756 [Lasher, Cohen, 1995] R. Lasher, D. Cohen, "A Format for 3757 Bibliographic Records," RFC 1807. Stanford, Myricom. June, 1995. 3759 [MARC, 1994] Network Development and MARC Standards, Office, ed. 3760 1994. "USMARC Format for Bibliographic Data", 1994. Washington, DC: 3761 Cataloging Distribution Service, Library of Congress. 3763 [Miller et al., 1996] J. Miller, T. Krauskopf, P. Resnick, W. 3764 Treese, "PICS Label Distribution Label Syntax and Communication 3765 Protocols" Version 1.1, World Wide Web Consortium Recommendation 3766 REC-PICS-labels-961031. http://www.w3.org/pub/WWW/TR/REC-PICS- 3767 labels-961031.html. 3769 [Slein et al., 1998] J. A. Slein, F. Vitali, E. J. Whitehead, Jr., 3770 D. Durand, "Requirements for Distributed Authoring and Versioning 3771 Protocol for the World Wide Web." RFC 2291. Xerox, Univ. of Bologna, 3772 U.C. Irvine, Boston Univ. February, 1998. 3774 [Weibel et al., 1995] S. Weibel, J. Godby, E. Miller, R. Daniel, 3775 "OCLC/NCSA Metadata Workshop Report." 3776 http://purl.oclc.org/metadata/dublin_core_report. 3778 23 Authors' Addresses 3780 Y. Y. Goland 3781 Microsoft Corporation 3782 One Microsoft Way 3783 Redmond, WA 98052-6399 3784 Email: yarong@microsoft.com 3786 E. J. Whitehead, Jr. 3787 Dept. Of Information and Computer Science 3788 University of California, Irvine 3789 Irvine, CA 92697-3425 3790 Email: ejw@ics.uci.edu 3792 A. Faizi 3793 Netscape 3794 685 East Middlefield Road 3795 Mountain View, CA 94043 3796 Email: asad@netscape.com 3798 S. R. Carter 3799 Novell 3800 1555 N. Technology Way 3801 M/S ORM F111 3802 Orem, UT 84097-2399 3803 Email: srcarter@novell.com 3805 D. Jensen 3806 Novell 3807 1555 N. Technology Way 3808 M/S ORM F111 3809 Orem, UT 84097-2399 3810 Email: dcjensen@novell.com 3812 24 Appendices 3814 24.1 Appendix 1 - WebDAV Document Type Definition 3816 This section provides a document type definition, following the 3817 rules in [Bray, Paoli, Sperberg-McQueen, 1998], for the XML elements 3818 used in the protocol stream and in the values of properties. It 3819 collects the element definitions given in sections 11 and 12. 3821 3825 3828 3829 3831 3832 3834 3835 3836 3838 3840 3842 3844 3846 3848 3849 3850 3852 3854 3856 3857 3858 3860 3862 3863 3864 3866 3867 3868 3870 3871 3872 3874 3876 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3890 ]> 3892 24.2 Appendix 2 - ISO 8601 Date and Time Profile 3894 The creationdate property specifies the use of the ISO 8601 date 3895 format [ISO-8601]. This section defines a profile of the ISO 8601 3896 date format for use with this specification. This profile is quoted 3897 verbatim from draft-newman-datetime-01.txt (expired). 3899 date-time = full-date "T" full-time 3901 full-date = date-fullyear "-" date-month "-" date-mday 3902 full-time = partial-time time-offset 3904 date-fullyear = 4DIGIT 3905 date-month = 2DIGIT ; 01-12 3906 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on 3907 month/year 3908 time-hour = 2DIGIT ; 00-23 3909 time-minute = 2DIGIT ; 00-59 3910 time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules 3911 time-secfrac = "." 1*DIGIT 3912 time-numoffset = ("+" / "-") time-hour ":" time-minute 3913 time-offset = "Z" / time-numoffset 3915 partial-time = time-hour ":" time-minute ":" time-second 3917 [time-secfrac] 3919 Numeric offsets are calculated as local time minus UTC (Coordinated 3920 Universal Time). So the equivalent time in UTC can be determined by 3921 subtracting the offset from the local time. For example, 18:50:00- 3922 04:00 is the same time as 22:58:00Z. 3924 If the time in UTC is known, but the offset to local time is 3925 unknown, this can be represented with an offset of "-00:00". This 3926 differs from an offset of "Z" which implies that UTC is the 3927 preferred reference point for the specified time. 3929 24.3 Appendix 3 - Notes on Processing XML Elements 3931 24.3.1 Notes on Empty XML Elements 3933 XML supports two mechanisms for indicating that an XML element does 3934 not have any content. The first is to declare an XML element of the 3935 form . The second is to declare an XML element of the form 3936 . The two XML elements are semantically identical. 3938 It is a violation of the XML specification to use the form 3939 if the associated DTD declares the element to be EMPTY (e.g., 3940 ). If such a statement is included, then the 3941 empty element format, must be used. If the element is not 3942 delcared to be EMPTY, then either form or may be used 3943 for empty elements. 3945 24.3.2 Notes on Illegal XML Processing 3947 XML is a flexible data format that makes it easy to submit data that 3948 appears legal but in fact is not. The philosophy of "Be flexible in 3949 what you accept and strict in what you send" still applies, but it 3950 must not be applied inappropriately. XML is extremely flexible in 3951 dealing with issues of white space, element ordering, inserting new 3952 elements, etc. This flexibility does not require extension, 3953 especially not in the area of the meaning of elements. 3955 There is no kindness in accepting illegal combinations of XML 3956 elements. At best it will cause an unwanted result and at worst it 3957 can cause real damage. 3959 24.3.2.1 Example - XML Syntax Error 3961 The following request body for a PROPFIND method is illegal. 3963 3964 3965 3966 3967 3968 3969 The definition of the propfind element only allows for the allprop 3970 or the propname element, not both. Thus the above is an error and 3971 must be responded to with a 400 Bad Request. 3973 Imagine, however, that a server wanted to be "kind" and decided to 3974 pick the allprop element as the true element and respond to it. A 3975 client running over a bandwidth limited line who intended to execute 3977 a propname would be in for a big surprise if the server treated the 3978 command as an allprop. 3980 Additionally, if a server were lenient and decided to reply to this 3981 request, the results would vary randomly from server to server, with 3982 some servers executing the allprop directive, and others executing 3983 the propname directive. This reduces interoperability rather than 3984 increasing it. 3986 24.3.2.2 Example - Unknown XML Element 3988 The previous example was illegal because it contained two elements 3989 that were explicitly banned from appearing together in the propfind 3990 element. However, XML is an extensible language, so one can imagine 3991 new elements being defined for use with propfind. Below is the 3992 request body of a PROPFIND and, like the previous example, must be 3993 rejected with a 400 Bad Request by a server that does not understand 3994 the expired-props element. 3996 3997 3998 4000 4001 4002 4004 To understand why a 400 Bad Request is returned let us look at the 4005 request body as the server unfamiliar with expired-props sees it. 4007 4008 4009 4011 4012 4014 As the server does not understand the expired-props element, by the 4015 rules of XML, it must ignore it. Thus the server sees an empty 4016 propfind, which by the definition of the propfind element is 4017 illegal. 4019 Please note that had the extension been additive it would not 4020 necessarily have resulted in a 400 Bad Request. For example, 4021 imagine the following request body for a PROPFIND: 4023 4024 4025 4027 4028 4029 *boss* 4030 4032 The previous example contains the fictitious element leave-out. Its 4033 purpose is to prevent the return of any property whose name matches 4034 the submitted pattern. If the previous example were submitted to a 4035 server unfamiliar with leave-out, the only result would be that the 4036 leave-out element would be ignored and a propname would be executed. 4038 24.4 Appendix 4 -- XML Namespaces for WebDAV 4040 24.4.1 Introduction 4042 To provide a unique space of XML element names which has 4043 decentralized extensibility, this specification uses a feature of 4044 XML known as XML "namespaces". This appendix provides a normative 4045 reference for XML namespace functionality for implementations of 4046 this specification. All DAV compliant systems MUST support the XML 4047 namespace extension as specified in this appendix. 4049 The remainder of this appendix is intended to match, as closely as 4050 needed, the text in WD-xml-names-19980327, "Namespaces in XML", 4051 edited by Tim Bray, Dave Hollander, and Andrew Layman [Bray, 4052 Hollander, Layman, 1998]. To meet this goal, the text in this 4053 appendix is mostly quoted verbatim from that source. The notational 4054 conventions and BNF productions in this appendix match those of the 4055 XML specification [Bray, Paoli, Spreberg-McQueen, 1998] 4057 XML namespaces are based on the use of qualified names, which 4058 contain a single colon, separating the name into a namespace prefix 4059 and the local name. The prefix, which is mapped to a URI, selects a 4060 namespace. The combination of the universally-managed URI namespace 4061 and the local schema namespace produces names that are guaranteed 4062 universally unique. 4064 URIs can contain characters not allowed in names, and so cannot be 4065 used directly as namespace prefixes. Therefore, the namespace 4066 prefix serves as a proxy for a URI. A special processing 4067 instruction described below is used to declare the association of 4068 the namespace prefix with a URI; software which supports this 4069 namespace proposal must recognize and act on it. 4071 A namespace is declared using a reserved processing instruction as 4072 follows: 4074 24.4.2 Namespace Declaration PI 4076 [1] NamespacePI ::= '' [ NSC: Required Parts ] 4078 [2] NSDef ::= 'ns' Eq SystemLiteral [ NSC: No Fragments ] 4079 [3] SrcDef ::= 'src' Eq SystemLiteral 4080 [4] PrefixDef ::= 'prefix' Eq ("'" NCName "'" | '"' NCName '"') 4081 [5] NCName ::= (Letter | '_') (NCNameChar)* /* An XML Name, minus 4082 the ":" */ 4083 [6] NCNameChar ::= Letter | Digit | '.' | '-' | '_' | 4084 CombiningChar | Extender 4086 [Definition:] The SystemLiteral in the NSDef production is a URI 4087 which functions as a namespace name to identify the namespace. The 4088 SystemLiteral in the SrcDef production is an optional URI which may 4089 be used to retrieve the schema, if one is provided. Some namespaces 4090 need no schemas; this specification does not depend on their 4091 existence, or on the use of any particular machine- or human- 4092 readable syntax in the schema. 4094 [Definition:] The NCName in the PrefixDef production gives the 4095 namespace prefix used to associate names in an XML document with 4096 this namespace. 4098 Namespace Constraint: Required Parts 4100 A namespace declaration must contain exactly one NSDef, exactly one 4101 PrefixDef and zero or one SrcDef. 4103 Namespace Constraint: No Fragments 4105 The SystemLiteral in the NSDef production must contain a URI, not 4106 including an attached #-separated fragment identifier. 4108 The namespace name, to serve its intended purpose, should have the 4109 characteristics of uniqueness and persistence. It is not a goal 4110 that it be directly usable for retrieval of a schema (if any 4111 exists). 4113 24.4.2.1 Examples of namespace declarations: 4115 4116 4117 4120 24.4.3 Placing Declarations in Documents 4122 Namespace declarations must be located in the prolog of an XML 4123 document, after the XML Declaration (if any) and before the DTD (if 4124 any). This effectively makes the scope of namespace prefixes global 4125 to the whole document, including the DTD. It also means that should 4126 a processor wish to insert its own qualified names, it need only 4127 read the namespace declarations from the prolog to be sure of 4128 generating a new, unique, namespace prefix. 4130 In XML documents conforming to this specification, the prolog must 4131 match the following production: 4133 24.4.4 Prolog with Namespace Declarations 4135 [7] prolog ::= XMLDecl? (NamespacePI | Misc)* (doctypedecl Misc*)? 4136 [ NSC: Unique Prefix ] 4138 Note that the namespace declarations are ordinary processing 4139 instructions which the XML processor will pass to the application as 4140 it does any other. 4142 Namespace Constraint: Unique Prefix 4144 A namespace prefix may not be declared more than once; i.e. there 4145 may not be two PrefixDefs which contain the same NCName string. 4147 24.4.5 Qualified Names 4149 [Definition:] In XML documents conforming to this specification, 4150 some names (constructs corresponding to the nonterminal Name) may be 4151 given as qualified names, defined as follows: 4153 Qualified Name 4155 [8] QName ::= (Prefix ':')? LocalPart 4156 [9] Prefix ::= NCName [ NSC: Prefix Declared ] 4157 [10] LocalPart ::= NCName 4159 The Prefix provides the namespace prefix part of the qualified name, 4160 and must be associated with defining schema through the URI in the 4161 applicable namespace declaration. 4163 [Definition:] The LocalPart provides the local name part of the 4164 qualified name. 4166 Namespace Constraint: Prefix Declared 4168 The namespace prefix, unless it is "xml", must have been declared in 4169 a namespace declaration. The namespace prefix xml is reserved and 4170 considered to have been implicitly declared. No other prefix 4171 beginning with the three-letter sequence x m, l, in any case 4172 combination, is allowed. 4174 24.4.6 Universal Names 4176 [Definition:] For each qualified name, there is a corresponding 4177 universal name, which is an ordered pair containing first, the 4178 namespace name associated with its prefix, and second, its local 4179 name. 4181 A universal name is independent of the prefix in use in any 4182 particular XML document; thus, universal names provide a basis for 4183 comparing named objects located in different XML documents. 4185 24.4.7 Using Qualified Names 4187 In XML documents conforming to this specification, element types are 4188 given as qualified names, as follows. In the productions below, the 4189 nonterminals (STag, ETag, EmptyElement, and Attribute) are taken 4190 from the XML specification [XML]; the productions in all cases match 4191 a subset of the strings matched by those of the same name in the XML 4192 spec. 4194 Start-tag 4195 [11] STag ::= '<' QName (S Attribute)* S? '>' 4196 [12] ETag ::= '' 4197 [13] EmptyElement ::= '<' QName (S Attribute)* S? '/>' 4199 24.4.8 Processing instruction 4201 Targets are given as qualified names, as follows: 4203 PI Target 4205 [15] PITarget ::= QName [ NSC: Declare Before Use ] 4207 Namespace Constraint: Declare Before Use 4209 When a PI target, aside from that in a namespace declaration PI, is 4210 qualified with a prefix, that prefix must be declared at a location 4211 in the document which precedes its use. 4213 24.4.9 Scope and Meaning of Qualified Names 4215 [Note to the reader: This section does not appear in [Bray, 4216 Hollander, Layman, 1998], but is necessary to avoid ambiguity for 4217 WebDAV XML processors.] 4219 WebDAV compliant XML processors MUST interpret a qualified name as a 4220 URI constructed by appending the LocalPart to the schema URI of the 4221 namespace. The scope of a namespace in a qualified name is limited 4222 to a single element tag. Every start tag, end tag, or empty XML 4223 element from a namespace MUST include the namespace name in the tag. 4225 Scope Example 4227 4228 4229 4230 Johnny Updraft 4231 4232 4233 4235 In this example, the qualified element name "del:glider" is 4236 interpreted as the URL "http://www.del.jensen.org/glider". Since 4237 the scope of a namespace is limited to a single element, each start 4238 tag, end tag, and empty element tag in the example includes the 4239 short name of the namespace, "del" as part of the qualified name. 4241 4242 4243 4244 Johnny Updraft 4245 4246 4247 4249 Even though this example is syntactically different from the 4250 previous example, it is semantically identical. Each instance of 4251 the namespace name "bar" is replaced with 4252 "http://www.del.jensen.org/" and then appended to the local name for 4253 each element tag. The resulting tag names in this example are 4254 exactly the same as for the previous example. 4256 4257 4258 4259 Johnny Updraft 4260 4261 4262 4264 This example is semantically identical to the two previous ones. 4265 Each instance of the namespace name "foo" is replaced with 4266 "http://www.del.jensen.org/glide" which is then appended to the 4267 local name for each element tag, the resulting tag names are 4268 identical to those in the previous examples.