idnits 2.17.1 draft-ietf-webdav-protocol-03.txt: -(319): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1973): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2498): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2506): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2507): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2550): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2793): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-27) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == There are 17 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 51 longer pages, the longest (page 1) being 71 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' 8 Security Considerations' ) ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** There are 627 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** The abstract seems to contain references ([Live], [WebDAV,1997], [MARC,1994], [DTD], [Berners-Lee,1997], [VTML], [ResponseDescription], [DefinedProps], [ISO8601], [Bray,Sperberg-McQueen,, 1995], [TBD], [Lagoze,1996], 1997], [Lasher,Cohen,, [Yergeau,1997], [Maloney,1996]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 18 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 302: '... of the property MUST be either blank,...' RFC 2119 keyword, line 341: '...t property system MUST be such that it...' RFC 2119 keyword, line 344: '... MUST be able to speak to a h...' RFC 2119 keyword, line 345: '... client MUST be able to speak...' RFC 2119 keyword, line 346: '... way MUST be that the request...' (164 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 2657 has weird spacing: '...such as the U...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "Second" TimeType specifies the number of seconds that may elapse before the lock is automatically removed. A server MUST not generate a time out value for "second" greater than 2^32-1. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 29, 1997) is 9707 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'Bray' on line 3064 looks like a reference -- Missing reference section? 'Sperberg-McQueen' on line 3064 looks like a reference -- Missing reference section? '1997' on line 3107 looks like a reference -- Missing reference section? 'Berners-Lee' on line 3060 looks like a reference -- Missing reference section? 'Lagoze' on line 272 looks like a reference -- Missing reference section? '1996' on line 3080 looks like a reference -- Missing reference section? 'MARC' on line 3083 looks like a reference -- Missing reference section? '1994' on line 3083 looks like a reference -- Missing reference section? 'Lasher' on line 3077 looks like a reference -- Missing reference section? 'Cohen' on line 3077 looks like a reference -- Missing reference section? '1995' on line 3077 looks like a reference -- Missing reference section? 'DTD' on line 425 looks like a reference -- Missing reference section? 'DefinedProps' on line 392 looks like a reference -- Missing reference section? 'Live' on line 425 looks like a reference -- Missing reference section? 'ResponseDescription' on line 662 looks like a reference -- Missing reference section? 'ISO8601' on line 1291 looks like a reference -- Missing reference section? 'VTML' on line 1946 looks like a reference -- Missing reference section? 'TBD' on line 3041 looks like a reference -- Missing reference section? 'Maloney' on line 3080 looks like a reference -- Missing reference section? 'WebDAV' on line 3099 looks like a reference -- Missing reference section? 'Yergeau' on line 3107 looks like a reference Summary: 14 errors (**), 0 flaws (~~), 7 warnings (==), 23 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 WEBDAV Working Group Y. Y. Goland, Microsoft 3 INTERNET-DRAFT E. J. Whitehead, Jr., U.C. Irvine 4 A. Faizi, Netscape 5 S. R Carter, Novell 6 D. Jensen, Novell 7 Expires April 6, 1998 September 29, 1997 9 Extensions for Distributed Authoring and Versioning 10 on the 11 World Wide Web -- WEBDAV 13 Status of this Memo 15 This document is an Internet-Draft. Internet-Drafts are working 16 documents of the Internet Engineering Task Force (IETF), its 17 areas, and its working groups. Note that other groups may also 18 distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six 21 months and may be updated, replaced, or made obsolete by other 22 documents at any time. It is inappropriate to use Internet-Drafts 23 as reference material or to cite them other than as "work in 24 progress". 26 To learn the current status of any Internet-Draft, please check 27 the "1id-abstracts.txt" listing contained in the Internet-Drafts 28 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net 29 (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East 30 Coast), or ftp.isi.edu (US West Coast). 32 Distribution of this document is unlimited. Please send comments 33 to the Distributed Authoring and Versioning (WEBDAV) working 34 group at , which may be joined by sending a 35 message with subject "subscribe" to . 38 Discussions of the WEBDAV working group are archived at 39 . 41 Abstract 43 This Document specifies a set of methods and content-types 44 ancillary to HTTP/1.1 for the management of resource properties, 45 simple name space manipulation, simple resource locking 46 (collision avoidance) and resource version control. 48 Table of Contents 49 Abstract 50 1 Terminology 51 2 Data Model and Methods for DAV Properties 52 2.1 Introduction 53 2.1.1 The DAV Property 54 2.1.2 Existing Metadata Proposals 55 2.1.3 Properties and HTTP Headers 56 2.2 A Property Model for HTTP Resources 57 2.2.1 Overview 58 2.2.2 Property Namespace 59 2.3 Schemas 60 2.3.1 PropSchema XML Element 61 2.3.2 DTD XML Element 62 2.3.3 DefinedProps XML Element 63 2.3.4 PropEntries XML Element 64 2.3.5 Live XML Element 65 2.4 DAV Schema 66 2.4.1 DAV Property 67 2.4.2 Level XML Element 68 2.4.3 Prop XML element 69 2.4.4 PropLoc XML Attribute 70 2.4.5 Example 71 2.5 Property Identifiers 72 2.5.1 Problem Definition 73 2.6 Link XML Element 74 2.6.1 Problem Description 75 2.6.2 Solution Requirements 76 2.6.3 Link XML Element 77 2.6.4 Src XML Element 78 2.6.5 Dst XML Element 79 2.6.6 Example 80 2.7 Multi-Status Response 81 2.7.1 Problem Definition 82 2.7.2 Solution Requirements 83 2.7.3 Multi-Status Response 84 2.8 Properties and Methods 85 2.8.1 DELETE 86 2.8.2 GET 87 2.8.3 PROPPATCH 88 2.8.4 PUT 89 2.8.5 PROPFIND 90 3 A Proposal for Collections of Web Resources and Name Space 91 Operations 92 3.1 Observations on the HTTP Object Model 93 3.1.1 Collection Resources 94 3.1.2 Creation and Retrieval of Collection Resources 95 3.1.3 Source Resources and Output Resources 96 3.2 MKCOL Method 97 3.2.1 Problem Description 98 3.2.2 Solution Requirements 99 3.2.3 Request 100 3.2.4 Response 101 3.2.5 Example 102 3.3 Standard DAV Properties 103 3.3.1 IsCollection Property 104 3.3.2 DisplayName Property 105 3.3.3 CreationDate Property 106 3.3.4 GETentity Property 107 3.3.5 INDEXentity Property 108 3.3.6 Content-Type XML Element 109 3.3.7 Content-Length XML Element 110 3.3.8 Content-Language XML Element 111 3.3.9 Last-Modified XML Element 112 3.3.10 Etag XML Element 113 3.4 INDEX Method 114 3.4.1 Problem Description 115 3.4.2 Solution Requirements 116 3.4.3 The Request 117 3.4.4 The Response 118 3.4.5 ResInfo XML Element 119 3.4.6 Members XML Element 120 3.4.7 Href XML Element 121 3.4.8 Example 122 3.5 Behavior of RFC 2068 Methods on Collections 123 3.5.1 GET, HEAD for Collections 124 3.5.2 POST for Collections 125 3.5.3 PUT for Collections 126 3.5.4 DELETE for Collections 127 3.5.5 DELETE Method for Non-Collection Resources 128 3.6 COPY Method 129 3.6.1 Problem Description 130 3.6.2 Solution Requirements 131 3.6.3 The Request 132 3.6.4 The Response 133 3.6.5 Examples 134 3.7 MOVE Method 135 3.7.1 Problem Description 136 3.7.2 Solution Requirements 137 3.7.3 The Request 138 3.7.4 The Response 139 3.7.5 Examples 140 3.8 ADDREF Method 141 3.8.1 Problem Definition 142 3.8.2 Solution Requirements 143 3.8.3 The Request 144 3.8.4 Example 145 3.9 DELREF Method 146 3.9.1 Problem Definition 147 3.9.2 Solution Requirements 148 3.9.3 The Request 149 3.9.4 Example 150 3.10 PATCH Method 151 3.10.1 Problem Definition 152 3.10.2 Solution Requirements 153 3.10.3 The Request 154 3.10.4 text/xml elements for PATCH 155 3.10.5 The Response 156 3.10.6 Examples 157 3.11 Headers 158 3.11.1 Destination Header 159 3.11.2 Enforce-Live-Properties Header 160 3.11.3 Overwrite Header 161 3.11.4 Destroy Header 162 3.11.5 Collection-Member Header 163 3.12 Links 164 3.12.1 Source Link Property Type 165 4 State Tokens 166 4.1 Overview 167 4.1.1 Problem Description 168 4.1.2 Solution Requirements 169 4.2 State Token Syntax 170 4.3 State Token Conditional Headers 171 4.3.1 If-State-Match 172 4.3.2 If-None-State-Match 173 4.4 State Token Header 174 4.5 E-Tags 175 5 Locking 176 5.1 Problem Description - Overview 177 5.1.1 Exclusive Vs. Shared Locks 178 5.1.2 Required Support 179 5.2 LOCK Method 180 5.2.1 Operation 181 5.2.2 Effect of Locks on Properties and Containers 182 5.2.3 Locking Replicated Resources 183 5.2.4 Interaction with other Methods 184 5.2.5 Lock Compatibility Table 185 5.2.6 Status Codes 186 5.2.7 Example 187 5.2.8 Lock-Info Request Header 188 5.2.9 Owner Request Header 189 5.2.10 Time-Out Header 190 5.2.11 State-Token Header 191 5.3 Write Lock 192 5.4 Lock Tokens 193 5.4.1 Problem Description 194 5.4.2 Proposed Solution 195 5.4.3 Lock Token Definition 196 5.5 UNLOCK Method 197 5.5.1 Problem Definition 198 5.5.2 Example 199 5.6 Discovery Mechanisms 200 5.6.1 Lock Type Discovery 201 5.6.2 Active Lock Discovery 202 6 Version Control 203 7 Internationalization Support 204 8 Security Considerations 205 9 Acknowledgements 206 10 References 207 11 Authors' Addresses 209 1 Terminology 211 Collection - A resource that contains member resources. 213 Member Resource - a resource referred to by a collection. There 214 are two types of member resources: external and internal. 216 Internal Member Resource - the name given to a member resource of 217 a collection whose URI is relative to the URI of the collection. 219 External Member Resource - a member resource with an absolute URI 220 that is not relative to its parent�s URI. 222 Properties - A set of name/value pairs that contain descriptive 223 information about a resource. 225 Live Properties - Properties whose semantics and syntax are 226 enforced by the server. For example, a live "read-only" property 227 that is enforced by the server would disallow PUTs to the 228 associated resource. 230 Dead properties - Properties whose semantics and syntax are not 231 enforced by the server. A dead "read-only" property would not be 232 enforced by the server and thus would not be used by the server 233 as a reason to disallow a PUT on the associated resource. 235 2 Data Model and Methods for DAV Properties 237 2.1 Introduction 239 2.1.1 The DAV Property 241 Properties are pieces of data that describe the state of a 242 resource. Properties are data about data. The term property is 243 used within this specification to disambiguate the concept from 244 the overloaded terms "metadata" and "attribute". 245 Properties are used within distributed authoring environments to 246 provide for efficient discovery and management of resources. For 247 example, a 'subject' property might allow for the indexing of all 248 resources by their subject, and an 'author' property might allow 249 for the discovery of what authors have written which documents. 251 2.1.2 Existing Metadata Proposals 252 Properties have a long played an essential role in the 253 maintenance of large document repositories, and many current 254 proposals contain some notion of a property. These include PICS 255 [Miller et al., 1996], PICS-NG, the Rel/Rev draft [Maloney, 256 1996], Web Collections, XML [Bray, Sperberg-McQueen, 1997], 257 several proposals on representing relationships within HTML, 258 digital signature manifests (DCMF), and a position paper on Web 259 metadata architecture [Berners-Lee, 1997]. 261 Some proposals come from a digital library perspective. These 262 include the Dublin Core [Weibel et al., 1995] metadata set and 263 the Warwick Framework [Lagoze, 1996], a container architecture 264 for different metadata schemas. The literature includes many 265 examples of metadata, including MARC [MARC, 1994], a 266 bibliographic metadata format, RFC 1807 [Lasher, Cohen, 1995], a 267 technical report bibliographic format employed by the Dienst 268 system, and the proceedings from the first IEEE Metadata 269 conference describe many community-specific metadata sets. 271 Participants of the 1996 Metadata II Workshop in Warwick, UK 272 [Lagoze, 1996], noted that, "new metadata sets will develop as 273 the networked infrastructure matures" and "different communities 274 will propose, design, and be responsible for different types of 275 metadata." These observations can be corroborated by noting that 276 many community-specific sets of metadata already exist, and there 277 is significant motivation for the development of new forms of 278 metadata as many communities increasingly make their data 279 available in digital form, requiring a metadata format to assist 280 data location and cataloging. 282 2.1.3 Properties and HTTP Headers 284 Properties already exist, in a limited sense, within HTTP through 285 the use of message headers. However, in distributed authoring 286 environments a relatively large number of properties are needed 287 to describe the state of a resource, and setting/returning them 288 all through HTTP headers is inefficient. Thus a mechanism is 289 needed which allows a principal to identify a set of properties 290 in which the principal is interested and to then set or retrieve 291 just those properties. 293 2.2 A Property Model for HTTP Resources 295 2.2.1 Overview 297 The DAV property model is based on name/value doubles. The name 298 of a property identifies the property's syntax and semantics, and 299 provides an address with which to refer to a property. The name 300 and value of a property is expressed as a well-formed XML 301 element, where the name of the property is the name of the XML 302 element, and the value of the property MUST be either blank, or a 303 well-formed XML element value. 305 2.2.2 Property Namespace 307 2.2.2.1 Problem Definition 309 The requirement is to be able to associate a value with a 310 property name on a resource and to be able to directly address 311 that value. 313 2.2.2.2 Solution Requirement 315 Ideally a property namespace should work well with extant 316 property implementations as well as database systems. The DAV 317 property namespace has been specified with the following two 318 facts in mind: 319 � Namespaces associated with flat file systems are ubiquitous. 320 � The majority of databases use a fixed schema mechanism. 321 The last point makes efficient implementation of hierarchical 322 properties difficult. Specifically, each property has a random 323 set of children; the best a relational database can do is provide 324 a table with name and value, where the value is a series of 325 indexes into other tables and each index represents a specific 326 value. However most RDBS do not provide for table pointers, only 327 index values. Such a system would have to be jury-rigged to 328 handle table pointers. In addition, indexing systems are 329 optimized for a small set of relatively large tables; 330 hierarchical property systems tend toward many properties, each 331 with different numbers and types of children, thus potentially 332 requiring a table for each child. 334 It would seem best to implement a flat property namespace, 335 inducing a natural isomorphism between DAV and most native file 336 systems. Adopting such a model will not restrict RDBS from taking 337 full advantage of their search facilities. 339 However, it seems that future trends might be toward hierarchical 340 properties. Therefore, DAV requirements [Slein et al.] stipulate 341 that the design of the flat property system MUST be such that it 342 will be possible to add true hierarchical properties later 343 without breaking downlevel clients. Specifically, a flat client 344 MUST be able to speak to a hierarchical server and a hierarchical 345 client MUST be able to speak to a flat server. Worst case either 346 way MUST be that the request fails. 348 2.2.2.3 Property Names 350 A property name identifies both the syntax and semantics of the 351 property's value. It is critical that property names do not 352 collide, e.g., two principals defining the same property name 353 with two different meanings. 355 The URI framework provides a mechanism to prevent namespace 356 collision and for varying degrees of administrative control. 357 Rather than reinvent these desirable features, DAV properties 358 make use of them by requiring that all DAV property names MUST be 359 URIs. Since a property is also an XML element, the name of the 360 XML element is a URI. 362 The property namespace is flat, that is, it is not possible to 363 string together a series of property names in order to refer to a 364 hierarchy of properties. Thus it is possible to refer to a 365 property B but not a property A/B, where is also a property 366 defined on the resource. 368 Finally, it is not possible to define the same property twice as 369 this would cause a collision in the resource's property 370 namespace. 372 2.3 Schemas 373 A schema is a group of property names and XML elements. 375 Schema discovery is used to determine if a system supports a 376 group of properties or XML elements. A property does not 377 necessarily contain sufficient information to identify any 378 schema(s) to which it may belong. 380 As with property names, schemas MUST use URIs as their names. 382 A resource declares its support for a schema by defining a 383 property whose name is the same as the schema's. The property 384 SHOULD contain the PropSchema XML element. 386 2.3.1 PropSchema XML Element 388 Name: http://www.ietf.org/standards/dav/PropSchema 389 Purpose: To provide information about properties 390 Schema: http://www.ietf.org/standards/dav/ 391 Parent: Any 392 Values= [DTD] [DefinedProps] 393 Description:This property contains the definition of the schema. 394 This definition consists of two parts. A DTD element that 395 contains a DTD that declares all XML elements and DefinedProps 396 that defines any properties associated with the schema. As with 397 all XML it is possible to add extra XML elements. Therefore 398 schemas may define extra XML elements which are to be included 399 with their values. 401 2.3.2 DTD XML Element 403 Name: http://www.ietf.org/standards/dav/DTD 404 Purpose: To contain the DTD for XML elements associated with the 405 schema. 406 Schema: http://www.ietf.org/standards/dav/ 407 Parent: Any 408 Values: XML Declaration statements 410 2.3.3 DefinedProps XML Element 412 Name: http://www.ietf.org/standards/dav/DefinedProps 413 Purpose: To contain a list of properties defined by the schema. 414 Schema: http://www.ietf.org/standards/dav/ 415 Parent: Any 416 Values= 1*PropEntries 418 2.3.4 PropEntries XML Element 420 Name: http://www.ietf.org/standards/dav/PropEntries 421 Purpose: To contain the name of a defined property, the DTD of 422 its value, and its live/dead status. 423 Schema: http://www.ietf.org/standards/dav/ 424 Parent: DefinedProps 425 Values= Prop [DTD] [Live] 426 Description:Prop contains the name of the property. The DTD 427 contains the DTD of the property's value. Live, if defined, 428 indicates that the property has semantics and syntax that are 429 enforced by the server. 431 2.3.5 Live XML Element 433 Name: http://www.ietf.org/standards/dav/Live 434 Purpose: If present this indicates the server MUST enforce the 435 syntax and semantics of the property. 436 Schema: http://www.ietf.org/standards/dav/ 437 Parent: PropEntries 439 2.4 DAV Schema 441 The DAV Schema is specified as 442 http://www.ietf.org/standards/dav/. This schema is used to 443 indicate support for 444 � properties that may be defined on a resource and 445 � XML elements that may be returned in responses. 447 2.4.1 DAV Property 449 Name: http://www.ietf.org/standards/dav 450 Purpose: Defines support for the DAV schema and protocol. 451 Schema: http://www.ietf.org/standards/dav/ 452 Values= PropSchema Level 453 Description:This property indicates that the resource supports 454 the DAV schema and protocol to the level indicated. THE VALUE IN 455 PROPSCHEMA IS TBD, WE NEED TO PROVIDE IT IN AN APPENDIX. 457 2.4.2 Level XML Element 459 Name: http://www.ietf.org/standards/dav/level 460 Purpose: To indicate the level of DAV compliance the resource 461 meets. 462 Schema: http://www.ietf.org/standards/dav/ 463 Parent: DAV 464 Values= "1" | "2" | "3" 465 Description:A value of 1 for level indicates that the resource 466 supports the property and namespace sections of the DAV 467 specification. Level 2 indicates that the resource supports level 468 1 and the lock section of the specification, with a minimum 469 locking capability of the write lock. Level 3 indicates support 470 for levels 1 and 2 as well as support for the versioning section 471 of the DAV specification. 473 2.4.3 Prop XML element 475 Name: http://www.ietf.org/standards/dav/prop 476 Purpose: Contains properties related to a resource. 477 Schema: http://www.ietf.org/standards/dav/ 478 Parent: Any 479 Values: XML Elements 480 Description:The Prop XML element is a generic container for 481 properties defined on resources. All elements inside Prop MUST 482 define properties related to the resource. No other elements may 483 be used inside of a Prop element. 485 2.4.4 PropLoc XML Attribute 487 Name: http://www.ietf.org/standards/dav/PropLoc 488 Purpose: To specify the location of the associated property. 489 Schema: http://www.ietf.org/standards/dav/ 490 Values= URL 491 Description:This attribute is used with elements inside of Props 492 contained in responses to specify the URL of the property on the 493 associated resource. The PropLoc attribute MUST NOT be used in 494 requests. 496 2.4.5 Example 498 500 501 502 504 Larry Masinter 505 506 508 The previous specifies that the property author exists on some 509 unspecified resource and that the property can be directly 510 referenced at http://www.foo.com/resource/props/Author. The 511 resource upon which the property is defined must be determined 512 from context. 514 2.5 Property Identifiers 516 2.5.1 Problem Definition 518 DAV properties are resources and thus may have a URI where the 519 value of an instance of the property may be retrieved. This URI 520 is separate from the URI name of the property, which identifies 521 the syntax and semantics of the property, but which does not give 522 information on how to access the value of an instance of the 523 property. 525 A server is free to assign whatever URI it chooses to identify an 526 instance of a property defined on a resource. In fact, a server 527 is free not to reveal the URI of an instance of a particular 528 resource and instead require that the client access the property 529 through PROPFIND and PROPPATCH. However, many servers will want 530 to allow clients to directly manipulate properties. On these 531 servers, a client can discover the URI of an instance of a 532 property by performing a PROPFIND and examining the PropLoc 533 attribute, if returned, of each property. 535 2.6 Link XML Element 537 2.6.1 Problem Description 539 A mechanism is needed to associate resources with other 540 resources. These associations, known as links, consist of three 541 values, a type describing the nature of the association, the 542 source of the link, and the destination of the link. In the case 543 of annotation, neither the source nor the destination of a link 544 need be the resource upon which the link is recorded. 546 2.6.2 Solution Requirements 548 The association mechanism MUST make use of the DAV property 549 mechanism in order to make the existence of the associations 550 searchable. 552 2.6.3 Link XML Element 553 Name: http://www.ietf.org/standards/dav/link 554 Purpose: To identify a property as a link and to contain the 555 source and destination of that link. 556 Schema: http://www.ietf.org/standards/dav/ 557 Values= 1*Src 1*Dst 558 Description:Link is used to provide the sources and destinations 559 of a link. The type of the property containing the Link XML 560 element provides the type of the link. Link is a multi-valued 561 element, so multiple Links may be used together to indicate 562 multiple links with the same type. 564 2.6.4 Src XML Element 566 Name: http://www.ietf.org/standards/dav/src 567 Purpose: To indicate the source of a link. 568 Schema: http://www.ietf.org/standards/dav/ 569 Parent: http://www.ietf.org/standards/dav/link 570 Values= URI 572 2.6.5 Dst XML Element 574 Name: http://www.ietf.org/standards/dav/Dst 575 Purpose: To indicate the destination of a link 576 Schema: http://www.ietf.org/standards/dav/ 577 Parent: http://www.ietf.org/standards/dav/link 578 Values= URI 580 2.6.6 Example 582 584 586 587 588 589 Source 590 http://foo.bar/program 591 http://foo.bar/src/main.c 592 593 594 Library 595 http://foo.bar/program 596 http://foo.bar/src/main.lib 597 598 599 Makefile 600 http://foo.bar/program 601 http://foo.bar/src/makefile 602 603 604 606 In this example the resource http://foo.bar/program has a source 607 property defined which contains three links. Each link contains 608 three elements, two of which, src and dst, are part of the DAV 609 schema defined in this document, and one which is defined by the 610 schema http://www.foocorp.com/project/ (Source, Library, and 611 Makefile). A client which only implements the elements in the DAV 612 spec will not understand the foocorp elements and will ignore 613 them, thus seeing the expected source and destination links. An 614 enhanced client may know about the foocorp elements and be able 615 to present the user with additional information about the links. 617 2.7 Multi-Status Response 619 2.7.1 Problem Definition 621 Some methods effect more than one resource. The effect of the 622 method on each of the scoped resources may be different, as such 623 a return format that can specify the effect of the method on each 624 resource is needed. 626 2.7.2 Solution Requirements 628 The solution must: 629 - communicate the status code and reason 630 - give the URI of the resource on which the method was invoked 631 - be consistent with other return body formats 632 - 634 2.7.3 Multi-Status Response 636 The default multi-status response body is an text/xml HTTP entity 637 that contains a single XML element called multiresponse, which 638 contains a set of XML elements called response, one for each 200, 639 300, 400, and 500 series status code generated during the method 640 invocation. 100 series status codes MUST NOT be recorded in a 641 response XML element. 643 2.7.3.1 MultiResponse 645 Name: http://www.ietf.org/standards/dav/multiresponse 646 Purpose: Contains multiple response messages. 647 Schema: http://www.ietf.org/standards/dav/ 648 Parent: Any 649 Value: 1*Response [ResponseDescription] 650 Description:The ResponseDescription at the top level is used to 651 provide a general message describing the over arching nature of 652 the response. If this value is available an application MAY use 653 it instead of presenting the individual response descriptions 654 contain within the responses. 656 2.7.3.2 Response 658 Name: http://www.ietf.org/standards/dav/response 659 Purpose: Holds a single response 660 Schema: http://www.ietf.org/standards/dav/ 661 Parent: Any 662 Value: (Prop | HREF) Status [ResponseDescription] 663 Description: Prop MUST contain one or more empty XML elements 664 representing the name of properties. Multiple properties may be 665 included if the same response applies to them all. If HREF is 666 used then the response refers to a problem with the referenced 667 resource, not a property. 669 2.7.3.3 Status 671 Name: http://www.ietf.org/standards/dav/status 672 Purpose: Holds a single HTTP status-line 673 Schema: http://www.ietf.org/standards/dav/ 674 Parent: Response 675 Value: status-line ;status-line defined in [Fielding et al., 676 1997] 678 2.7.3.4 ResponseDescription 680 Name: 681 http://www.ietf.org/standards/dav/ResponseDescription 682 Purpose: Contains a message that can be displayed to the user 683 explaining the nature of the response. 684 Schema: http://www.ietf.org/standards/dav/ 685 Parent: Multiresponse and/or Response 686 Value: Any 687 Description: This XML element provides information suitable to 688 be presented to a user. 690 2.8 Properties and Methods 692 2.8.1 DELETE 694 As properties are resources, the deletion of a property causes 695 the same result as the deletion of any resource. It is worth 696 pointing out that the deletion of a property effects both direct 697 manipulation, that is by the property's URL, as well as indirect 698 discovery and manipulation, that is PROPPATCH and PROPFIND. 700 2.8.2 GET 702 A GET with a Request-URI that identifies a property returns the 703 name and value of that property. Accept types may be used to 704 specify the format of the return value, but all DAV compliant 705 servers MUST at minimum support a return type of text/xml. If 706 text/xml is used as the response format then it MUST return the 707 name and value of the property using the Prop XML element. 709 2.8.2.1 Example 711 The following example assumes that the property's URL, originally 712 generated by the server, was discovered by examining the proploc 713 XML attribute returned on a result from a FINDPROP. 715 GET /bar.html;prop=z39.50_authors HTTP/1.1 716 Host: foo.com 718 HTTP/1.1 200 OK 719 Content-Type: text/xml 720 Content-Length: xxxx 721 E-tag: "1234" 722 Last-Modified: xxxx 724 726 728 729 730 Jane Doe 731 Joe Doe 732 Lots o'Doe 733 734 736 2.8.3 PROPPATCH 738 The PROPPATCH method processes instructions specified in the 739 request body to create and/or remove properties defined on the 740 resource identified by Request-URI. 742 All DAV compliant servers MUST process instructions which are 743 specified using the PropertyUpdate, Create, and Remove XML 744 elements of the DAV schema. The request message body MUST 745 contain at least one PropertyUpdate XML element. Instruction 746 processing MUST occur in the order instructions are received 747 (i.e., from top to bottom), and MUST be performed atomically. 749 2.8.3.1 PropertyUpdate XML element 751 Name: http://www.ietf.org/standards/dav/PropertyUpdate 752 Purpose: To contain a request to alter the properties on a 753 resource. 754 Schema: http://www.ietf.org/standards/dav/ 755 Parent: Any 756 Values= *(Create | Remove) 757 Description:This XML element is a container for the information 758 required to modify the properties on the resource. This XML 759 element is multi-valued. 761 2.8.3.2 Create XML element 763 Name: http://www.ietf.org/standards/dav/create 764 Purpose: To create the DAV properties specified inside the 765 Create XML element. 766 Schema: http://www.ietf.org/standards/dav/ 767 Parent: http://www.ietf.org/standards/dav/PropertyUpdate 768 Values= Prop 769 Description:This XML element MUST contain only a Prop XML 770 element. The elements contained by Prop specify the name and 771 value of properties that are created on Request-URI. If a 772 property already exists then its value is replaced. The Prop XML 773 element MUST NOT contain a PropLoc XML attribute. 775 2.8.3.3 Remove XML element 777 Name: http://www.ietf.org/standards/dav/remove 778 Purpose: To remove the DAV properties specified inside the 779 Remove XML element. 780 Schema: http://www.ietf.org/standards/dav/ 781 Parent: http://www.ietf.org/standards/dav/PropertyUpdate 782 Values= Prop 783 Description:Remove specifies that the properties specified in 784 Prop should be removed. Specifying the removal of a property that 785 does not exist is not an error. All the elements in Prop MUST be 786 empty, as only the names of properties to be removed are 787 required. 789 2.8.3.4 Response 791 The response MUST have a response body that contains a 792 multiresponse identifying the results for each property. 794 2.8.3.5 Response Codes 796 200 OK - The command succeeded. As there can be a mixture of 797 Create and Removes in a body, a 201 Create seems inappropriate. 798 403 Forbidden - The client, for reasons the server chooses not to 799 specify, can not alter one of the properties. 800 405 Conflict - The client has provided a value whose semantics 801 are not appropriate for the property. This includes trying to set 802 read only properties. 803 413 Request Entity Too Long - If a particular property is too 804 long to be recorded then a composite XML error will be returned 805 indicating the offending property. 806 417 Insufficient Space on Resource - The resource does not have 807 sufficient space to record the state of the resource after the 808 execution of this method. 809 418 Atomicity Failure - The command was not executed because of 810 an atomicity failure elsewhere the caused the entire command to 811 be aborted. 813 2.8.3.6 Example 815 PROPPATCH /bar.html HTTP/1.1 816 Host: www.foo.com 817 Content-Type: text/xml 818 Content-Length: xxxx 820 822 824 825 826 827 828 Jim Whitehead 829 Roy Fielding 830 831 832 833 834 835 836 838 HTTP/1.1 405 Conflict 839 Content-Type: text/xml 840 Content-Length: xxxxx 842 844 846 847 Copyright Owner can not be deleted or 848 altered. 849 850 851 HTTP/1.1 418 Atomicity Failure 852 853 854 855 HTTP/1.1 405 Conflict 856 857 859 2.8.4 PUT 861 A PUT is specified in order to control what is returned by a GET. 862 However a GET on a property always returns a predefined property 863 containment format. Therefore PUT can not be used if the Request- 864 URI refers to a property. 866 2.8.5 PROPFIND 868 The PROPFIND method retrieves properties defined on Request-URI. 869 The request message body is an XML document that MUST contain 870 only one PropFind XML element, which specifies the type of 871 property find action to be performed. The XML element contained 872 by PropFind specifies the type of action to be performed: 873 retrieve all property names and values (AllProp), retrieve only 874 specified property names and values (Prop), or retrieve only a 875 list of all property names (Propname). When a Prop XML element 876 is present, it specifies a list of the names of properties whose 877 name and value are to be returned. The Prop element, when used 878 within a FINDPROP request body MUST be empty. 880 The response is a text/xml message body that contains a 881 MultiResponse XML element which describes the results of the 882 attempts to retrieve the various properties. If a property was 883 successfully retrieved then its value MUST be returned in the 884 prop XML element. In the case of Allprop and Findprop, if a 885 principal does not have the right to know if a particular 886 property exists, an error MUST NOT be returned. The results of 887 this method SHOULD NOT be cached. 889 2.8.5.1 Propfind XML element 891 Name: http://www.ietf.org/standards/dav/Propfind 892 Purpose: To specify the set of matching properties 893 Schema: http://www.ietf.org/standards/dav/ 894 Parent: Any 895 Values= (Prop | Allprop | Propname) 896 Description: Propfind is a container element for the exact 897 specification of a PROPFIND request. 899 2.8.5.2 Allprop 901 Name: http://www.ietf.org/standards/dav/Allprop 902 Purpose: To specify that all properties are to be returned 903 Schema: http://www.ietf.org/standards/dav/ 904 Parent: Propfind 905 Description: Its presence in a PROPFIND request specifies the 906 name and value of all properties defined on the resource MUST be 907 returned. 909 2.8.5.3 Propname 911 Name: http://www.ietf.org/standards/dav/Propname 912 Purpose: To specify that the names of all properties defined on 913 the resource are to be returned. 914 Schema: http://www.ietf.org/standards/dav/ 915 Parent: Propfind 916 Description: Its presence in a PROPFIND request specifies the 917 name of all properties defined on the resource MUST be returned. 919 2.8.5.4 PropFindResult XML element 921 Name: http://www.ietf.org/standards/dav/PropFindResult 922 Purpose: To contain the results of a SEARCH request 923 Schema: http://www.ietf.org/standards/dav/ 924 Parent: Any 925 Values: Prop 927 2.8.5.5 Example 1 - Prop 929 PROPFIND /container/ HTTP/1.1 930 Host: www.foo.bar 931 Content-Length: xxxx 932 Content-Type: text/xml 934 936 938 939 940 941 942 943 944 945 947 HTTP/1.1 207 Partial Success 948 Content-Type: text/xml 949 Content-Length: xxxxx 951 953 954 955 There has been an access violation 956 error. 957 958 959 960 Box type A 961 962 963 J.J. Dingleheimerschmidt 964 965 966 HTTP/1.1 200 Success 967 968 969 970 HTTP/1.1 403 Forbidden 971 The user does not have access to 972 the DingALink property. 973 974 976 The result will return all properties on the container. In this 977 case only two properties were found. The principal did not have 978 sufficient access rights to see the third and fourth properties 979 so an error was returned. 981 2.8.5.6 Example 2 - Allprop 983 PROPFIND /container/ HTTP/1.1 984 Host: www.foo.bar 985 Content-Length: xxxx 986 Content-Type: text/xml 988 990 991 992 994 HTTP/1.1 200 Success 995 Content-Type: text/xml 996 Content-Length: xxxxx 998 1000 1001 1002 1003 1004 Box type A 1005 1006 1007 Hadrian 1008 1009 1010 HTTP/1.1 200 Success 1011 1013 This particular client only had the right to see two properties, 1014 BoxType and Author. No error is returned for the remaining 1015 properties, as the client does not even have sufficient rights to 1016 know they exist. If the client did have the right to know they 1017 existed but did not have the right to see their value, a 201 1018 Partial Success with a multiresponse, as used in the previous 1019 example, would have been returned. 1021 2.8.5.7 Example 3 - Propname 1023 PROPFIND /container/ HTTP/1.1 1024 Host: www.foo.bar 1025 Content-Length: xxxx 1026 Content-Type: text/xml 1028 1030 1031 1032 1034 HTTP/1.1 200 Success 1035 Content-Type: text/xml 1036 Content-Length: xxxxx 1038 1040 1042 1043 1044 1045 1046 1047 1048 1049 HTTP/1.1 200 Success 1050 1052 In this case only two of the properties have direct URLs 1053 available, while the other two properties can only be referenced 1054 via PROPFIND and PROPPATCH. 1056 3 A Proposal for Collections of Web Resources and Name Space 1057 Operations 1059 3.1 Observations on the HTTP Object Model 1061 This section provides a description of a new type of Web 1062 resource, the collection, and discusses its interactions with the 1063 HTTP URL namespace. This discussion is a prerequisite for the 1064 specification of methods that operate on collections, given later 1065 in this document. 1067 3.1.1 Collection Resources 1069 A collection is a resource whose state consists of a list of 1070 internal members, a list of external members, and a set of 1071 properties. An internal member resource MUST have a URI that is 1072 immediately relative to the base URI of the collection, that is, 1073 a relative URI in which "../" is illegal, which must begin with 1074 "./" and which MAY contain only one other "/" at the end of the 1075 URI. An external member resource MUST be an absolute URI that is 1076 not an internal URI. Any given internal or external URI MUST 1077 only belong to the collection once, i.e., multiple instances of 1078 URIs in a collection are illegal. Properties defined on 1079 collections have no special distinction, and behave exactly as do 1080 properties on non-collection resources. 1081 The purpose of a collection resource is to model collection-like 1082 objects (e.g., a filesystem directory) within a server's 1083 namespace. Once these objects have been modeled with 1084 collections, a client may perform an INDEX, add and remove 1085 external members using ADDREF and DELREF, and perform recursive 1086 operations, such as a full hierarchy copy. 1087 To support methods which operate on collections, a server SHOULD 1088 model its collection-like objects with collection resources. For 1089 example, a server which is implemented on top of a filesystem 1090 SHOULD treat all filesystem directories exposed by the server as 1091 collection resources.1 1093 3.1.2 Creation and Retrieval of Collection Resources 1095 This document specifies the MKCOL method to create new collection 1096 resources, and the INDEX method to list their contents.2 1097 In HTTP/1.1, the PUT method is defined to store the request body 1098 at the location specified by Request-URI. While a description 1099 format for a collection can readily be constructed that could be 1100 used with PUT, the implications of sending such a description to 1101 the server are undesirable. For example, if a description of a 1102 collection that omitted some existing resources were PUT to a 1103 server, this might be interpreted as a command to remove those 1104 members. This would extend PUT to perform DELETE functionality, 1105 which is undesirable since it changes the semantics of PUT, and 1106 makes it difficult to control DELETE functionality with an access 1107 control scheme based on methods. 1108 While the POST method is sufficiently open-ended that a "create a 1109 collection" POST command could be constructed, this is 1110 undesirable because it would be difficult to separate access 1111 control for collection creation from other uses of POST if they 1112 both use the same method. 1113 While it might seem desirable to have GET return a listing of the 1114 members of a collection, this is foiled by the existence of the 1115 "index.html" de-facto standard namespace redirection, in which a 1116 GET request on a collection is automatically redirected to the 1117 index.html resource. 1118 The exact definition of the behavior of GET and PUT on 1119 collections is defined later in this document. 1121 3.1.2.1 Example 1123 The structured resource http://foo/bar is created with a PUT. Bar 1124 is a multipart/related file with two members http://foo/bar/a and 1125 http://foo/bar/b. If bar were deleted then both a and b would 1126 also be deleted since they are all really just one resource. If 1127 http://foo/bar/a/c was PUT then a DELETE on http://foo/bar/a 1128 would also delete http://foo/bar/a/c as c was created with a PUT 1129 not a MKCOL. 1130 If http://foo/bar/b/d is created with a MKCOL and 1131 http://foo/bar/b/d/e was created then a DELETE on d would fail 1132 because d is a collection with an internal member. However the 1133 existence of the collection d is something of an illusion. If a 1134 DELETE was executed on http://foo/bar then everything would be 1135 deleted, even though http://foo/bar/b/d was created with a MKCOL. 1136 Thus the effect of a MKCOL within a composite resource�s 1137 namespace is felt on its children, not its ancestors. The 1138 children of d MUST be treated as members of a collection when a 1139 method is executed on d. But a method executed on b or a is 1140 treated as if there only existed a non-collection resource. 1142 3.1.3 Source Resources and Output Resources 1144 For many resources, the entity returned by GET exactly matches 1145 the persistent state of the resource, for example, a GIF file 1146 stored on a disk. For this simple case, the URL at which a 1147 resource is accessed is identical to the URL at which the source 1148 (the persistent state) of the resource is accessed. This is also 1149 the case for HTML source files that are not processed by the 1150 server prior to transmission. 1151 However, the server can sometimes process HTML resources before 1152 they are transmitted as a return entity body. For example, 1153 server- 1154 side-include directives within an HTML file instruct a server to 1155 replace the directive with another value, such as the current 1156 date. In this case, what is returned by GET (HTML plus date) 1157 differs from the persistent state of the resource (HTML plus 1158 directive). Typically there is no way to access the HTML resource 1159 containing the unprocessed directive. 1160 Sometimes the entity returned by GET is the output of a data- 1161 producing process that is described by one or more source 1162 resources (that may not even have a location in the URL 1163 namespace). A single data-producing process may dynamically 1164 generate the state of a potentially large number of output 1165 resources. An example of this is a CGI script that describes a 1166 "finger" gateway process that maps part of the namespace of a 1167 server into finger requests, such as 1168 http://www.foo.bar.org/finger_gateway/user@host. 1169 In the absence of distributed authoring capability, it is 1170 acceptable to have no mapping of source resource(s) to the URI 1171 namespace, and in fact has desirable security benefits. However, 1172 if remote editing of the source resource(s) is desired, the 1173 source resource(s) should be given a location in the URI 1174 namespace. This source location should not be one of the 1175 locations at which the generated output is retrievable, since in 1176 general it is impossible for the server to differentiate requests 1177 for source resources from requests for process output resources. 1178 There is often a many-to-many relationship between source 1179 resources and output resources. 1180 For DAV compliant servers all output resources which have a 1181 single source resource (and that source resource has a URI), the 1182 URI of the source resource SHOULD be stored in a single link on 1183 the output resource with type 1184 http://www.ietf.org/standards/dav/source. Note that by storing 1185 the source URI in links on the output resources, the burden of 1186 discovering the source is placed on the authoring client. 1188 3.2 MKCOL Method 1190 3.2.1 Problem Description 1192 A client must be able to create a collection. 1194 3.2.2 Solution Requirements 1196 The solution: 1197 - Must ensure that a collection has been made (i.e. that it 1198 responds to the INDEX method) as opposed to a non-collection 1199 resource. If a collection could not be made, it must indicate 1200 this failure to the user-agent. 1202 3.2.3 Request 1204 MKCOL creates a new collection resource at the location specified 1205 by the Request-URI. If the Request-URI exists, then MKCOL must 1206 fail. During MKCOL processing, a server MUST make the Request-URI 1207 a member of its parent collection. If no such an ancestor exists, 1208 the method MUST fail. When the MKCOL operation creates a new 1209 collection resource, all ancestors MUST already exist, or the 1210 method MUST fail with a 409 Conflict status code. For example, 1211 if a request to create collection /a/b/c/d/ is made, and neither 1212 /a/b/ nor /a/b/c/ exist, the request MUST fail. 1214 3.2.3.1 MKCOL Without Request Body 1216 When MKCOL is invoked without a request body, the newly created 1217 collection has no members. 1219 3.2.3.2 MKCOL With Request Body 1221 A MKCOL request message MAY contain a message body. The behavior 1222 of a MKCOL request when the body is present is limited to 1223 creating collections, members of a collection, bodies of members 1224 and properties on the collections or members. If the server 1225 receives a MKCOL request entity type it does not support or 1226 understand it MUST respond with a 415 (Unsupported Media Type) 1227 status code. The exact behavior of MKCOL for various request 1228 media types is undefined in this document, and will be specified 1229 in separate documents. 1231 3.2.4 Response 1233 Responses from a MKCOL request are not cacheable, since MKCOL has 1234 non-idempotent semantics. 1235 201 (Created) - The collection or structured resource was created 1236 in its entirety. 1237 403 (Forbidden) - This indicates at least one of two conditions: 1238 1) The server does not allow the creation of collections at the 1239 given location in its namespace, and 2) The parent collection of 1240 the Request-URI exists but cannot accept members. 1241 409 (Conflict) - A collection cannot be made at the Request-URI 1242 until one or more intermediate collections have been created. 1243 415 (Unsupported Media Type)- The server does not support the 1244 request type of the body. 1245 417 (Insufficient Space on Resource) - The resource does not have 1246 sufficient space to record the state of the resource after the 1247 execution of this method. 1249 3.2.5 Example 1251 This example creates a container collection called 1252 /webdisc/xfiles/ on the server www.server.org. 1253 MKCOL /webdisc/xfiles/ HTTP/1.1 1254 Host: www.server.org 1256 HTTP/1.1 201 Created 1258 3.3 Standard DAV Properties 1260 The following properties are defined on DAV compliant resources. 1261 All enclosed properties are part of the DAV Schema. 1263 3.3.1 IsCollection Property 1265 Name: http://www.ietf.org/standards/dav/iscollection 1266 Purpose: This property contains a Boolean value that is set to 1267 "true" if the resource is a collection 1268 Schema: http://www.ietf.org/standards/dav/ 1269 Value: ("true" | "false") 1270 Description: This property MUST be defined on all DAV compliant 1271 resources. 1273 3.3.2 DisplayName Property 1275 Name: http://www.ietf.org/standards/dav/displayname 1276 Purpose: A name for the resource that is suitable for 1277 presentation to a user. 1278 Schema: http://www.ietf.org/standards/dav/ 1279 Value: Any valid XML character data (as defined in [Bray, 1280 Sperberg-McQueen, 1997]) 1281 Description: This property SHOULD be defined on all DAV compliant 1282 resources. If present, the property a description of the resource 1283 that is suitable for presentation to a user. 1285 3.3.3 CreationDate3 Property 1287 Name: http://www.ietf.org/standards/dav/creationdate 1288 Purpose: The time and 4date the resource was created. 1289 Schema: http://www.ietf.org/standards/dav/ 1290 Value: The time and date MUST be given in ISO 8601 format 1291 [ISO8601] 1292 Description: This property SHOULD be defined on all DAV compliant 1293 resources. If present, it contains a timestamp of the moment when 1294 the resource was created (i.e., the moment it had non-null 1295 state). 1297 3.3.4 GETentity Property5 1299 Name: http://www.ietf.org/standards/dav/GETentity 1300 Purpose: Contains the value of headers that are returned by a 1301 GET without Accept headers. 1302 Schema: http://www.ietf.org/standards/dav/ 1303 Value: Content-Type Content-Length Content-Language Last- 1304 Modified Etag Creation-Date 1305 Description: This property MUST be defined on all DAV compliant 1306 resources unless GET is not supported, in which case this 1307 property MUST NOT be defined. This property MUST contain at most 1308 one instance of each element in its Value, if they are defined. 1310 3.3.5 INDEXentity Property 1312 Name: http://www.ietf.org/standards/dav/INDEXentity 1313 Purpose: Contains the value of headers that are returned by an 1314 INDEX. 1315 Schema: http://www.ietf.org/standards/dav/ 1316 Value: Content-Type Content-Length Content-Language Last- 1317 Modified Etag Creation-Date 1318 Description: This property MUST be defined on all DAV compliant 1319 resources unless INDEX is not supported, in which case this 1320 property MUST NOT be defined. This property MUST contain at most 1321 one instance of each element in its Value, if they are defined. 1323 3.3.6 Content-Type XML Element 1325 Name: http://www.ietf.org/standards/dav/content-type 1326 Purpose: The content-type of the member resource. 1327 Schema: http://www.ietf.org/standards/dav/ 1328 Parent: GETentity or INDEXentity 1329 Value: media-type ; defined in Section 3.7 of [Fielding et 1330 al., 1997] 1331 Description: If the parent of this element is GETentity, the 1332 value MUST be identical to the content-type returned by a GET on 1333 the resource without Accept headers. If the parent is 1334 INDEXentity, the value MUST be identical to the content-type 1335 returned by an INDEX on the resource. If no content-type is 1336 available, this element MUST NOT be defined. 1338 3.3.7 Content-Length XML Element 1340 Name: http://www.ietf.org/standards/dav/content-length 1341 Purpose: Describes the default content-length of the resource. 1342 Schema: http://www.ietf.org/standards/dav/ 1343 Value: content-length ; see section 14.14 of RFC 2068 1344 Description: If the parent of this element is GETentity, this 1345 element MUST have a value equal to the content-length header 1346 returned by a GET on the resource without Accept headers. If the 1347 parent is INDEXentity, the value MUST be identical to the 1348 content- 1349 length returned by an INDEX on the resource. If no content- 1350 length is available, this element MUST NOT be defined. 1352 3.3.8 Content-Language XML Element 1354 Name: http://www.ietf.org/standards/dav/content-language 1355 Purpose: Describes the default natural language of a resource. 1356 Schema: http://www.ietf.org/standards/dav/ 1357 Value: language-tag ;language-tag is defined in section 1358 14.13 of RFC 2068 1359 Description: If the parent of this element is GETentity, this 1360 element MUST have a value equal to the content-language header 1361 returned by a GET on the resource without Accept headers. If the 1362 parent is INDEXentity, the value MUST be identical to the 1363 content- 1364 language header returned by an INDEX on the resource. If no 1365 content-language header is available, this element MUST NOT be 1366 defined. 1368 3.3.9 Last-Modified XML Element 1370 Name: http://www.ietf.org/standards/dav/last-modified 1371 Purpose: The date the resource was last modified. 1372 Schema: http://www.ietf.org/standards/dav/ 1373 Parent: GETentity or INDEXentity 1374 Value: The date MUST be given in RFC 1123 format (rfc-1123 1375 production, defined in section 3.3.1 of [Fielding et al., 1997] 1376 Description: If the parent of this element is GETentity, this 1377 element MUST have a value equal to the last-modified header 1378 returned by a GET on the resource without Accept headers. If the 1379 parent is INDEXentity, the value MUST be identical to the last- 1380 modified header returned by an INDEX on the resource. If no 1381 last- 1382 modified header is available, this element MUST NOT be defined. 1384 3.3.10 Etag XML Element 1386 Name: http://www.ietf.org/standards/dav/etag 1387 Purpose: The entity tag of the resource. 1388 Schema: http://www.ietf.org/standards/dav/ 1389 Parent: GETentity or INDEXentity 1390 Value: entity-tag ; defined in Section 3.11 of [Fielding et 1391 al., 1997] 1392 Description: If the parent of this element is GETentity, this 1393 element MUST have a value equal to the entity-tag header returned 1394 by a GET on the resource without Accept headers. If the parent 1395 is INDEXentity, the value MUST be identical to the entity-tag 1396 header returned by an INDEX on the resource. If no entity-tag 1397 header is available, this element MUST NOT be defined. 1399 3.4 INDEX Method 1401 3.4.1 Problem Description 1403 A mechanism is needed to discover if a resource is a collection 1404 and if so, list its members. 1406 3.4.2 Solution Requirements 1408 The solution: 1409 - must allow a client to discover the members of a collection 1410 - must always provide a machine-readable description of the 1411 membership of a collection 1412 - must be leveraged as a more general mechanism to provide a 1413 list of contents for any resource which can profitably return a 1414 membership like listing. 1416 3.4.3 The Request 1418 The INDEX method returns a machine-readable representation of the 1419 membership of the resource at the Request-URI. 6 1421 For a collection, INDEX MUST return a 7list of its members. All 1422 WebDAV compliant resources MUST support the text/xml response 1423 entity described below. The INDEX result for a collection MAY 1424 also return a list of the members of child collections, to any 1425 depth. 1427 Collections that respond to an INDEX method with a text/xml 1428 entity MUST contain only one ResInfo element. This ResInfo 1429 element contains an Href element, which gives the identifier(s) 1430 of the resource, a Prop element, which gives selected properties 1431 of the resource, and a Members element, which contains a ResInfo 1432 element for each member of the collection. The Prop element MUST 1433 contain at least the following properties, if they are defined 1434 and available8: DisplayName, IsCollection, CreationDate, 1435 GETentity, and INDEXentity. 1437 The response from INDEX is cacheable, and SHOULD be accompanied 1438 by an ETag header (see section 13.3.4 of RFC 2068). If GET and 1439 INDEX return different entities for the same resource state, they 1440 MUST return different entity tags. 1442 3.4.4 The Response 1444 200 (OK) - The server MUST send a machine readable response 1445 entity which describes the membership of the resource. 1447 3.4.5 ResInfo XML Element 1449 Name: http://www.ietf.org/standards/dav/resinfo 1450 Purpose: Describes a resource. 1451 Schema: http://www.ietf.org/standards/dav/ 1452 Parent: Any 1453 Value: Href Prop Members9 1454 Description: There MUST be at least one Href element. Each Href 1455 element contains a URI for the resource, which MUST be an 1456 absolute URI. There MUST be a single Prop element that contains a 1457 series of properties defined on the resource. If the resource is 1458 a collection, it MAY have at most one Members element, which 1459 describes the members of the collection. 1461 3.4.6 Members XML Element 1463 Name: http://www.ietf.org/standards/dav/members 1464 Purpose: Describes the membership of a collection resource. 1466 Schema: http://www.ietf.org/standards/dav/ 1467 Parent: ResInfo 1468 Value: ResInfo 1469 Description: Contains zero or more ResInfo elements, which 1470 describe members of the collection. 1472 3.4.7 Href XML Element 1473 10 1474 Name: http://www.ietf.org/standards/dav/href 1475 Purpose: To identify that the content of the element is a URI. 1476 Schema: http://www.ietf.org/standards/dav/ 1477 Parent: Any 1478 Value: URI ; See section 3.2.1 of [Fielding et al., 1997] 1480 3.4.8 Example 1482 INDEX /user/yarong/dav_drafts/ HTTP/1.1 1483 Host: www.microsoft.com 1485 HTTP/1.1 200 OK 1486 Content-Type: text/xml 1487 Content-Length: xxx 1488 Last-Modified: Thu, 11 Sep 1997 23:45:12 GMT 1489 ETag: "fooyyybar" 1491 1493 1494 1495 http://www.microsoft.com/user/yarong/dav_drafts/ 1496 1497 1498 1499 WebDAV working drafts directory 1500 1501 true 1502 19970418T070304Z 1503 1504 text/html 1505 2754 1506 en 1507 1508 Fri, 22 Aug 1997 10:11:26 GMT 1509 1510 "8675309" 1511 1512 1513 text/xml 1514 xxx 1515 1516 Thu, 11 Sep 1997 23:45:12 GMT 1517 1518 "fooyyybar" 1519 1520 1522 1523 1524 1525 http://www.microsoft.com/user/yarong/dav_drafts/base 1526 1527 1528 1531 False 1532 1533 1534 WebDAV Name Space Operations Draft 1535 1536 19970320T230525Z 1538 1539 application/msword 1540 1400 1541 en 1542 1543 Fri, 22 Aug 1997 18:22:56 GMT 1544 1545 "8675309" 1546 1547 1548 1549 1550 1551 This example shows the result of the INDEX method applied to the 1552 collection resource 1553 http://www.microsoft.com/user/yarong/dav_drafts/. It returns a 1554 response body in XML format, which gives information about the 1555 container and its sole member, 1556 http://www.microsoft.com/user/yarong/dav_drafts/base. The entry 1557 on the collection confirms that resource the INDEX was executed 1558 on is a collection. The result also contains the URI of the 1559 IsCollection property on the member resource. 1561 3.5 Behavior of RFC 2068 Methods on Collections 1563 With the introduction of the collection resource type to the HTTP 1564 object model, it is necessary to define the behavior of the 1565 existing methods (defined in RFC 2068) when invoked on a 1566 collection resource to avoid ambiguity. While some methods, such 1567 as OPTIONS and TRACE behave identically when applied to 1568 collections, GET, HEAD, POST, PUT, and DELETE require some 1569 additional explanation. 1571 3.5.1 GET, HEAD for Collections 1573 The semantics of GET are unchanged when applied to a collection, 1574 since GET is defined as, "retrieve whatever information (in the 1575 form of an entity) is identified by the Request-URI" [Fielding et 1576 al., 1997]. GET when applied to a collection MAY return the 1577 contents of an "index.html" resource, a human-readable view of 1578 the contents of the collection, or something else altogether, and 1579 hence it is possible the result of a GET on a collection will 1580 bear no correlation to the state of the collection. 1581 Similarly, since the definition of HEAD is a GET without a 1582 response message body, the semantics of HEAD are unmodified when 1583 applied to collection resources. 1585 3.5.2 POST for Collections 1587 Since by definition the actual function performed by POST is 1588 determined by the server and often depends on the particular 1589 resource, the behavior of POST when applied to collections cannot 1590 be meaningfully modified because it is largely undefined. Thus 1591 the semantics of POST are unmodified when applied to a 1592 collection. 1594 3.5.3 PUT for Collections 1596 As defined in the HTTP/1.1 specification [Fielding et al., 1997], 1597 the "PUT method requests that the enclosed entity be stored under 1598 the supplied Request-URI." Since submission of an entity 1599 representing a collection would implicitly encode creation and 1600 deletion of resources, this specification intentionally does not 1601 define a transmission format for creating a collection using PUT. 1602 Instead, the MKCOL method is defined to create collections. If a 1603 PUT is invoked on a collection resource it MUST fail. 1604 When the PUT operation creates a new non-collection resource all 1605 ancestors MUST already exist. If all ancestors do not exist, the 1606 method MUST fail with a 409 Conflict status code. For example, 1607 if resource /a/b/c/d.html is to be created and /a/b/c/ does not 1608 exist, then the request MUST fail. 1610 3.5.3.1 PUT for Non-Collection Resources 1612 A PUT performed on an existing resource replaces the GET response 1613 entity of the resource, but MUST NOT change the value of any dead 1614 properties defined on the resource. Live properties defined on 1615 the resource MAY be recomputed during PUT processing. 1617 3.5.4 DELETE for Collections 1619 When DELETE is applied to a collection without internal members 1620 the collection resource, along with its properties, and external 1621 members, MUST be deleted. A DELETE method applied to a 1622 collection resource containing internal member resources MUST 1623 fail with a 409 Conflict status code1112. 1625 3.5.5 13DELETE Method for Non-Collection Resources 1627 If the DELETE method is issued to a non-collection resource which 1628 is an internal member of a collection, then during DELETE 1629 processing a server MUST remove the Request-URI from its parent 1630 collection. A server MAY remove the URI of a deleted resource 1631 from any collections of which the resource is an external member. 1633 3.6 COPY Method 1635 3.6.1 Problem Description 1637 Currently, in order to create a copy of a resource, the client 1638 must GET an entity and then PUT that entity to the desired 1639 destination. This requires (1) an entity to be transmitted to and 1640 from the server and (2) that the resource be expressible as an 1641 entity with complete fidelity. 1642 This is problematic because of the network traffic involved in 1643 making a copy, and because there is often no way to fully express 1644 a resource as an entity without a loss of fidelity. 1646 3.6.2 Solution Requirements 1648 The solution: 1649 - MUST allow a principal to create a copy of a resource 1650 without having to transmit the resource to and from the server. 1652 3.6.3 The Request 1654 The COPY method creates a duplicate of the source resource, given 1655 by the Request-URI, in the destination resource, given by the 1656 Destination header. The Destination header MUST be present. The 1657 exact behavior of the COPY method depends on the type of the 1658 source resource. 1660 3.6.3.1 COPY for HTTP/1.1 resources 1662 When the source resource is not a collection, and is not a 1663 property, the body of the destination resource MUST be octet-for- 1664 octet identical to the body of the source resource. Alterations 1665 to the destination resource do not modify the source resource. 1666 Alterations to the source resource do not modify the destination 1667 resource. Thus, all copies are performed "by-value". 1668 All properties on the source resource MUST be duplicated on the 1669 destination resource, subject to modifying headers, following the 1670 definition for copying properties. 1672 3.6.3.2 COPY for Properties 1674 The following section defines how properties on a resource are 1675 handled during a COPY operation. 1676 Live properties SHOULD be duplicated as identically behaving live 1677 properties at the destination resource. Since they are live 1678 properties, the server determines the syntax and semantics (hence 1679 value) of these properties. Properties named by the Enforce- 1680 Live- 1681 Properties header MUST be live on the destination resource, or 1682 the method MUST fail. If a property is not named by Enforce- 1683 Live- 1684 Properties and cannot be copied live, then its value MUST be 1685 duplicated, octet-for-octet, in an identically named, dead 1686 resource on the destination resource. 1687 If a property on the source already exists on the resource and 1688 the overwrite header is set to TRUE then the property at the 1689 destination MUST be overwritten with the property from the 1690 source. If the overwrite header is false and the previous 1691 situation exists then the COPY MUST fail with a 409 Conflict. 1693 3.6.3.3 COPY for Collections 1695 A COPY on a collection causes a collection resource to be created 1696 at the destination with the same properties, but without any 1697 members, internal or external. All properties on the source 1698 collection are copied over to the destination collection. Where 1699 there is a conflict the source properties will overwrite the 1700 destination properties. Any members at theMUST be duplicated on 1701 the destination collection, subject to modifying headers, 1702 following the definition for copying properties. 1704 3.6.3.4 Type Interactions 1706 If the destination resource identifies a property and the source 1707 resource is not a property, then the copy SHOULD fail. 1708 If the destination resource identifies a collection and the 1709 Overwrite header is "true," prior to performing the copy, the 1710 server MUST perform a DELETE operation on the collection. 1712 3.6.4 The Response 1714 200 (OK) The source resource was successfully copied to a pre- 1715 existing destination resource. 1716 201 (Created) The source resource was successfully copied. The 1717 copy operation resulted in the creation of a new resource. 1718 412 (Precondition Failed) This status code MUST be returned if 1719 the server was unable to maintain the liveness of the properties 1720 listed in the Enforce-Live-Properties header, or if the Overwrite 1721 header is false, and the state of the destination resource is 1722 non- 1723 null. 1724 417 (Insufficient Space on Resource) - The destination resource 1725 does not have sufficient space to record the state of the 1726 resource after the execution of this method. 1727 500 (Server Error) The resource was in such a state that it could 1728 not be copied. This may occur if the Destination header specifies 1729 a resource that is outside the namespace the resource is able to 1730 interact with. 1732 3.6.5 Examples 1734 3.6.5.1 Overwrite Example 1736 This example shows resource 1737 http://www.ics.uci.edu/~fielding/index.html being copied to the 1738 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1739 contents of the destination resource were overwritten, if non- 1740 null. 1742 COPY /~fielding/index.html HTTP/1.1 1743 Host: www.ics.uci.edu 1744 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1746 HTTP/1.1 200 OK 1748 3.6.5.2 No Overwrite Example 1750 The following example shows the same copy operation being 1751 performed, except with the Overwrite header set to "false." A 1752 response of 412, Precondition Failed, is returned because the 1753 destination resource has a non-null state. 1755 COPY /~fielding/index.html HTTP/1.1 1756 Host: www.ics.uci.edu 1757 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1758 Overwrite: "false" 1760 HTTP/1.1 412 Precondition Failed 1762 3.7 MOVE Method 1763 3.7.1 Problem Description 1765 The move operation on a resource is the logical equivalent of a 1766 copy followed by a delete, where the actions are performed 1767 atomically. Using RFC 2068 methods only, this procedure could be 1768 performed in several steps. First, the client could issue a GET 1769 to retrieve a representation of a resource, issue a DELETE to 1770 remove the resource from the server, then use PUT to place the 1771 resource on the server with a new URI. As is the case for COPY - 1772 because of the network traffic involved in making a move, and 1773 because there is often no way to fully express a resource as an 1774 entity without a loss of fidelity - server move functionality is 1775 preferable. 1776 With a WEBDAV server, a principal may accomplish this task by 1777 issuing a COPY and then DELETE. Network load decreases, but the 1778 server load may still be significant because the server must 1779 create a duplicate resource. Were a server to know beforehand 1780 that a principal intended to perform COPY and DELETE operations 1781 in succession, it could avoid the creation of a duplicate 1782 resource. 1784 3.7.2 Solution Requirements 1786 The solution: 1787 - Must prevent the unneeded transfer of entity bodies from and 1788 to the server. 1789 - Must prevent the unneeded creation of copies by the server. 1791 3.7.3 The Request 1793 The move operation on a resource is the logical equivalent of a 1794 copy followed by a delete, where the actions are performed 1795 atomically. If a resource exists at the destination, the 1796 destination resource will be DELETEd as a side effect of the MOVE 1797 operation, subject to the restrictions of the overwrite header. 1799 3.7.4 The Response 1801 200 (OK) - The resource was moved. A successful response must 1802 contain the Content-Location header, set equal to the URI in 1803 source. This lets caches properly flush any cached entries for 1804 the source. Unfortunately the Content-Location header only allows 1805 a single value so it is not possible for caches unfamiliar with 1806 the MOVE method to properly clear their caches. 1807 412 (Precondition Failed) This status code MUST be returned if 1808 the server was unable to maintain the liveness of the properties 1809 listed in the Enforce-Live-Properties header, or if the Overwrite 1810 header is false, and the state of the destination resource is 1811 non- 1812 null. 1813 501 (Not Implemented) - This may occur if the Destination header 1814 specifies a resource which is outside its domain of control 1815 (e.g., stored on another server) resource and the server either 1816 refuses or is incapable of moving to an external resource. 1817 502 (Bad Gateway) - This may occur when moving to external 1818 resources and the destination server refused to accept the 1819 resource. 1821 3.7.5 Examples 1822 3.7.5.1 Overwrite Example 1824 This example shows resource 1825 http://www.ics.uci.edu/~fielding/index.html being moved to the 1826 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1827 contents of the destination resource were overwritten, if non- 1828 null. 1830 MOVE /~fielding/index.html HTTP/1.1 1831 Host: www.ics.uci.edu 1832 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 1834 HTTP/1.1 200 OK 1835 Content-Location: 1836 http://www.ics.uci.edu/users/f/fielding/index.html 1838 3.8 ADDREF Method 1840 3.8.1 Problem Definition 1842 There needs to be a way to add an external member to a 1843 collection. 1845 3.8.2 Solution Requirements 1847 The solution must: 1848 - allow access control 1849 - allow referencing to URIs of external members 1850 - not require a body 1852 3.8.3 The Request 1854 The ADDREF method adds the URI specified in the Collection-Member 1855 header as an external member to the collection specified by the 1856 Request-URI. The value in the Collection-Member header MUST be an 1857 absolute URI meeting the requirements of an external member URI. 1858 It is not an error if the URI specified in the Collection-Member 1859 header already exists as an external member of the collection, 1860 however, after processing ADDREF there MUST be only one instance 1861 of the URI in the collection. If the URI specified in the 1862 Collection-Member header already exists as an internal member of 1863 the collection, the ADDREF method MUST fail with a 412 1864 Precondition Failed status code. 1866 3.8.4 Example 1868 ADDREF /~whitehead/dav/ HTTP/1.1 1869 HOST: www.ics.udi.edu 1870 Collection-Member: http://www.ietf.org/standards/dav/ 1872 HTTP/1.1 200 OK 1874 3.9 DELREF Method 1876 3.9.1 Problem Definition 1877 There needs to be a way to remove an external member from a 1878 collection. 1880 3.9.2 Solution Requirements 1882 The solution must: 1883 - allow access control 1884 - allow referencing to URIs of external members 1885 - not require a body 1887 3.9.3 The Request 1889 The DELREF method removes the URI specified in the Collection- 1890 Member header from the collection specified by the Request-URI. 1891 DELREFing a URI which is not a member of the collection is not an 1892 error. DELREFing an internal member MUST fail with a 412 1893 Precondition Failed status code. 1895 3.9.4 Example 1897 DELREF /~whitehead/dav/ HTTP/1.1 1898 Host: www.ics.udi.edu 1899 Collection-Member: http://www.ietf.org/standards/dav/ 1901 HTTP/1.1 200 OK 1903 3.10 PATCH Method 1905 3.10.1 Problem Definition 1907 At present, if a principal wishes to modify a resource, they must 1908 issue a GET against the resource, modify their local copy of the 1909 resource, and then issue a PUT to place the modified resource on 1910 the server. This procedure is inefficient because the entire 1911 entity for a resource must be transmitted to and from the server 1912 in order to make even small changes. Ideally, the update entity 1913 transmitted to the server should be proportional in size to the 1914 modifications. 1916 3.10.2 Solution Requirements 1918 The solution must: 1919 - allow partial modification of a resource without having to 1920 transmit the entire modified resource 1921 - allow byte-range patching 1922 - allows extensions so that patches can be done beyond simple 1923 byte-range patching 1924 - allow ranges to be deleted, inserted, and replaced 1926 3.10.3 The Request 1928 The request entity of the PATCH method contains a list of 1929 differences between the resource identified by the Request-URI 1930 and the desired content of the resource after the PATCH action 1931 has been applied. The list of differences is in a format defined 1932 by the media type of the entity (e.g., "application/diff") and 1933 must include sufficient information to allow the server to 1934 convert the original version of the resource to the desired 1935 version. Processing performed by PATCH is atomic, hence all 1936 changes MUST be successfully executed or the method fails. PATCH 1937 MUST fail if executed on a non-existent resource; i.e. PATCH does 1938 not create a resource as a side effect. 1939 If the request appears (at least initially) to be acceptable, the 1940 server MUST transmit an interim 100 response message after 1941 receiving the empty line terminating the request headers and 1942 continue processing the request. Since the semantics of PATCH 1943 are non-idempotent, responses to this method are not cacheable. 1944 While server support for PATCH is optional, if a server does 1945 support PATCH, it MUST support at least the text/xml diff format 1946 defined below. Support for the VTML difference format [VTML] is 1947 recommended, but not required. 1949 3.10.4 text/xml elements for PATCH 1951 The resourceupdate XML element contains a set of XML sub-entities 1952 that describe modification operations. The name and meaning of 1953 these XML elements is given below. Processing of these directives 1954 MUST be performed in the order encountered within the XML 1955 document. A directive operates on the resource as modified by 1956 all previous directives (executed in sequential order). The 1957 length of the resource MAY be extended or reduced by a PATCH. 1958 The changes specified by the resourceupdate XML element MUST be 1959 executed atomically. 1961 3.10.4.1 ResourceUpdate 1963 Name: http://www.ietf.org/standards/dav/patch/resourceupdate 1964 Purpose: Contains an ordered set of changes to a non- 1965 collection, non-property resource. 1966 Schema: http://www.ietf.org/standards/dav/patch/ 1967 Parent: Any 1968 Value: *(Insert | Delete | Replace) 1970 3.10.4.2 Insert 1972 Name: http://www.ietf.org/standards/dav/patch/insert 1973 Purpose: Insert the XML element�s contents starting at the 1974 specified octet. 1975 Schema: http://www.ietf.org/standards/dav/patch/ 1976 Parent: ResourceUpdate 1977 Value: The insert XML element MUST contain an Octet-Range 1978 XML element that specifies an octet position within the body of a 1979 resource. A value of "end" specifies the end of the resource. 1980 The body of the insert XML element contains the octets to be 1981 inserted. 1982 Please note that in order to protect the white space contained in 1983 this XML element the following attribute/value MUST be included 1984 in the element: XML-SPACE = "PRESERVE". 1986 3.10.4.3 Delete 1988 Name: http://www.ietf.org/standards/dav/patch/delete 1989 Purpose: Removes the specified range of octets. 1990 Schema: http://www.ietf.org/standards/dav/patch/ 1991 Parent: ResourceUpdate 1992 Value: The Delete XML element MUST contain an octet-range 1993 XML element. 1994 Discussion: The octets that are deleted are removed, which means 1995 the resource is collapsed and the length of the resource is 1996 decremented by the size of the octet range. It is not 1997 appropriate to replace deleted octets with zeroed-out octets, 1998 since zero is a valid octet value. 2000 3.10.4.4 Replace 2002 Name: http://www.ietf.org/standards/dav/patch/replace 2003 Purpose: Replaces the specified range of octets with the 2004 contents of the XML element. If the number of octets in the XML 2005 element is different from the number of octets specified, the 2006 update MUST be rejected. 2007 Schema: http://www.ietf.org/standards/dav/patch/ 2008 Parent: ResourceUpdate 2009 Value: The Replace XML element MUST contain an octet- 2010 range XML element. The contents of the entity are the replacement 2011 octets. 2012 Please note that in order to protect the white space contained in 2013 this XML element the following attribute/value MUST be included 2014 in the element: XML-SPACE = "PRESERVE". 2016 3.10.4.5 Octet-Range Attribute 2018 Name: http://www.ietf.org/standards/dav/patch/octet- 2019 range 2020 Purpose: Specifies a range of octets that the enclosing property 2021 effects. 2022 Schema: http://www.ietf.org/standards/dav/patch/ 2023 Parent: Insert, Delete, Replace 2024 Value: number ["-" (number | "end")] 2025 Number = 1*Digit 2026 Description: Octet numbering begins with 0. If the octet contains 2027 a single number then the operation is to begin at that octet and 2028 to continue for a length specified by the operation. In the case 2029 of a delete, this would mean to delete a single octet. In the 2030 case of an insert this would mean to begin the insertion at the 2031 specified octet and to continue for the length of the included 2032 value, extending the resource if necessary. In the case of 2033 replace, the replace begins at the specified octet and overwrites 2034 all that follow to the length of the included value. 2036 3.10.5 The Response 2038 200 (OK) - The request entity body was processed without error, 2039 resulting in an update to the state of the resource. 2040 409 (Conflict) - If the update information in the request message 2041 body does not make sense given the current state of the resource 2042 (e.g., an instruction to delete a non-existent line), this status 2043 code MAY be returned. 2044 415 (Unsupported Media Type) - The server does not support the 2045 content type of the update instructions in the request message 2046 body. 2047 416 (Unprocessable Entity) - A new status code. The server 2048 understands the content type of the request entity, but was 2049 unable to process the contained instructions. 2050 417 (Insufficient Space on Resource) - The resource does not have 2051 sufficient space to record the state of the resource after the 2052 execution of this method. 2054 3.10.6 Examples 2055 3.10.6.1 HTML file modification 2057 The following example shows a modification of the title and 2058 contents of the HTML resource http://www.example.org/hello.html. 2059 Before: 2060 2061 2062 Hello world HTML page 2063 2064 2065

Hello, world!

2066 2067 2068 PATCH Request: Response: 2069 PATCH hello.html HTTP/1.1 2070 Host: www.example.org 2071 Content-Type: text/xml 2072 Content-Length: xxx 2074 HTTP/1.1 100 Continue 2075 2077 2078 14&003CTITLE&003ENew Title&003C/TITLE&003E 2080 38-50 2081 86&003CP&003ENew paragraph&003C/P&003E 2083 2084 HTTP/1.1 200 OK 2085 After: 2086 2087 2088 New Title 2089 2090 2091

Hello, world!

2092

New paragraph

2093 2094 2096 14 2097 3.11 Headers 2099 3.11.1 Destination Header 2101 The Destination header specifies a destination resource for 2102 methods such as COPY and MOVE, which take two URIs as parameters. 2103 Destination= "Destination" ":" URI 2105 3.11.2 Enforce-Live-Properties Header 2107 The Enforce-Live-Properties header specifies properties that MUST 2108 be "live" after they are copied (moved) to the destination 2109 resource of a copy (or move). If the value "*" is given for the 2110 header, then it designates all live properties on the source 2111 resource. If the value is "Omit" then the server MUST NOT 2112 duplicate on the destination resource any properties that are 2113 defined on the source resource. If this header is not included 2114 then the server is expected to act as defined by the default 2115 property handling behavior of the associated method. 2116 EnforceLiveProperties = "Enforce-Live-Properties" ":" ("*" | 2117 "Omit" | 1#(Property-Name)) 2118 Property-Name = "<" URI ">" 2120 3.11.3 Overwrite Header 2121 The Overwrite header specifies whether the server should 2122 overwrite the state of a non-null destination resource during a 2123 COPY or MOVE. A value of "false" states that the server MUST NOT 2124 perform the COPY or MOVE operation if the state of the 2125 destination resource is non-null. By default, the value of 2126 Overwrite is "true," and a client MAY omit this header from a 2127 request when its value is "true." While the Overwrite header 2128 appears to duplicate the functionality of the If-Match: * header 2129 of HTTP/1.1, If-Match applies only to the Request-URI, and not to 2130 the Destination of a COPY or MOVE. 2131 Overwrite = "Overwrite" ":" ("true" | "false") 2132 If there is a conflict and the Overwrite header equals "true", or 2133 is absent and thus defaults to "true", then the method MUST fail 2134 with a 409 Conflict. 2136 3.11.4 Destroy Header15 2138 When deleting a resource the client often wishes to specify 2139 exactly what sort of delete is being enacted. The Destroy header, 2140 used with the Mandatory header, allows the client to specify the 2141 end result they desire. The Destroy header is specified as 2142 follows: 2143 The Undelete token requests that, if possible, the resource 2144 should be left in a state such that it can be undeleted. The 2145 server is not required to honor this request. 2146 The NoUndelete token requests that the resource MUST NOT be left 2147 in a state such that it can be undeleted. 2148 The VersionDestroy token includes the functionality of the 2149 NoUndelete token and extends it to include having the server 2150 remove all versioning references to the resource that it has 2151 control over. 2152 DestroyHeader = "Destroy" ":" #Choices 2153 Choices = "VersionDestroy" | "NoUndelete" | "Undelete" | token 2154 |"<" URI ">" ; a token extension MUST NOT be used unless it is 2155 specified in a RFC16, otherwise a URI MUST be used for 2156 extensions. 2158 3.11.5 Collection-Member Header 2160 The Collection-Member header specifies the URI of an external 2161 resource to be added/deleted to/from a collection. 2162 CollectionMember = "Collection-Member" ":" URI 2164 3.12 Links 2166 3.12.1 Source Link Property Type 2168 Name: http://www.ietf.org/standards/dav/link/source 2169 Purpose: The destination of the source link identifies the 2170 resource that contains the unprocessed source of the link�s 2171 source. 2172 Schema: http://www.ietf.org/standards/dav/link/ 2173 Parent: Any 2174 Value: An XML document with zero or more link XML 2175 elements. 2176 Discussion: The source of the link (src) is typically the URI of 2177 the output resource on which the link is defined, and there is 2178 typically only one destination (dst) of the link, which is the 2179 URI where the unprocessed source of the resource may be accessed. 2180 When more than one link destination exists, this specification 2181 asserts no policy on ordering. 2183 4 State Tokens 2185 4.1 Overview 2187 4.1.1 Problem Description 2189 There are times when a principal will want to predicate 2190 successful execution of a method on the current state of a 2191 resource. While HTTP/1.1 provides a mechanism for conditional 2192 execution of methods using entity tags via the "If-Match" and 2193 "If- 2194 None-Match" headers, the mechanism is not sufficiently extensible 2195 to express conditional statements involving more generic state 2196 indicators, such as lock tokens. 2198 The fundamental issue with entity tags is that they can only be 2199 generated by a resource. However there are times when a client 2200 will want to be able to share state tokens between resources, 2201 potentially on different servers, as well as be able to generate 2202 certain types of lock tokens without first having to communicate 2203 with a server. 2205 For example, a principal may wish to require that resource B have 2206 a certain state in order for a method to successfully execute on 2207 resource A. If the client submits an e-tag from resource B to 2208 resource A, then A has no way of knowing that the e-tag is meant 2209 to describe resource B. 2211 Another example occurs when a principal wishes to predicate the 2212 successful completion of a method on the absence of any locks on 2213 a resource. It is not sufficient to submit an "If-None-Match: *" 2214 as this refers to the existence of an entity, not of a lock. 2216 This draft defines the term "state token" as an identifier for a 2217 state of a resource. The sections below define requirements for 2218 state tokens and provide a state token syntax, along with two 2219 new headers which can accept the new state token syntax. 2221 4.1.2 Solution Requirements 2223 4.1.2.1 Syntax 2225 Self-Describing. A state token must be self describing such that 2226 upon inspecting a state token it is possible to determine what 2227 sort of state token it is, what resource(s) it applies to, and 2228 what state it represents. 2230 This self-describing nature allows servers to accept tokens from 2231 other servers and potentially be able to coordinate state 2232 information cross resource and cross site through standardized 2233 protocols. For example, the execution of a request on resource A 2234 can be predicated on the state of resource B, where A and B are 2235 potentially on different servers. 2237 Client Generable. The state token syntax must allow, when 2238 appropriate, for clients to generate a state token without having 2239 first communicated with a server. 2241 One drawback of entity tags is that they are set by the server, 2242 and there is no interoperable algorithm for calculating an entity 2243 tag. Consequently, a client cannot generate an entity tag from a 2244 particular state of a resource. However, a state token which 2245 encodes an MD5 state hash could be calculated by a client based 2246 on a client-held state of a resource, and then submitted to a 2247 server in a conditional method invocation. 2249 Another potential use for client generable state tokens is for a 2250 client to generate lock tokens with wild card fields, and hence 2251 be able to express conditionals such as: "only execute this GET 2252 if there are no write locks on this resource." 2254 4.1.2.2 Conditonals 2256 Universal. A solution must be applicable to all requests. 2257 Positive and Negative. Conditional expressions must allow for the 2258 expression of both positive and negative state requirements. 2260 4.2 State Token Syntax 2261 State tokens are URLs employing the following syntax: 2262 State-Token = "StateToken:" Type ":" Resources ":" State-Info 2263 Type = "Type" "=" Caret-encoded-URL 2264 Resources = "Res" "=" Caret-encoded-URL 2265 Caret-encoded-URL = "^" Resource "^" 2266 Resource = 2267 State-Info = *(uchar | reserved) ; uchar, reserved defined 2268 section 3.2.1 of RFC 2068 2270 This proposal has created a new URL scheme for state tokens 2271 because a state token names a network resource using its normal 2272 name, which is typically state-invariant, along with additional 2273 information that specifies a particular state of the resource. 2274 Encoding the state information into the native URL scheme of the 2275 network resource was not felt to be safe, since freedom from name 2276 space collisions could not be guaranteed. If this proposal is 2277 accepted, the StateToken URL scheme will need to be defined and 2278 registered with IANA. 2280 State Token URLs begin with the URL scheme name "StateToken" 2281 rather than the name of the particular state token type they 2282 represent in order to make the URL self describing. Thus it is 2283 possible to examine the URL and know, at a minimum, that it is a 2284 state token. 2286 Labeled name/value pairs are used within the token to allow new 2287 fields to be added. Processors of state tokens MUST be prepared 2288 to accept the fields in whatever order they are present and MUST 2289 ignore any fields they do not understand. 2290 The "Type" field specifies the type of the state information 2291 encoded in the state token. A URL is used in order to avoid 2292 namespace collisions. 2294 The "Res" field identifies the resource for which the state token 2295 specifies a particular state. Since commas and spaces are 2296 acceptable URL characters, a caret is used to delimit a URL. 2297 Since a caret is an acceptable URL character, any instances of it 2298 must be escaped using the % escape convention. 2300 The State-Info production is expanded upon in descriptions of 2301 specific state token types, and is intended to contain the state 2302 description information for a particular state token. 2304 4.3 State Token Conditional Headers 2306 4.3.1 If-State-Match 2308 If-State-Match = "If-State-Match" ":" ("AND" | "OR") 1#("<" 2309 State- 2310 Token ">") 2312 The If-State-Match header is intended to have similar 2313 functionality to the If-Match header defined in section 14.25 of 2314 RFC 2068. 2316 If the AND keyword is used and all of the state tokens identify 2317 the state of the resource, then the server MAY perform the 2318 requested method. If the OR keyword is used and any of the state 2319 tokens identifies the current state of the resource, then server 2320 MAY perform the requested method. If neither of the keyword 2321 requirements is met, the server MUST NOT perform the requested 2322 method, and MUST return a 412 (Precondition Failed) response. 2324 4.3.2 If-None-State-Match 2326 If-None-State-Match = "If-None-State-Match" ":" 1#("<" State- 2327 Token ">") 2329 The If-None-State-Match header is intended to have similar 2330 functionality to the If-None-Match header defined in section 2331 14.26 of RFC 2068. 2333 If any of the state tokens identifies the current state of the 2334 resource, the server MUST NOT perform the requested method. 2335 Instead, if the request method was GET, HEAD, INDEX, or GETMETA, 2336 the server SHOULD respond with a 304 (Not Modified) response, 2337 including the cache-related entity-header fields (particularly 2338 ETag) of the current state of the resource. For all other 2339 request methods, the server MUST respond with a status of 412 2340 (Precondition Failed). 2342 If none of the state tokens identifies the current state of the 2343 resource, the server MAY perform the requested method. 2345 Note that the "AND" and "OR" keywords specified with the If- 2346 State- 2347 Match header are intentionally not defined for If-None-State- 2348 Match, because this functionality is not required. 2350 4.4 State Token Header 2352 State-Token-Header = "State-Token" ":" 1#("<" State-Token ">") 2353 The State Token header is intended to have similar functionality 2354 to the etag header defined in section 14.20 of RFC 2068. The 2355 purpose of the tag is to return state tokens defined on a 2356 resource in a response. The contents of the state-token are not 2357 guaranteed to be exhaustive and are generally used to return a 2358 new state token that has been defined as the result of a method. 2359 For example, if a LOCK method were successfully executed on a 2360 resource the response would include a state token header with the 2361 lock state token included. 2363 4.5 E-Tags 2364 E-tags have already been deployed using the If-Match and If-None- 2365 Match headers. Introducing two mechanisms to express e-tags 2366 would only confuse matters, therefore e-tags should continue to 2367 be expressed using quoted strings and the If-Match and If-None- 2368 Match headers. 2370 5 Locking 2372 5.1 Problem Description - Overview 2374 Locking is used to arbitrate access to a resource amongst 2375 principals that have equal access rights to that resource. 2377 This draft allows locks to vary over two parameters, the number 2378 of principals involved and the type of access to be granted. This 2379 draft will only provide for the definition of locking for one 2380 access type, write. However, the syntax is extensible enough to 2381 allow for the specification of other access types. It is a goal 2382 of this proposal that it use the same access verbs as will be 2383 defined in the access control draft. 2385 5.1.1 Exclusive Vs. Shared Locks 2387 The most basic form of LOCK is an exclusive lock. This is a lock 2388 where the access right in question is only granted to a single 2389 principal. The need for this arbitration results from a desire to 2390 avoid having to constantly merge results. In fact, many users so 2391 dislike having to merge that they would rather serialize their 2392 access to a resource rather than have to constantly perform 2393 merges. 2395 However, there are times when the goal of a lock is not to 2396 exclude others from exercising an access right but rather to 2397 provide a mechanism for principals to indicate that they intend 2398 to exercise their access right. Shared locks are provided for 2399 this case. A shared lock allows multiple principals to receive a 2400 lock, hence any principal with appropriate access can get the 2401 lock. 2403 With shared locks there are two trust sets that affect a 2404 resource. The first trust set is created by access permissions. 2405 Principals who are trusted, for example, may have permission to 2406 write the resource, those who are not, don't. Among those who 2407 have access permission to write the resource, the set of 2408 principals who have taken out a shared lock also must trust each 2409 other, creating a (probably) smaller trust set within the access 2410 permission write set. 2412 Starting with every possible principal on the Internet, in most 2413 situations the vast majority of these principals will not have 2414 write access to a given resource. Of the small number who do 2415 have write access, some principals may decide to guarantee their 2416 edits are free from overwrite conflicts by using exclusive write 2417 locks in conjunction with a precondition header (If-State-Match) 2418 that checks for existence of the lock prior to writing the 2419 resource. Others may decide they trust their collaborators (the 2420 potential set of collaborators being the set of principals who 2421 have write permission) and use a shared lock, which informs their 2422 collaborators that a principal is potentially working on the 2423 resource. 2425 The WebDAV extensions to HTTP do not need to provide all of the 2426 communications paths necessary for principals to coordinate their 2427 activities. When using shared locks, principals may use any out 2428 of band communication channel to coordinate their work (e.g., 2429 face-to-face interaction, written notes, post-it notes on the 2430 screen, telephone conversation, email). The intent of a shared 2431 lock is to let collaborators know who else is potentially working 2432 on a resource. 2434 Why not use exclusive write locks all the time? Experience from 2435 initial Web distributed authoring systems has indicated that 2436 exclusive write locks are often too rigid. An exclusive write 2437 lock is used to enforce a particular editing process: take out 2438 exclusive write lock, read the resource, perform edits, write the 2439 resource, release the lock. What happens if the lock isn't 2440 released? While the time-out mechanism provides one solution, if 2441 you need to force the release of a lock immediately, it doesn't 2442 help much. Granted, an administrator can release the lock for 2443 you, but this could become a significant burden for large sites. 2444 Further, what if the administrator can't be reached immediately? 2446 Despite their potential problems, exclusive write locks are 2447 extremely useful, since often a guarantee of freedom from 2448 overwrite conflicts is exactly what is needed. The solution: 2449 provide exclusive write locks, but also provide a less strict 2450 mechanism in the form of shared locks which can be used by a set 2451 of people who trust each other and who have access to a 2452 communications channel external to HTTP which can be used to 2453 negotiate writing to the resource. 2455 5.1.2 Required Support 2457 A DAV compliant server is not required to support locking in any 2458 form. If the server does support locking it may choose to support 2459 any combination of exclusive and shared locks for any access 2460 types. 2462 The reason for this flexibility is that server implementers have 2463 said that they are willing to accept minimum requirements on all 2464 services but locking. Locking policy strikes to the very heart of 2465 their resource management and versioning systems and they require 2466 control over what sort of locking will be made available. For 2467 example, some systems only support shared write locks while 2468 others only provide support for exclusive write locks. As each 2469 system is sufficiently different to merit exclusion of certain 2470 locking features, the authors are proposing that locking be 2471 allowed as the sole axis of negotiation within DAV. 2473 5.2 LOCK Method 2475 5.2.1 Operation 2477 A lock method invocation creates the lock specified by the Lock- 2478 Info header on the request-URI. Lock method requests SHOULD NOT 2479 have a request body. A user-agent SHOULD submit an Owner header 2480 field with a lock request. 2482 A successful response to a lock invocation MUST include a Lock- 2483 Token header. If the server supports a time based lock removal 2484 mechanism on the resource, a successful lock invocation SHOULD 2485 return a Time-Out header. 2487 5.2.2 Effect of Locks on Properties and Containers 2489 By default a lock affects the entire state of the resource, 2490 including its associated properties. As such it is illegal to 2491 specify a lock on a property. For containers, a lock also affects 2492 the ability to add or remove members. The nature of the effect 2493 depends upon the type of access control involved. The Depth 2494 header expresses the general semantics of a LOCK method request 2495 when invoked on a collection (note that specific lock types may 2496 restrict the effect of a lock, for example limiting the allowable 2497 values of the Depth header): 2498 � A Depth header (defined in the namespace draft) may be used 2499 on a LOCK method when the LOCK method is applied to a 2500 collection 2501 resource. The legal values for Depth on a LOCK are 0, 1, and 2502 Infinity. A Depth of 0 instructs the resource to just lock the 2503 container. As previously mentioned, depending on the type of 2504 lock, the lock affects the ability to add or remove members of 2505 the container. 2506 � A Depth of 1 means that the container is locked and a LOCK 2507 is executed on the container�s propagate members with a Depth 2508 of 2509 0 and If-Range, If-Modified-Since, If-Unmodified-Since, If- 2510 Match 2511 and If-None-Match headers are dropped. However, the effects of 2512 the LOCK MUST be atomic in that either the container and all of 2513 its members are locked or no lock is granted. The result of a 2514 Depth 1 lock is a single lock token which represents the lock 2515 on 2516 the container and all of its members. This lock token may be 2517 used 2518 in an If-State-Match or If-Not-State-Match header against any 2519 of 2520 the resources covered by the lock. Since the lock token 2521 represents a lock on all the resources, an UNLOCK using that 2522 token will remove the lock from all included resources, not 2523 just 2524 the resource the UNLOCK was executed on. 2525 � A Depth of infinity means that the LOCK is recursively 2526 executed, with a Depth of infinity, on the collection and all 2527 of 2528 its propagate members and all of their propagate members. As 2529 with 2530 a Depth of 1, the LOCK must be granted in total or not at all. 2531 Otherwise the lock operates in the same manner as a Depth of 1 2532 lock. 2534 The default behavior when locking a container is to act as if a 2535 "Depth: 0" header had been placed on the method. 2537 5.2.3 Locking Replicated Resources 2539 Some servers automatically replicate resources across multiple 2540 URLs. In such a circumstance the server MAY only accept a lock on 2541 one of the URLs if the server can guarantee that the lock will be 2542 honored across all the URLs. 2544 5.2.4 Interaction with other Methods 2546 Only two methods, MOVE and DELETE, have side effects which 2547 involve locks. When a resource is moved, its lock SHOULD be moved 2548 with it. However this may not always be possible and there is 2549 currently no proposal to create a header which would specify that 2550 the lock request should fail if the resource�s locks can not be 2551 maintained. A COPY MUST NOT copy any locks on the source resource 2552 over to the destination resource. Deleting a resource MUST remove 2553 all locks on the resource. 2555 5.2.5 Lock Compatibility Table 2557 The table below describes the behavior that occurs when a lock 2558 request is made on a resource. 2560 Current lock state/ Shared Lock Exclusive Lock 2561 Lock request 2562 None True True 2563 Shared Lock True False 2564 Exclusive Lock False False* 2566 Legend: True = lock MAY be granted. False = lock MUST NOT be 2567 granted. *=if the principal requesting the lock is the owner of 2568 the lock, the lock MAY be regranted. 2570 The current lock state of a resource is given in the leftmost 2571 column, and lock requests are listed in the first row. The 2572 intersection of a row and column gives the result of a lock 2573 request. For example, if a shared lock is held on a resource, 2574 and an exclusive lock is requested, the table entry is "false", 2575 indicating the lock must not be granted. 2577 If an exclusive lock is re-requested by the principal who owns 2578 the lock, the lock MAY be regranted. If the lock is regranted, 2579 the same lock token that was previously issued MUST be returned. 2581 5.2.6 Status Codes 2583 412 "Precondition Failed" - The included state-token was not 2584 enforceable on this resource. 2586 416 "Locked" - The resource is locked so the method has been 2587 rejected. 2589 5.2.7 Example 2591 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2592 Host: webdav.sb.aol.com 2593 Lock-Info: LockType=Write LockScope=Exclusive 2594 Owner: 2596 HTTP/1.1 200 OK 2597 State-Token: StateToken:Type=^DAV:/LOCK/DAVLOCK^:Res=^http://www. 2598 ics.uci.edu/workspace/webdav/proposal.doc^:LockType=Write:LockSco 2599 pe=Exclusive:ServerID=12382349AdfFFF 2600 Time-Out: ClockType=Activity TimeType=second;604800 2601 This example shows the successful creation of an exclusive write 2602 lock on resource 2603 http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The 2604 resource http://www.ics.uci.edu/~ejw/contact.html contains 2605 contact information for the owner of the lock. The server has an 2606 activity-based timeout policy in place on this resource, which 2607 causes the lock to automatically be removed after 1 week (604800 2608 seconds). The response has a Lock-Token header that gives the 2609 state token URL for the lock token generated by this lock 2610 request. 2612 5.2.8 Lock-Info Request Header 2614 The Lock-Info header specifies the scope and type of a lock for a 2615 LOCK method request. The syntax specification below is 2616 extensible, allowing new type and scope identifiers to be added. 2617 LockInfo = "Lock-Info" ":" DAVLockType SP DAVLockScope CRLF 2618 DAVLockType = "LockType" "=" DAVLockTypeValue 2619 DAVLockTypeValue = ("Write" | *(uchar | reserved)) 2620 DAVLockScope = "LockScope" "=" DAVLockScopeValue 2621 DAVLockScopeValue = ("Exclusive" |"Shared" | *(uchar | reserved)) 2623 5.2.9 Owner Request Header 2625 5.2.9.1 Problem Description 2627 When discovering the list of owners of locks on a resource, a 2628 principal may want to be able to contact the owner directly. For 2629 this to be possible the lock discovery mechanism must provide 2630 enough information for the lock owner to be contacted. 2632 5.2.9.2 Solution Requirements 2634 Not all systems have authentication procedures that provide 2635 sufficient information to identify a particular user in a way 2636 that is meaningful to a human. In addition, many systems that do 2637 have sufficient information, such as a name and e-mail address, 2638 do not have the ability to associate this information with the 2639 lock discovery mechanism. Therefore a means is needed to allow 2640 principals to provide authentication in a manner which will be 2641 meaningful to a human. 2643 The From header (defined in RFC 2068), which contains only an 2644 email mailbox, is not sufficient for the purposes of quick 2645 identification. When desperately looking for someone to remove a 2646 lock, e-mail is often not sufficient. A telephone number (cell 2647 number, pager number, etc.) would be better. Furthermore, the 2648 email address in the From field may or may not support including 2649 the owners name and that name is often set to an alias anyway. 2650 Therefore a header more flexible than From is required. 2652 5.2.9.3 Syntax 2654 Owner = "Owner" ":" (("<" URI ">") | quoted-string) 2655 The URI SHOULD provide a means for either directly contacting the 2656 principal (such as a telephone number or e-mail URI), or for 2657 discovering the principal (such as the URL of a homepage). The 2658 quoted string SHOULD provide a means for directly contacting the 2659 principal, such as a name and telephone number. 2661 5.2.10 Time-Out Header 2663 5.2.10.1 Problem Description 2665 In a perfect world principals take out locks, use the resource as 2666 needed, and then remove the lock when it is no longer needed. 2668 However, this scenario is frequently not completed, leaving 2669 active but unused locks. Reasons for this include client programs 2670 crashing and loosing information about locks, users leaving their 2671 systems for the day and forgetting to remove their locks, etc. As 2672 a result of this behavior, servers need to establish a policy by 2673 which they can remove a lock without input from the lock owner. 2674 Once such a policy is instituted, the server also needs a 2675 mechanism to inform the principal of the policy. 2677 5.2.10.2 Solution Requirements 2679 There are two basic lock removal policies, administrator and time 2680 based remove. In the first case a principal other than the lock 2681 owner has sufficient access rights to order the lock removed, 2682 even though they did not take it out. User-agents MUST assume 2683 that such a mechanism is available and thus locks may arbitrarily 2684 disappear at any time. If their actions require confirmation of 2685 the existence of a lock then the If-State headers are available. 2687 The second solution, is the time based removal policy. Activity 2688 based systems set a timer as soon as the lock is taken out. Every 2689 time a method is executed on the resource, the timer is reset. If 2690 the timer runs out, the lock is removed. 2692 Finally, some systems only allow locks to exist for the duration 2693 of a session, where a session is defined as the time when the 2694 HTTP connection that was used to take out the lock remains 2695 connected. This mechanism is used to allow programs which are 2696 likely to be improperly exited, such as JAVA programs running in 2697 a browser, to take out locks without leaving a lot of ownerless 2698 locks around when they are improperly exited. 2700 5.2.10.3 Syntax 2702 TimeOut = "Time-Out" ":" ((TimeOutType SP Session) | TimeOutVal | 2703 Session) CRLF 2704 TimeOutType = ClockType SP TimeType 2705 ClockType = "ClockType" "=" ClockTypeValue 2706 ClockTypeValue = "Activity" 2707 TimeType = "TimeType" "=" TimeTypeValue 2708 TimeTypeValue = "Second" ";" DAVTimeOutVal 2709 DAVTimeOutVal = 1*digit 2710 Session = "Session" "=" ("Yes" | "No") 2712 The "Second" TimeType specifies the number of seconds that may 2713 elapse before the lock is automatically removed. A server MUST 2714 not generate a time out value for "second" greater than 2^32-1. 2716 If no time based system is in use then a Time-Out header MUST NOT 2717 be returned. The Time-Out header MUST only be returned in a 2718 response to a LOCK request.When session is set to yes then 2719 whatever clocktype and timetype is being used, their effects are 2720 scoped within that particular session. So an absolute lock with a 2721 ten day expiration period will only remain active so long as the 2722 session remains active. A DAVTimeOutVal value must be greater 2723 than zero. 2725 Clients MAY include TimeOut headers in their LOCK requests. 2726 However the server is not required to honor or even consider the 2727 request. The primary purpose in allowing clients to submit a 2728 TimeOut header is to inform the server if the client is 2729 requesting a session based lock. If a timeout is associated with 2730 the lock, the server MUST return a TimeOut header with a valid 2731 value. 2733 5.2.11 State-Token Header 2735 5.2.11.1 Problem Definition 2737 Program A, used by User A, takes out a write lock on a resource. 2738 Program B, also run by User A, then proceeds to perform a PUT to 2739 the locked resource. The PUT will succeed because locks are 2740 associated with a principal, not a program, and thus program B, 2741 because it is acting with principal A�s credential, will be 2742 allowed to perform the PUT. In reality program B had no knowledge 2743 of the lock and had it had such knowledge, would not have 2744 overwritten the resource. Hence, a mechanism is needed to prevent 2745 different programs from accidentally ignoring locks taken out by 2746 other programs with the same authorization. 2748 5.2.11.2 Solution Requirement 2750 The solution must not require principals to perform discovery in 2751 order to prevent accidental overwrites as this could cause race 2752 conditions. 2754 The solution must not require that clients guess what sorts of 2755 locks might be used and use if-state-match headers with wildcards 2756 to prevent collisions. The problem with trying to "guess" which 2757 locks are being used is that new lock types might be introduced, 2758 and the program would not know to "guess them". So, for example, 2759 a client might put in an if-state-match header with a wildcard 2760 specifying that if any write lock is outstanding then the 2761 operation should fail. However a new read/write lock could be 2762 introduced which the client would not know to put in the header. 2764 5.2.11.3 State-Token Header 2766 The State-Token header is returned in a successful response to 2767 the LOCK method or is used as a request header with the UNLOCK 2768 method. 2770 The State-Token header containing a lock token owned by the 2771 request principal is used by the principal on arbitrary method to 2772 indicate that the principal is aware of the specified lock. If 2773 the State-Token header with the appropriate lock token is not 2774 included the request MUST be rejected, even though the requesting 2775 principal has authorization to make modifications specified by 2776 the lock type. This injunction does not apply to methods that are 2777 not affected by the principal�s lock. 2779 For example, Program A, used by user A, takes out a write lock on 2780 a resource. Program A then makes a number of PUT requests on the 2781 locked resource, all the requests contain a State-Token header 2782 which includes the write lock state token. Program B, also run by 2783 User A, then proceeds to perform a PUT to the locked resource. 2784 However program B was not aware of the existence of the lock and 2785 so does not include the appropriate state-token header. The 2786 method is rejected even though principal A is authorized to 2787 perform the PUT. Program B can, if it so chooses, now perform 2788 lock discovery and obtain the lock token. Note that program A and 2789 B can perform GETs without using the state-token header because 2790 the ability to perform a GET is not affected by a write lock. 2792 Note that having a lock state token provides no special access 2793 rights. Anyone can find out anyone else�s lock state token by 2794 performing lock discovery. Locks are to be enforced based upon 2795 whatever authentication mechanism is used by the server, not 2796 based on the secrecy of the token values. 2798 5.3 Write Lock 2800 A write lock prevents a principal without the lock from 2801 successfully executing a PUT, POST, DELETE, MKCOL, PROPPATCH, 2802 PATCH, ADDREF or DELREF on the locked resource. All other 2803 methods, GET in particular, function independent of the lock. 2805 While those without a write lock may not alter a property on a 2806 resource it is still possible for the values of live properties 2807 to change, even while locked, due to the requirements of their 2808 schemas. Only dead properties and live properties defined to 2809 respect locks are guaranteed to not change while locked. 2811 It is possible to assert a write lock on a null resource in order 2812 to lock the name. Please note, however, that locking a null 2813 resource effectively makes the resource non-null as the resource 2814 now has lock related properties defined on it. 2816 Write locking a container also prevents adding or removing 2817 members of the container. This means that attempts to PUT/POST a 2818 resource into the immediate name space of the write locked 2819 container MUST fail if the principal requesting the action does 2820 not have the write lock on the container. In order to keep the 2821 behavior of locking containers consistent all locks on containers 2822 MUST contain a Depth header equal to infinity, any other value is 2823 illegal. 2825 5.4 Lock Tokens 2827 5.4.1 Problem Description 2829 It is possible that once a lock has been granted it may be 2830 removed without the lock owner�s knowledge. This can cause 2831 serialization problems if the lock owner executes methods 2832 thinking their lock is still in effect. Thus a mechanism is 2833 needed for a principal to predicate the successful execution of a 2834 message upon the continuing existence of a lock. 2836 5.4.2 Proposed Solution 2838 The proposed solution is to provide a lock token in the response 2839 of a lock request. The lock token is a type of state token and 2840 describes a particular lock. The same lock token must never be 2841 repeated on a particular resource. This prevents problems with 2842 long held outstanding lock tokens being confused with newer 2843 tokens. This uniqueness requirement is the same as for e-tags. 2844 This requirement also allows for tokens to be submitted across 2845 resources and servers without fear of confusion. 2847 5.4.3 Lock Token Definition 2849 The lock token is returned in the State-Token header in the 2850 response to a LOCK method. The lock token can also be discovered 2851 through lock discovery on a resource. 2852 Lock-Token-URL = "StateToken:" Type ":" Resources ":" State-Info 2853 Type = "Type" "=" "^DAV:/LOCK/DAVLOCK^" 2854 Resources = "Res" "=" 1*("^" Caret-Encoded-URI "^") 2855 Caret-Encoded-URI = 2856 State-Info = DAVLockScope ":" DAVLockType ":" ServerID ; 2857 DAVLockScope, DAVLockType defined in Lock-Info header 2858 ServerID = "ServerID" "=" *(uchar | reserved) 2860 The ServerID is a field for use by the server. Its most basic 2861 purpose is to put in a unique identifier to guarantee that a 2862 server will never confuse an old lock token with a newer one. 2863 However the server is free to use the field to record whatever 2864 information it deems fit. The field is opaque to clients. 2866 5.5 UNLOCK Method 2868 5.5.1 Problem Definition 2870 The UNLOCK method removes the lock identified by the lock token 2871 in the State-Token header from the Request-URI. 2873 5.5.2 Example 2875 UNLOCK /workspace/webdav/proposal.doc HTTP/1.1 2876 Host: webdav.sb.aol.com 2877 State-Token: StateToken:Type=^DAV:/LOCK/DAVLOCK^:Res=^http://www. 2878 ics.uci.edu/workspace/webdav/proposal.doc^:LockType=Write:LockSco 2879 pe=Exclusive:ServerID=12382349AdfFFF 2881 HTTP/1.1 200 OK 2883 In this example, the lock from example of Section 2.9 is removed 2884 from the resource at 2885 http://webdav.sb.aol.com/workspace/webdav/proposal.doc 2887 5.6 Discovery Mechanisms 2889 5.6.1 Lock Type Discovery 2891 5.6.1.1 Problem Definition 2893 Since server lock support is optional, a client trying to lock a 2894 resource on a server can either try the lock and hope for the 2895 best or can perform some form of discovery to determine what lock 2896 types the server actually supports, then formulate a supported 2897 request. This is known as lock type discovery. Lock type 2898 discovery is not the same as discovering what access control 2899 types are supported, as there may be access control types without 2900 corresponding lock types. 2902 5.6.1.2 SupportedLock Property 2904 Name: http://www.ietf.org/standards/dav/lock/supportedlock 2905 Purpose: To provide a listing of the lock types supported by the 2906 resource. 2907 Schema: http://www.ietf.org/standards/dav/ 2908 Values: An XML document containing zero or more LockEntry XML 2909 elements. 2911 Description: The SupportedLock property of a resource returns a 2912 listing of the combinations of scope and access types which may 2913 be specified in a lock request on the resource. Note that the 2914 actual contents are themselves controlled by access controls so a 2915 server is not required to provide information the client is not 2916 authorized to see. If SupportedLock is available on "*" then it 2917 MUST define the set of locks allowed on all resources on that 2918 server. 2920 5.6.1.3 LOCKENTRY XML Element 2922 Name: http://www.ietf.org/standards/dav/lockentry 2923 Purpose: Defines a DAVLockType/LockScope pair which may be 2924 legally used with a LOCK on the specified resource. 2925 Schema: HYPERLINK http://www.ietf.org/standards/dav/ 2926 Parent: A SupportedLock entry 2927 Values: LockType LockScope 2929 5.6.1.4 LOCKTYPE XML Element 2931 Name: http://www.ietf.org/standards/dav/locktype 2932 Purpose: Lists a DAVLockType 2933 Schema: http://www.ietf.org/standards/dav/ 2934 Parent: LOCKENTRY 2935 Values: DAVLockTypeValue 2937 5.6.1.5 LOCKSCOPE XML Element 2939 Name: http://www.ietf.org/standards/dav/lockscope 2940 Purpose: Lists a DAVLockScope 2941 Schema: http://www.ietf.org/standards/dav/ 2942 Parent: LOCKENTRY 2943 Values: DAVLockScopeValue 2945 5.6.2 Active Lock Discovery 2947 5.6.2.1 Problem Definition 2949 If another principal locks a resource that a principal wishes to 2950 access, it is useful for the second principal to be able to find 2951 out who the first principal is. 2953 5.6.2.2 Solution Requirements 2955 The lock discovery mechanism should provide a list of who has the 2956 resource locked, what locks they have, and what their lock tokens 2957 are. The lock tokens are useful in shared lock situations where 2958 two principals in particular may want to guarantee that they do 2959 not overwrite each other. The lock tokens are also useful for 2960 administrative purposes so that an administrator can remove a 2961 lock by referring to its token. 2963 5.6.2.3 LOCKDISCOVERY Property 2965 Name: http://www.ietf.org/standards/dav/lockdiscovery 2966 Purpose: To discover what locks are active on a resource 2967 Schema: http://www.ietf.org/standards/dav/ 2968 Values= An XML document containing zero or more ActiveLock XML 2969 elements. 2970 Description: The LOCKDISCOVERY property returns a listing of who 2971 has a lock, what type of lock they have, the time out type and 2972 the time remaining on the time out, and the associated lock 2973 token. The server is free to withhold any or all of this 2974 information if the requesting principal does not have sufficient 2975 access rights to see the requested data. 2977 5.6.2.4 ACTIVELOCK XML Element 2979 Name: http://www.ietf.org/standards/dav/activelock 2980 Purpose: A multivalued XML element that describes a particular 2981 active lock on a resource 2982 Schema: http://www.ietf.org/standards/dav/ 2983 Parent: A LOCKDISCOVERY entry 2984 Values= LOCKTYPE LOCKSCOPE OWNER TIMEOUT LOCKTOKEN 2986 5.6.2.5 OWNER XML Element 2988 Name: http://www.ietf.org/standards/dav/lock/owner 2989 Purpose: Returns owner information 2990 Schema: http://www.ietf.org/standards/dav/ 2991 Parent: ACTIVELOCK 2992 Values= XML:REF | {any valid XML string} 2994 5.6.2.6 TIMEOUT XML Element 2996 Name: http://www.ietf.org/standards/dav/timeout 2997 Purpose: Returns information about the timeout associated with 2998 the lock 2999 Schema: http://www.ietf.org/standards/dav/ 3000 Parent: ACTIVELOCK 3001 Values= CLOCKTYPE TIMETYPE TIMEOUTVAL 3003 5.6.2.7 CLOCKTYPE XML Element 3005 Name: http://www.ietf.org/standards/dav/clocktype 3006 Purpose: Returns the clock type used with this lock 3007 Schema: http://www.ietf.org/standards/dav/ 3008 Parent: TIMEOUT 3009 Values= ClockTypeValue 3011 5.6.2.8 TIMETYPE XML Element 3013 Name: http://www.ietf.org/standards/dav/clocktype 3014 Purpose: Returns the time type used with this lock 3015 Schema: http://www.ietf.org/standards/dav/ 3016 Parent: TIMEOUT 3017 Values= TimeTypeValue 3019 5.6.2.9 TIMEOUTVAL XML Element 3021 Name: http://www.ietf.org/standards/dav/timeoutval 3022 Purpose: Returns the amount of time left on the lock 3023 Schema: http://www.ietf.org/standards/dav/ 3024 Parent: TIMEOUT 3025 Values= DAVTimeOutVal 3026 5.6.2.10 LOCKTOKEN XML Element 3027 Name: http://www.ietf.org/standards/dav/statetoken 3028 Purpose: Returns the lock token 3029 Schema: http://www.ietf.org/standards/dav/ 3030 Parent: ACTIVELOCK 3031 Values= XML:REF 3032 Description: The REF contains a Lock-Token-URL. 3034 6 Version Control 3035 [TBD] 3037 7 Internationalization Support 3038 [TBD] 3040 8 Security Considerations 3041 [TBD] 3043 9 Acknowledgements 3045 Terry Allen, Harald Alvestrand, Alan Babich, Dylan Barrell, 3046 Bernard Chester, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., 3047 Keith Dawson, Mark Day, Martin Duerst, David Durand, Lee Farrell, 3048 Chuck Fay, Roy Fielding, Mark Fisher, Alan Freier, George 3049 Florentine, Jim Gettys, Phill Hallam-Baker, Dennis Hamilton, 3050 Steve Henning, Alex Hopmann, Andre van der Hoek, Ben Laurie, Paul 3051 Leach, Ora Lassila, Karen MacArthur, Steven Martin, Larry 3052 Masinter, Michael Mealling, Keith Moore, Henrik Nielsen, Kenji 3053 Ota, Bob Parker, Glenn Peterson, Jon Radoff, Saveen Reddy, Henry 3054 Sanders, Christopher Seiwald, Judith Slein, Mike Spreitzer, Einar 3055 Stefferud, Ralph Swick, Kenji Takahashi, Robert Thau, Sankar 3056 Virdhagriswaran, Fabio Vitali, Gregory Woodhouse, Lauren Wood 3058 10 References 3060 [Berners-Lee, 1997] T. Berners-Lee, "Metadata Architecture." 3061 Unpublished white paper, January 1997. 3062 http://www.w3.org/pub/WWW/DesignIssues/Metadata.html. 3064 [Bray, Sperberg-McQueen, 1997] T. Bray, C. M. Sperberg-McQueen, 3065 "Extensible Markup Language (XML): Part I. Syntax", WD-xml- 3066 lang.html, http://www.w3.org/pub/WWW/TR/WD-xml-lang.html. 3068 [Connolly et al, 1997] D. Connolly, R. Khare, H.F. Nielsen, "PEP 3069 - an Extension Mechanism for HTTP", Internet draft, work-in- 3070 progress. draft-ietf-http-pep-04.txt, 3071 ftp://ds.internic.net/internet-drafts/draft-ietf-http-pep-04.txt. 3073 [Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H. 3074 Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- 3075 HTTP/1.1." RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997. 3077 [Lasher, Cohen, 1995] R. Lasher, D. Cohen, "A Format for 3078 Bibliographic Records," RFC 1807. Stanford, Myricom. June, 1995. 3080 [Maloney, 1996] M. Maloney, "Hypertext Links in HTML." Internet 3081 draft (expired), work-in-progress, January, 1996. 3083 [MARC, 1994] Network Development and MARC Standards, Office, ed. 3084 1994. "USMARC Format for Bibliographic Data", 1994. Washington, 3085 DC: Cataloging Distribution Service, Library of Congress. 3087 [Miller et al., 1996] J. Miller, T. Krauskopf, P. Resnick, W. 3088 Treese, "PICS Label Distribution Label Syntax and Communication 3089 Protocols" Version 1.1, W3C Recommendation REC-PICS-labels- 3090 961031. http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html. 3092 [Slein et al., 1997] J. A. Slein, F. Vitali, E. J. Whitehead, 3093 Jr., D. Durand, "Requirements for Distributed Authoring and 3094 Versioning on the World Wide Web." Internet-draft, work-in- 3095 progress, draft-ietf-webdav-requirements-02.txt, 3096 ftp://ds.internic.net/internet-drafts/draft-ietf-webdav- 3097 requirements-02.txt. 3099 [WebDAV, 1997] WEBDAV Design Team. "A Proposal for Web Metadata 3100 Operations." Unpublished manuscript. 3101 http://www.ics.uci.edu/~ejw/authoring/proposals/metadata.html 3103 [Weibel et al., 1995] S. Weibel, J. Godby, E. Miller, R. Daniel, 3104 "OCLC/NCSA Metadata Workshop Report." 3105 http://purl.oclc.org/metadata/dublin_core_report. 3107 [Yergeau, 1997] F. Yergeau, "UTF-8, a transformation format of 3108 Unicode and ISO 10646", Internet Draft, work-in-progress, draft- 3109 yergeau-utf8-rev-00.txt, http://www.internic.net/internet- 3110 drafts/draft-yergeau-utf8-rev-00.txt. 3112 11 Authors' Addresses 3114 Y. Y. Goland 3115 Microsoft Corporation 3116 One Microsoft Way 3117 Redmond, WA 98052-6399 3118 Email yarong@microsoft.com 3120 E. J. Whitehead, Jr. 3121 Dept. Of Information and Computer Science 3122 University of California, Irvine 3123 Irvine, CA 92697-3425 3124 Email: ejw@ics.uci.edu 3126 A. Faizi 3127 Netscape 3128 685 East Middlefield Road 3129 Mountain View, CA 94043 3130 Email: asad@netscape.com 3132 S. R Carter 3133 Novell 3134 1555 N. Technology Way 3135 M/S ORM F111 3136 Orem, UT 84097-2399 3137 Email srcarter@novell.com 3139 D. Jensen 3140 Novell 3141 1555 N. Technology Way 3142 M/S ORM F111 3143 Orem, UT 84097-2399 3144 Email dcjensen@novell.com