idnits 2.17.1 draft-ietf-webdav-protocol-02.txt: -(307): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1222): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1243): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1518): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1912): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2067): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2465): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2473): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2474): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2515): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2757): 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-25) 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 23 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 604 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], [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 290: '... of the property MUST be either blank,...' RFC 2119 keyword, line 329: '...t property system MUST be such that it...' RFC 2119 keyword, line 332: '... MUST be able to speak to a h...' RFC 2119 keyword, line 333: '... client MUST be able to speak...' RFC 2119 keyword, line 334: '... way MUST be that the request...' (132 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1096 has weird spacing: '...tion of such ...' == Line 1897 has weird spacing: '...rective opera...' == Line 2622 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: When DELETE is applied to a collection resource, all internal members MUST be recursively deleted. The dav:link/propagate external members MUST be deleted and their links must be removed. dav:link/nopropagate external members MUST have only their link removed; the resources MUST not be deleted. == 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 3, 1997) is 9731 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 3025 looks like a reference -- Missing reference section? 'Sperberg-McQueen' on line 3025 looks like a reference -- Missing reference section? '1997' on line 3068 looks like a reference -- Missing reference section? 'Berners-Lee' on line 3021 looks like a reference -- Missing reference section? 'Lagoze' on line 260 looks like a reference -- Missing reference section? '1996' on line 3041 looks like a reference -- Missing reference section? 'MARC' on line 3044 looks like a reference -- Missing reference section? '1994' on line 3044 looks like a reference -- Missing reference section? 'Lasher' on line 3038 looks like a reference -- Missing reference section? 'Cohen' on line 3038 looks like a reference -- Missing reference section? '1995' on line 3038 looks like a reference -- Missing reference section? 'DTD' on line 414 looks like a reference -- Missing reference section? 'DefinedProps' on line 381 looks like a reference -- Missing reference section? 'Live' on line 414 looks like a reference -- Missing reference section? 'ResponseDescription' on line 652 looks like a reference -- Missing reference section? 'VTML' on line 1889 looks like a reference -- Missing reference section? 'TBD' on line 3002 looks like a reference -- Missing reference section? 'Maloney' on line 3041 looks like a reference -- Missing reference section? 'WebDAV' on line 3060 looks like a reference -- Missing reference section? 'Yergeau' on line 3068 looks like a reference Summary: 14 errors (**), 0 flaws (~~), 10 warnings (==), 22 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 March 8, 1998 September 3, 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.2Creation 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 INDEX Method 103 3.3.1 Problem Description 104 3.3.2 Solution Requirements 105 3.3.3 The Request 106 3.3.4 The Response 107 3.3.5 Response Message Body 108 3.3.6 Example 109 3.4 Behavior of RFC 2068 Methods on Collections 110 3.4.1 GET, HEAD for Collections 111 3.4.2 POST for Collections 112 3.4.3 PUT for Collections 113 3.4.4 DELETE for Collections 114 3.5 COPY Method 115 3.5.1 Problem Description 116 3.5.2 Solution Requirements 117 3.5.3 The Request 118 3.5.4 The Response 119 3.5.5 Examples 120 3.6 MOVE Method 121 3.6.1 Problem Description 122 3.6.2 Solution Requirements 123 3.6.3 The Request 124 3.6.4 The Response 125 3.6.5 Examples 126 3.7 ADDREF Method 127 3.7.1 Problem Definition 128 3.7.2 Solution Requirements 129 3.7.3 The Request 130 3.8 DELREF Method 131 3.8.1 Problem Definition 132 3.8.2 Solution Requirements 133 3.8.3 The Request 134 3.9 PATCH Method 135 3.9.1 Problem Definition 136 3.9.2 Solution Requirements 137 3.9.3 The Request 138 3.9.4 application/XML elements for PATCH 139 3.9.5 The Response 140 3.9.6 Examples 141 3.10 Headers 142 3.10.1 Depth 143 3.10.2 Destination 144 3.10.3 Enforce-Live-Properties 145 3.10.4 Duplicate-Properties 146 3.10.5 Overwrite 147 3.10.6 Destroy Header 148 3.10.7 Mandatory header 149 3.10.8 Collection-Member Header 150 3.11 Links 151 3.11.1 Source Link Property Type 152 4 State Tokens 153 4.1 Overview 154 4.1.1 Problem Description 155 4.1.2 Solution Requirements 156 4.2 State Token Syntax 157 4.3 State Token Conditional Headers 158 4.3.1 If-State-Match 159 4.3.2 If-None-State-Match 160 4.4 State Token Header 161 4.5 E-Tags 162 5 Locking 163 5.1 Problem Description - Overview 164 5.1.1 Exclusive Vs. Shared Locks 165 5.1.2 Required Support 166 5.2 LOCK Method 167 5.2.1 Operation 168 5.2.2Effect of Locks on Properties and Containers 169 5.2.3 Locking Replicated Resources 170 5.2.4 Interaction with other Methods 171 5.2.5 Lock Compatibility Table 172 5.2.6 Status Codes 173 5.2.7 Example 174 5.2.8 Lock-Info Request Header 175 5.2.9 Owner Request Header 176 5.2.10 Time-Out Header 177 5.2.11 State-Token Header 178 5.3 Write Lock 179 5.4 Lock Tokens 180 5.4.1 Problem Description 181 5.4.2 Proposed Solution 182 5.4.3 Lock Token Definition 183 5.5 UNLOCK Method 184 5.5.1 Problem Definition 185 5.5.2 Example 186 5.6 Discovery Mechanisms 187 5.6.1 Lock Type Discovery 188 5.6.2 Active Lock Discovery 189 6 Version Control 190 7 Internationalization Support 191 8 Security Considerations 192 9 Acknowledgements 193 10 References 194 11 Authors' Addresses 196 1 Terminology 198 Collection - A resource that contains member resources. 200 Member Resource - a resource referred to by a collection. There 201 are two types of member resources: external and internal. 203 Internal Member Resource - the name given to a member resource of 204 a collection whose URI is relative to the URI of the collection. 206 External Member Resource - a member resource with an absolute URI 207 that is not relative to its parent�s URI. 209 Properties - A set of name/value pairs that contain descriptive 210 information about a resource. 212 Live Properties - Properties whose semantics and syntax are 213 enforced by the server. For example, a live "read-only" property 214 that is enforced by the server would disallow PUTs to the 215 associated resource. 217 Dead properties - Properties whose semantics and syntax are not 218 enforced by the server. A dead "read-only" property would not be 219 enforced by the server and thus would not be used by the server 220 as a reason to disallow a PUT on the associated resource. 222 2 Data Model and Methods for DAV Properties 224 2.1 Introduction 226 2.1.1 The DAV Property 228 Properties are pieces of data that describe the state of a 229 resource. Properties are data about data. The term property is 230 used within this specification to disambiguate the concept from 231 the overloaded terms "metadata" and "attribute". 232 Properties are used within distributed authoring environments to 233 provide for efficient discovery and management of resources. For 234 example, a 'subject' property might allow for the indexing of all 235 resources by their subject, and an 'author' property might allow 236 for the discovery of what authors have written which documents. 238 2.1.2 Existing Metadata Proposals 240 Properties have a long played an essential role in the 241 maintenance of large document repositories, and many current 242 proposals contain some notion of a property. These include PICS 243 [Miller et al., 1996], PICS-NG, the Rel/Rev draft [Maloney, 244 1996], Web Collections, XML [Bray, Sperberg-McQueen, 1997], 245 several proposals on representing relationships within HTML, 246 digital signature manifests (DCMF), and a position paper on Web 247 metadata architecture [Berners-Lee, 1997]. 249 Some proposals come from a digital library perspective. These 250 include the Dublin Core [Weibel et al., 1995] metadata set and 251 the Warwick Framework [Lagoze, 1996], a container architecture 252 for different metadata schemas. The literature includes many 253 examples of metadata, including MARC [MARC, 1994], a 254 bibliographic metadata format, RFC 1807 [Lasher, Cohen, 1995], a 255 technical report bibliographic format employed by the Dienst 256 system, and the proceedings from the first IEEE Metadata 257 conference describe many community-specific metadata sets. 259 Participants of the 1996 Metadata II Workshop in Warwick, UK 260 [Lagoze, 1996], noted that, "new metadata sets will develop as 261 the networked infrastructure matures" and "different communities 262 will propose, design, and be responsible for different types of 263 metadata." These observations can be corroborated by noting that 264 many community-specific sets of metadata already exist, and there 265 is significant motivation for the development of new forms of 266 metadata as many communities increasingly make their data 267 available in digital form, requiring a metadata format to assist 268 data location and cataloging. 270 2.1.3 Properties and HTTP Headers 272 Properties already exist, in a limited sense, within HTTP through 273 the use of message headers. However, in distributed authoring 274 environments a relatively large number of properties are needed 275 to describe the state of a resource, and setting/returning them 276 all through HTTP headers is inefficient. Thus a mechanism is 277 needed which allows a principal to identify a set of properties 278 in which the principal is interested and to then set or retrieve 279 just those properties. 281 2.2 A Property Model for HTTP Resources 283 2.2.1 Overview 285 The DAV property model is based on name/value doubles. The name 286 of a property identifies the property's syntax and semantics, and 287 provides an address with which to refer to a property. The name 288 and value of a property is expressed as a well-formed XML 289 element, where the name of the property is the name of the XML 290 element, and the value of the property MUST be either blank, or a 291 well-formed XML element value. 293 2.2.2 Property Namespace 295 2.2.2.1 Problem Definition 297 The requirement is to be able to associate a value with a 298 property name on a resource and to be able to directly address 299 that value. 301 2.2.2.2 Solution Requirement 303 Ideally a property namespace should work well with extant 304 property implementations as well as database systems. The DAV 305 property namespace has been specified with the following two 306 facts in mind: 307 � Namespaces associated with flat file systems are ubiquitous. 308 � The majority of databases use a fixed schema mechanism. 309 The last point makes efficient implementation of hierarchical 310 properties difficult. Specifically, each property has a random 311 set of children; the best a relational database can do is provide 312 a table with name and value, where the value is a series of 313 indexes into other tables and each index represents a specific 314 value. However most RDBS do not provide for table pointers, only 315 index values. Such a system would have to be jury-rigged to 316 handle table pointers. In addition, indexing systems are 317 optimized for a small set of relatively large tables; 318 hierarchical property systems tend toward many properties, each 319 with different numbers and types of children, thus potentially 320 requiring a table for each child. 322 It would seem best to implement a flat property namespace, 323 inducing a natural isomorphism between DAV and most native file 324 systems. Adopting such a model will not restrict RDBS from taking 325 full advantage of their search facilities. 327 However, it seems that future trends might be toward hierarchical 328 properties. Therefore, DAV requirements [Slein et al.] stipulate 329 that the design of the flat property system MUST be such that it 330 will be possible to add true hierarchical properties later 331 without breaking downlevel clients. Specifically, a flat client 332 MUST be able to speak to a hierarchical server and a hierarchical 333 client MUST be able to speak to a flat server. Worst case either 334 way MUST be that the request fails. 336 2.2.2.3 Property Names 338 A property name identifies both the syntax and semantics of the 339 property's value. It is critical that property names do not 340 collide, e.g., two principals defining the same property name 341 with two different meanings. 343 The URI framework provides a mechanism to prevent namespace 344 collision and for varying degrees of administrative control. 345 Rather than reinvent these desirable features, DAV properties 346 make use of them by requiring that all DAV property names MUST be 347 URIs. Since a property is also an XML element, the name of the 348 XML element is a URI. 350 The property namespace is flat, that is, it is not possible to 351 string together a series of property names in order to refer to a 352 hierarchy of properties. Thus it is possible to refer to a 353 property B but not a property A/B, where is also a property 354 defined on the resource. 356 Finally, it is not possible to define the same property twice as 357 this would cause a collision in the resource's property 358 namespace. 360 2.3 Schemas 362 A schema is a group of property names and XML elements. 364 Schema discovery is used to determine if a system supports a 365 group of properties or XML elements. A property does not 366 necessarily contain sufficient information to identify any 367 schema(s) to which it may belong. 369 As with property names, schemas MUST use URIs as their names. 371 A resource declares its support for a schema by defining a 372 property whose name is the same as the schema's. The property 373 SHOULD contain the PropSchema XML element. 375 2.3.1 PropSchema XML Element 377 Name: http://www.ietf.org/standards/dav/PropSchema 378 Purpose: To provide information about properties 379 Schema: http://www.ietf.org/standards/dav/ 380 Parent: Any 381 Values= [DTD] [DefinedProps] 382 Description:This property contains the definition of the schema. 383 This definition consists of two parts. A DTD element that 384 contains a DTD that declares all XML elements and DefinedProps 385 that defines any properties associated with the schema. As with 386 all XML it is possible to add extra XML elements. Therefore 387 schemas may define extra XML elements which are to be included 388 with their values. 390 2.3.2 DTD XML Element 392 Name: http://www.ietf.org/standards/dav/DTD 393 Purpose: To contain the DTD for XML elements associated with the 394 schema. 395 Schema: http://www.ietf.org/standards/dav/ 396 Parent: Any 397 Values: XML Declaration statements 399 2.3.3 DefinedProps XML Element 401 Name: http://www.ietf.org/standards/dav/DefinedProps 402 Purpose: To contain a list of properties defined by the schema. 403 Schema: http://www.ietf.org/standards/dav/ 404 Parent: Any 405 Values= 1*PropEntries 407 2.3.4 PropEntries XML Element 409 Name: http://www.ietf.org/standards/dav/PropEntries 410 Purpose: To contain the name of a defined property, the DTD of 411 its value, and its live/dead status. 412 Schema: http://www.ietf.org/standards/dav/ 413 Parent: DefinedProps 414 Values= Prop [DTD] [Live] 415 Description:Prop contains the name of the property. The DTD 416 contains the DTD of the property's value. Live, if defined, 417 indicates that the property has semantics and syntax that are 418 enforced by the server. 420 2.3.5 Live XML Element 422 Name: http://www.ietf.org/standards/dav/Live 423 Purpose: If present this indicates the server MUST enforce the 424 syntax and semantics of the property. 425 Schema: http://www.ietf.org/standards/dav/ 426 Parent: PropEntries 428 2.4 DAV Schema 430 The DAV Schema is specified as 431 http://www.ietf.org/standards/dav/. This schema is used to 432 indicate support for 433 � properties that may be defined on a resource and 434 � XML elements that may be returned in responses. 436 2.4.1 DAV Property 438 Name: http://www.ietf.org/standards/dav 439 Purpose: Defines support for the DAV schema and protocol. 440 Schema: http://www.ietf.org/standards/dav/ 441 Values= PropSchema Level 442 Description:This property indicates that the resource supports 443 the DAV schema and protocol to the level indicated. THE VALUE IN 444 PROPSCHEMA IS TBD, WE NEED TO PROVIDE IT IN AN APPENDIX. 446 2.4.2 Level XML Element 448 Name: http://www.ietf.org/standards/dav/level 449 Purpose: To indicate the level of DAV compliance the resource 450 meets. 451 Schema: http://www.ietf.org/standards/dav/ 452 Parent: DAV 453 Values= "1" | "2" | "3" 454 Description:A value of 1 for level indicates that the resource 455 supports the property and namespace sections of the DAV 456 specification. Level 2 indicates that the resource supports level 457 1 and the lock section of the specification, with a minimum 458 locking capability of the write lock. Level 3 indicates support 459 for levels 1 and 2 as well as support for the versioning section 460 of the DAV specification. 462 2.4.3 Prop XML element 464 Name: http://www.ietf.org/standards/dav/prop 465 Purpose: Contains properties related to a resource. 466 Schema: http://www.ietf.org/standards/dav/ 467 Parent: Any 468 Values: XML Elements 469 Description:The Prop XML element is a generic container for 470 properties defined on resources. All elements inside Prop MUST 471 define properties related to the resource. No other elements may 472 be used inside of a Prop element. 474 2.4.4 PropLoc XML Attribute 476 Name: http://www.ietf.org/standards/dav/PropLoc 477 Purpose: To specify the location of the associated property. 478 Schema: http://www.ietf.org/standards/dav/ 479 Values= URL 480 Description:This attribute is used with elements inside of Props 481 contained in responses to specify the URL of the property on the 482 associated resource. The PropLoc attribute MUST NOT be used in 483 requests. 485 2.4.5 Example 487 489 490 491 493 Larry Masinter 494 495 497 The previous specifies that the property author exists on some 498 unspecified resource and that the property can be directly 499 referenced at http://www.foo.com/resource/props/Author. The 500 resource upon which the property is defined must be determined 501 from context. 503 2.5 Property Identifiers 505 2.5.1 Problem Definition 507 DAV properties are resources and thus may have a URI where the 508 value of an instance of the property may be retrieved. This URI 509 is separate from the URI name of the property, which identifies 510 the syntax and semantics of the property, but which does not give 511 information on how to access the value of an instance of the 512 property. 514 A server is free to assign whatever URI it chooses to identify an 515 instance of a property defined on a resource. In fact, a server 516 is free not to reveal the URI of an instance of a particular 517 resource and instead require that the client access the property 518 through PROPFIND and PROPPATCH. However, many servers will want 519 to allow clients to directly manipulate properties. On these 520 servers, a client can discover the URI of an instance of a 521 property by performing a PROPFIND and examining the PropLoc 522 attribute, if returned, of each property. 524 2.6 Link XML Element 526 2.6.1 Problem Description 528 A mechanism is needed to associate resources with other 529 resources. These associations, known as links, consist of three 530 values, a type describing the nature of the association, the 531 source of the link, and the destination of the link. In the case 532 of annotation, neither the source nor the destination of a link 533 need be the resource upon which the link is recorded. 535 2.6.2 Solution Requirements 537 The association mechanism MUST make use of the DAV property 538 mechanism in order to make the existence of the associations 539 searchable. 541 2.6.3 Link XML Element 543 Name: http://www.ietf.org/standards/dav/link 544 Purpose: To identify a property as a link and to contain the 545 source and destination of that link. 546 Schema: http://www.ietf.org/standards/dav/ 547 Values= 1*Src 1*Dst 548 Description:Link is used to provide the sources and destinations 549 of a link. The type of the property containing the Link XML 550 element provides the type of the link. Link is a multi-valued 551 element, so multiple Links may be used together to indicate 552 multiple links with the same type. 554 2.6.4 Src XML Element 556 Name: http://www.ietf.org/standards/dav/src 557 Purpose: To indicate the source of a link. 558 Schema: http://www.ietf.org/standards/dav/ 559 Parent: http://www.ietf.org/standards/dav/link 560 Values= URI 562 2.6.5 Dst XML Element 564 Name: http://www.ietf.org/standards/dav/Dst 565 Purpose: To indicate the destination of a link 566 Schema: http://www.ietf.org/standards/dav/ 567 Parent: http://www.ietf.org/standards/dav/link 568 Values= URI 570 2.6.6 Example 572 574 576 577 578 579 Source 580 http://foo.bar/program 581 http://foo.bar/src/main.c 582 583 584 Library 585 http://foo.bar/program 586 http://foo.bar/src/main.lib 587 588 589 Makefile 590 http://foo.bar/program 591 http://foo.bar/src/makefile 592 593 594 596 In this example the resource http://foo.bar/program has a source 597 property defined which contains three links. Each link contains 598 three elements, two of which, src and dst, are part of the DAV 599 schema defined in this document, and one which is defined by the 600 schema http://www.foocorp.com/project/ (Source, Library, and 601 Makefile). A client which only implements the elements in the DAV 602 spec will not understand the foocorp elements and will ignore 603 them, thus seeing the expected source and destination links. An 604 enhanced client may know about the foocorp elements and be able 605 to present the user with additional information about the links. 607 2.7 Multi-Status Response 609 2.7.1 Problem Definition 611 Some methods effect more than one resource. The effect of the 612 method on each of the scoped resources may be different, as such 613 a return format that can specify the effect of the method on each 614 resource is needed. 616 2.7.2 Solution Requirements 618 The solution must: 619 - communicate the status code and reason 620 - give the URI of the resource on which the method was invoked 621 - be consistent with other return body formats 622 - 624 2.7.3 Multi-Status Response 626 The default multi-status response body is an text/xml HTTP entity 627 that contains a single XML element called multiresponse, which 628 contains a set of XML elements called response, one for each 200, 629 300, 400, and 500 series status code generated during the method 630 invocation. 100 series status codes MUST NOT be recorded in a 631 response XML element. 633 2.7.3.1 MultiResponse 635 Name: http://www.ietf.org/standards/dav/multiresponse 636 Purpose: Contains multiple response messages. 637 Schema: http://www.ietf.org/standards/dav/ 638 Parent: Any 639 Value: 1*Response [ResponseDescription] 640 Description:The ResponseDescription at the top level is used to 641 provide a general message describing the over arching nature of 642 the response. If this value is available an application MAY use 643 it instead of presenting the individual response descriptions 644 contain within the responses. 646 2.7.3.2 Response 648 Name: http://www.ietf.org/standards/dav/response 649 Purpose: Holds a single response 650 Schema: http://www.ietf.org/standards/dav/ 651 Parent: Any 652 Value: (Prop | HREF) Status [ResponseDescription] 653 Description: Prop MUST contain one or more empty XML elements 654 representing the name of properties. Multiple properties may be 655 included if the same response applies to them all. If HREF is 656 used then the response refers to a problem with the referenced 657 resource, not a property. 659 2.7.3.3 Status 661 Name: http://www.ietf.org/standards/dav/status 662 Purpose: Holds a single HTTP status-line 663 Schema: http://www.ietf.org/standards/dav/ 664 Parent: Response 665 Value: status-line ;status-line defined in [Fielding et al., 666 1997] 668 2.7.3.4 ResponseDescription 670 Name: 671 http://www.ietf.org/standards/dav/ResponseDescription 672 Purpose: Contains a message that can be displayed to the user 673 explaining the nature of the response. 674 Schema: http://www.ietf.org/standards/dav/ 675 Parent: Multiresponse and/or Response 676 Value: Any 677 Description: This XML element provides information suitable to 678 be presented to a user. 680 2.8 Properties and Methods 682 2.8.1 DELETE 684 As properties are resources, the deletion of a property causes 685 the same result as the deletion of any resource. It is worth 686 pointing out that the deletion of a property effects both direct 687 manipulation, that is by the property's URL, as well as indirect 688 discovery and manipulation, that is PROPPATCH and PROPFIND. 690 2.8.2 GET 692 A GET with a Request-URI that identifies a property returns the 693 name and value of that property. Accept types may be used to 694 specify the format of the return value, but all DAV compliant 695 servers MUST at minimum support a return type of text/xml. If 696 text/xml is used as the response format then it MUST return the 697 name and value of the property using the Prop XML element. 699 2.8.2.1 Example 701 The following example assumes that the property's URL, originally 702 generated by the server, was discovered by examining the proploc 703 XML attribute returned on a result from a FINDPROP. 705 GET /bar.html;prop=z39.50_authors HTTP/1.1 706 Host: foo.com 708 HTTP/1.1 200 OK 709 Content-Type: text/xml 710 Content-Length: xxxx 711 E-tag: "1234" 712 Last-Modified: xxxx 714 716 718 719 720 Jane Doe 721 Joe Doe 722 Lots o'Doe 723 724 726 2.8.3 PROPPATCH 728 The PROPPATCH method processes instructions specified in the 729 request body to create and/or remove properties defined on the 730 resource identified by Request-URI. 732 All DAV compliant servers MUST process instructions which are 733 specified using the PropertyUpdate, Create, and Remove XML 734 elements of the DAV schema. The request message body MUST 735 contain at least one PropertyUpdate XML element. Instruction 736 processing MUST occur in the order instructions are received 737 (i.e., from top to bottom), and MUST be performed atomically. 739 2.8.3.1 PropertyUpdate XML element 741 Name: http://www.ietf.org/standards/dav/PropertyUpdate 742 Purpose: To contain a request to alter the properties on a 743 resource. 744 Schema: http://www.ietf.org/standards/dav/ 745 Parent: Any 746 Values= *(Create | Remove) 747 Description:This XML element is a container for the information 748 required to modify the properties on the resource. This XML 749 element is multi-valued. 751 2.8.3.2 Create XML element 753 Name: http://www.ietf.org/standards/dav/create 754 Purpose: To create the DAV properties specified inside the 755 Create XML element. 756 Schema: http://www.ietf.org/standards/dav/ 757 Parent: http://www.ietf.org/standards/dav/PropertyUpdate 758 Values= Prop 759 Description:This XML element MUST contain only a Prop XML 760 element. The elements contained by Prop specify the name and 761 value of properties that are created on Request-URI. If a 762 property already exists then its value is replaced. The Prop XML 763 element MUST NOT contain a PropLoc XML attribute. 765 2.8.3.3 Remove XML element 767 Name: http://www.ietf.org/standards/dav/remove 768 Purpose: To remove the DAV properties specified inside the 769 Remove XML element. 770 Schema: http://www.ietf.org/standards/dav/ 771 Parent: http://www.ietf.org/standards/dav/PropertyUpdate 772 Values= Prop 773 Description:Remove specifies that the properties specified in 774 Prop should be removed. Specifying the removal of a property that 775 does not exist is not an error. All the elements in Prop MUST be 776 empty, as only the names of properties to be removed are 777 required. 779 2.8.3.4 Response 781 The response MUST have a response body that contains a 782 multiresponse identifying the results for each property. 784 2.8.3.5 Response Codes 786 200 OK - The command succeeded. As there can be a mixture of 787 Create and Removes in a body, a 201 Create seems inappropriate. 788 403 Forbidden - The client, for reasons the server chooses not to 789 specify, can not alter one of the properties. 790 405 Conflict - The client has provided a value whose semantics 791 are not appropriate for the property. This includes trying to set 792 read only properties. 793 413 Request Entity Too Long - If a particular property is too 794 long to be recorded then a composite XML error will be returned 795 indicating the offending property. 796 417 Insufficient Space on Resource - The resource does not have 797 sufficient space to record the state of the resource after the 798 execution of this method. 799 418 Atomicity Failure - The command was not executed because of 800 an atomicity failure elsewhere the caused the entire command to 801 be aborted. 803 2.8.3.6 Example 805 PROPPATCH /bar.html HTTP/1.1 806 Host: www.foo.com 807 Content-Type: text/xml 808 Content-Length: xxxx 810 812 814 815 816 817 818 Jim Whitehead 819 Roy Fielding 820 821 822 823 824 825 826 828 HTTP/1.1 405 Conflict 829 Content-Type: text/xml 830 Content-Length: xxxxx 832 834 836 837 Copyright Owner can not be deleted or 838 altered. 839 840 841 HTTP/1.1 418 Atomicity Failure 842 843 844 845 HTTP/1.1 405 Conflict 846 847 849 2.8.4 PUT 851 A PUT is specified in order to control what is returned by a GET. 852 However a GET on a property always returns a predefined property 853 containment format. Therefore PUT can not be used if the Request- 854 URI refers to a property. 856 2.8.5 PROPFIND 857 The PROPFIND method retrieves properties defined on Request-URI. 858 The request message body is an XML document that MUST contain 859 only one PropFind XML element, which specifies the type of 860 property find action to be performed. The XML element contained 861 by PropFind specifies the type of action to be performed: 862 retrieve all property names and values (AllProp), retrieve only 863 specified property names and values (Prop), or retrieve only a 864 list of all property names (Propname). When a Prop XML element 865 is present, it specifies a list of the names of properties whose 866 name and value are to be returned. The Prop element, when used 867 within a FINDPROP request body MUST be empty. 869 The response is a text/xml message body that contains a 870 MultiResponse XML element which describes the results of the 871 attempts to retrieve the various properties. If a property was 872 successfully retrieved then its value MUST be returned in the 873 prop XML element. In the case of Allprop and Findprop, if a 874 principal does not have the right to know if a particular 875 property exists, an error MUST NOT be returned. The results of 876 this method SHOULD NOT be cached. 878 2.8.5.1 Propfind XML element 880 Name: http://www.ietf.org/standards/dav/Propfind 881 Purpose: To specify the set of matching properties 882 Schema: http://www.ietf.org/standards/dav/ 883 Parent: Any 884 Values= (Prop | Allprop | Propname) 885 Description: Propfind is a container element for the exact 886 specification of a PROPFIND request. 888 2.8.5.2 Allprop 890 Name: http://www.ietf.org/standards/dav/Allprop 891 Purpose: To specify that all properties are to be returned 892 Schema: http://www.ietf.org/standards/dav/ 893 Parent: Propfind 894 Description: Its presence in a PROPFIND request specifies the 895 name and value of all properties defined on the resource MUST be 896 returned. 898 2.8.5.3 Propname 900 Name: http://www.ietf.org/standards/dav/Propname 901 Purpose: To specify that the names of all properties defined on 902 the resource 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 of all properties defined on the resource MUST be returned. 908 2.8.5.4 PropFindResult XML element 910 Name: http://www.ietf.org/standards/dav/PropFindResult 911 Purpose: To contain the results of a SEARCH request 912 Schema: http://www.ietf.org/standards/dav/ 913 Parent: Any 914 Values: Prop 915 2.8.5.5 Example 1 - Prop 917 PROPFIND /container/ HTTP/1.1 918 Host: www.foo.bar 919 Content-Length: xxxx 920 Content-Type: text/xml 922 924 926 927 928 929 930 931 932 933 935 HTTP/1.1 207 Partial Success 936 Content-Type: text/xml 937 Content-Length: xxxxx 939 941 942 943 There has been an access violation 944 error. 945 946 947 948 Box type A 949 950 951 J.J. Dingleheimerschmidt 952 953 954 HTTP/1.1 200 Success 955 956 957 958 HTTP/1.1 403 Forbidden 959 The user does not have access to 960 the DingALink property. 961 962 964 The result will return all properties on the container. In this 965 case only two properties were found. The principal did not have 966 sufficient access rights to see the third and fourth properties 967 so an error was returned. 969 2.8.5.6 Example 2 - Allprop 971 PROPFIND /container/ HTTP/1.1 972 Host: www.foo.bar 973 Content-Length: xxxx 974 Content-Type: text/xml 976 978 979 980 982 HTTP/1.1 200 Success 983 Content-Type: text/xml 984 Content-Length: xxxxx 986 988 989 990 991 992 Box type A 993 994 995 Hadrian 996 997 998 HTTP/1.1 200 Success 999 1001 This particular client only had the right to see two properties, 1002 BoxType and Author. No error is returned for the remaining 1003 properties, as the client does not even have sufficient rights to 1004 know they exist. If the client did have the right to know they 1005 existed but did not have the right to see their value, a 201 1006 Partial Success with a multiresponse, as used in the previous 1007 example, would have been returned. 1009 2.8.5.7 Example 3 - Propname 1011 PROPFIND /container/ HTTP/1.1 1012 Host: www.foo.bar 1013 Content-Length: xxxx 1014 Content-Type: text/xml 1016 1018 1019 1020 1022 HTTP/1.1 200 Success 1023 Content-Type: text/xml 1024 Content-Length: xxxxx 1026 1028 1030 1031 1032 1033 1034 1035 1036 1037 HTTP/1.1 200 Success 1038 1040 In this case only two of the properties have direct URLs 1041 available, while the other two properties can only be referenced 1042 via PROPFIND and PROPPATCH. 1044 3 A Proposal for Collections of Web Resources and Name Space 1045 Operations 1047 3.1 Observations on the HTTP Object Model 1049 As a prerequisite for specification of collections and name space 1050 operations for the Web, a model for collection resources and for 1051 namespace topology must be given. This section describes a new 1052 type of Web resource, the collection resource, and provides a 1053 model for discussing the relationship between the resources that 1054 are generated as the result of a data-producing process, and the 1055 source resources that describe the process. 1057 3.1.1 Collection Resources 1059 A collection is a Web resource type whose primary state is a set 1060 of URIs and associated values that are recorded as properties on 1061 the resource. The URIs identify resources that are members of 1062 the collection. The values associated with each URI include 1063 information such as the Last Modified Date, Entity Tag, Creation 1064 Date, Content Type, Display Name, and whether the member is a 1065 collection. 1067 A member of a collection is either an internal member resource, 1068 which MUST have a URI that is relative to the base URI of the 1069 collection, or an external member resource, which has a URI which 1070 is not relative to the base URI of the collection. External 1071 member resources are further subdivided into propagate members, 1072 which have recursive method invocations propagated to them, and 1073 no-propagate members, which do not. 1075 A collection resource may be viewed and used as a compound 1076 resource in which the collection is a container for a group of 1077 related resources that, together, form a larger logical unit. 1078 For example, a collection of HTML resources where each resource 1079 is the chapter of a book can be viewed as a compound resource 1080 representing the entire book. 1082 Some methods, when invoked on a collection, affect the entire 1083 collection. For example, it is possible to copy an entire 1084 collection and its contents with just a single copy method 1085 request. The model for performing these operations is a tree 1086 traversal. The method is invoked on the collection, which then 1087 performs the method on itself before propagating the method to 1088 all its internal members and propagate external members. If 1089 these are non-collection resources, the request method is 1090 processed. However, if the request is propagated to another 1091 collection, then the propagation begins again. This sequence of 1092 actions causes the method to be propagated as a tree traversal of 1093 the members of the collections. It is incumbent upon the client 1094 to perform any locking operation on the collection or subordinate 1095 members that it deems necessary in order to maintain state 1096 consistency during the execution of such methods. 1098 3.1.2 Creation and Retrieval of Collection Resources 1100 Since the existing HTTP methods for creating (PUT, POST) and 1101 retrieving (GET) a resource were defined for non-collection 1102 resources, it is not surprising that the semantics of these 1103 methods do not transfer well to collections. For example, the PUT 1104 method is defined to store the request entity under the Request- 1105 URI. While a description format for a collection can readily be 1106 constructed that could be used with PUT, the implications of 1107 sending such a description to the server are undesirable. For 1108 example, if a description of a collection that omitted some 1109 existing resources were PUT to a server, this might be 1110 interpreted as a command to remove those members. This would 1111 extend PUT to perform DELETE functionality, which is undesirable 1112 since it changes the semantics of PUT, and makes it difficult to 1113 control DELETE functionality with an access control scheme based 1114 on methods. 1116 While the POST method is sufficiently open-ended that a "create a 1117 collection" POST command could be constructed, this is 1118 undesirable because it would be difficult to provide separate 1119 access control for collection creation and other uses of POST if 1120 they both use the same method. 1122 The GET method when applied to collections is also problematic. 1123 While it might seem desirable to have GET return a listing of the 1124 members of a collection, this is foiled by the existence of the 1125 "index.html" de-facto standard namespace redirection, in which a 1126 GET request on a collection is automatically redirected to the 1127 index.html resource. 1129 Because of the difficulty of reusing some existing HTTP/1.1 1130 methods for collections, two new resource creation/retrieval 1131 methods are needed. This specification introduces the MKCOL 1132 method for creating collection resources, and the INDEX method 1133 for retrieving the contents of a collection. 1135 The exact definition of the behavior of GET and PUT on 1136 collections is defined later in this draft. 1138 3.1.3 Source Resources and Output Resources 1140 For many resources, the entity returned by GET exactly matches 1141 the persistent state of the resource, for example, a GIF file 1142 stored on a disk. For this simple case, the URL at which a 1143 resource is accessed is identical to the URL at which the source 1144 (the persistent state) of the resource is accessed. This is also 1145 the case for HTML source files that are not processed by the 1146 server prior to transmission. 1148 However, HTML files can sometimes be processed by the server 1149 before being transmitted as a return entity body. Server-side- 1150 include directives within an HTML file instruct a server to 1151 replace the directive with another value, such as the current 1152 date. In this case, what is returned by GET (HTML plus date) 1153 differs from the persistent state of the resource (HTML plus 1154 directive). Typically there is no way to access the HTML file 1155 containing the unprocessed directive. 1157 Sometimes the entity returned by GET is the output of a data- 1158 producing process that is described by one or more source 1159 resources (that may not even have a location in the URL 1160 namespace). A single data-producing process may dynamically 1161 generate the state of a potentially large number of output 1162 resources. An example of this is a CGI script that describes a 1163 "finger" gateway process that maps part of the namespace of a 1164 server into finger requests, such as 1165 http://www.foo.bar.org/finger_gateway/user@host. 1167 In the absence of distributed authoring capability, the fact that 1168 the source resource(s) for server generated output do not have a 1169 mapping to the URI namespace is not a problem, and has desirable 1170 security benefits. However, if remote editing of the source 1171 resource(s) is desired, they should be given a location in the 1172 URI namespace. This source location should not be one of the 1173 locations at which the generated output is retrievable, since in 1174 general it is impossible for the server to differentiate requests 1175 for source resources from requests for process output resources. 1176 There is often a many-to-many relationship between source 1177 resources and output resources. For DAV compliant servers all 1178 output resources which have a single source resource (and that 1179 source resource has a URI), the URI of the source resource SHOULD 1180 be stored in a single link on the output resource with type 1181 http://www.ietf.org/standards/dav/link/Source. Note that by 1182 storing the source URI in links on the output resources, the 1183 burden of discovering the source is placed on the authoring 1184 client. 1186 In the general case, a large number of source resources can 1187 comprise a data-producing process that generates many output 1188 resources, creating a many-to-many relationship between output 1189 resources and source resources. If each output resource had links 1190 back to every source resource in the data-producing process, 1191 there can be a potentially large number of such links. Due to the 1192 potentially large number of links, and the lack of a policy for 1193 ordering access to multiple sources, explicit storage of source 1194 relationships is limited to cases with only a single source 1195 resource. 1197 3.2 MKCOL Method 1199 3.2.1 Problem Description 1201 The client needs a way to create a collection. 1203 3.2.2 Solution Requirements 1205 The solution: 1206 - Must ensure that a collection has been made (i.e. that it 1207 responds to the INDEX method) as opposed to a non-collection 1208 resource. If a collection could not be made, it must indicate a 1209 failure to the principal. 1210 - The server MAY, if necessary, create any intermediate 1211 collections so that the underlying storage medium is self- 1212 consistent. 1213 - 1215 3.2.3 Request 1217 The MKCOL method creates a new collection resource at the 1218 location specified by the Request-URI. If the Request-URI exists 1219 then MKCOL must fail. 1221 During MKCOL processing, a server MAY add the Request-URI to one 1222 or more collections within the server�s controlled namespace. 1224 3.2.3.1 MKCOL Without Request Body 1226 When MKCOL is invoked without a request body then the collection 1227 created has no members. 1229 3.2.3.2 MKCOL With Request Body 1231 A MKCOL request message MAY contain a message body. The behavior 1232 of a MKCOL request when the body is present is limited to 1233 creating collections, members of a collection, bodies of members 1234 and properties on the collections or members. If the server 1235 receives a MKCOL request entity type it does not support or 1236 understand it MUST respond with a 415 (Unsupported Media Type) 1237 status code. 1239 3.2.3.3 Creating Multiple Collections 1241 The server MAY create intermediate collections if they do not 1242 already exist. For example, if the collection http://server/a/ 1243 already exists in the server�s namespace, then while performing a 1244 MKCOL to create http://server/a/b/c/ the server may also create a 1245 collection at http://server/a/b/. 1247 3.2.4 Response 1249 Responses from a MKCOL request are not cacheable, since MKCOL has 1250 non-idempotent semantics. 1251 201 (Created) - The structured resource was created in its 1252 entirety. 1253 403 (Forbidden) - The server does not allow the creation of 1254 collections at the given location in its namespace. 1255 415 (Unsupported Media Type)- The server does not support the 1256 request type of the body. 1257 416 (Unprocessable Entity) - A new status code. The server 1258 understands the content type of the request entity, but was 1259 unable to process the contained instructions. 1261 3.2.5 Example 1263 This example creates a container collection called 1264 /webdisc/xfiles/ on the server www.server.org. 1265 MKCOL /webdisc/xfiles/ HTTP/1.1 1266 Host: www.server.org 1268 HTTP/1.1 201 Created 1270 3.3 INDEX Method 1272 3.3.1 Problem Description 1274 A mechanism is needed to discover if a resource is a collection 1275 and if so, list its members. 1277 3.3.2 Solution Requirements 1279 The solution: 1280 - must allow a client to discover the members of a collection 1281 - must always provide a machine-readable description of the 1282 membership of a collection 1283 - 1285 3.3.3 The Request 1286 The INDEX method returns a machine-readable representation of the 1287 membership of the resource at the Request-URI. For a collection, 1288 INDEX MUST return a machine-readable list of its members. For 1289 other resources, the information returned by INDEX is undefined, 1290 and MAY vary. The request message body of an INDEX request 1291 SHOULD be ignored. 1293 The Depth header can be used to indicate how much of a result can 1294 be generated for the response. The specific values allowed for 1295 the depth header when used with the INDEX method are 1 and 1296 infinity. The 1 value indicates that the internal and external 1297 member resources should be reported in the result, infinity 1298 indicates that all internal and external member resources and all 1299 their descendants should be in the result. If the Depth header is 1300 not given, then 1 is assumed. Servers MUST honor a depth of 1. 1301 Servers MAY honor infinity. If the server does not support the 1302 value of the depth header then a 412 (Precondition failed) MUST 1303 be returned. 1305 3.3.4 The Response 1307 200 (OK) - The server MUST send an application/xml response 1308 entity which describes the collection. 1309 404 (Not Found) - Same behavior as HTTP 1.1. The server never had 1310 the resource, or the server permanently deleted the resource and 1311 has no knowledge that it ever existed. This error code implies 1312 that, essentially, the server has no information about the 1313 Request URI. 1315 3.3.5 Response Message Body 1317 The default INDEX response for a resource is an application/xml 1318 HTTP entity (i.e., an Extensible Markup Language (XML) document) 1319 that contains a single XML element called collectionresource 1320 which describes the collection, and a set of XML elements called 1321 memberesource which describe the members of the collection. 1323 The response from INDEX is cacheable, and SHOULD be accompanied 1324 by an ETag header (see section 13.3.4 of RFC 2068). If GET and 1325 INDEX return different entities for the same resource state, they 1326 MUST return different entity tags. 1328 The server MUST transmit the following XML elements for each 1329 member resource of a collection: Ref, IsCollection, Content-Type, 1330 External. The server MUST transmit the following XML elements if 1331 it can generate any meaningful values for them: Creation-Date, 1332 Last-Modified, DisplayName, Content-Language. The server SHOULD 1333 transmit Etag XML elements for each member (see section 13.3.4 of 1334 RFC 2068). 1336 The value of content-type, last-modified, and etag XML elements 1337 MUST be identical to the value of the response header field of 1338 the same name in the HTTP/1.1 specification. Since the HTTP/1.1 1339 header fields are described in terms of the on-the-wire entity, 1340 the values presented by INDEX are those that would be generated 1341 if the resource was accessed using the GET method without content 1342 negotiation. 1344 3.3.5.1 CollectionResource 1346 Name: http://www.ietf.org/standards/dav/collectionresource 1347 Purpose: Describes a collection 1348 Schema: http://www.ietf.org/standards/dav/ 1349 Parent: 1350 Value: MemberResource 1352 3.3.5.2 MemberResource 1354 Name: http://www.ietf.org/standards/dav/memberresource 1355 Purpose: Describes a member of a collection 1356 Schema: http://www.ietf.org/standards/dav/ 1357 Parent: CollectionResource 1358 Value: Ref, IsCollection, Content-Type, External, Creation- 1359 Date, Last-Modified, ETag, DisplayName (other XML elements MAY 1360 also be present) 1362 3.3.5.3 Ref 1364 See XML definition. 1366 3.3.5.4 IsCollection 1368 Name: http://www.ietf.org/standards/dav/iscollection 1369 Purpose: This is a boolean value which is set to "true" if the 1370 entry is a collection 1371 Schema: http://www.ietf.org/standards/dav/ 1372 Parent: MemberResource 1373 Value: ("true" | "false") 1375 3.3.5.5 Content-Type 1377 Name: http://www.ietf.org/standards/dav/content-type 1378 Purpose: The content-type of the member resource. 1379 Schema: http://www.ietf.org/standards/dav/ 1380 Parent: MemberResource 1381 Value: media-type ; defined in Section 3.7 of [Fielding et 1382 al., 1997] 1383 If no meaningful content-type can be generated, then an empty 1384 value MUST be given. 1386 3.3.5.6 External 1388 Name: http://www.ietf.org/standards/dav/external 1389 Purpose: If present, this element indicates the resource is an 1390 external member of the collection. If the value is "propagate," 1391 it is a propagate member, if the value is "no-propagate," it is a 1392 no-propagate member. 1393 Schema: http://www.ietf.org/standards/dav/ 1394 Parent: MemberResource 1395 Value: ("propagate" | "no-propagate") 1397 3.3.5.7 Creation-Date 1399 Name: http://www.ietf.org/standards/dav/creation-date 1400 Purpose: The date the resource was created. 1401 Schema: http://www.ietf.org/standards/dav/ 1402 Parent: MemberResource 1403 Value: The date MUST be given in RFC 1123 format (rfc-1123 1404 production, defined in section 3.3.1 of [Fielding et al., 1997] 1405 3.3.5.8 Last-Modified 1407 Name: http://www.ietf.org/standards/dav/last-modified 1408 Purpose: The date the resource was last modified. 1409 Schema: http://www.ietf.org/standards/dav/ 1410 Parent: MemberResource 1411 Value: The date MUST be given in RFC 1123 format (rfc-1123 1412 production, defined in section 3.3.1 of [Fielding et al., 1997] 1414 3.3.5.9 ETag 1416 Name: http://www.ietf.org/standards/dav/etag 1417 Purpose: The entity tag of the resource. 1418 Schema: http://www.ietf.org/standards/dav/ 1419 Parent: MemberResource 1420 Value: entity-tag ; defined in Section 3.11 of [Fielding et 1421 al., 1997] 1423 3.3.5.10 DisplayName 1425 Name: http://www.ietf.org/standards/dav/displayname 1426 Purpose: A name for the resource that is suitable for 1427 presentation to a person 1428 Schema: http://www.ietf.org/standards/dav/ 1429 Parent: MemberResource 1430 Value: Any valid XML character data (from XML specification) 1432 3.3.5.11 Content-Language 1434 Name: http://www.ietf.org/standards/dav/content-language 1435 Purpose: Describes the natural language(s) of the intended 1436 audience for the resource. 1437 Schema: http://www.ietf.org.standards/dav/ 1438 Parent: MemberResource 1439 Value: 1#language-tag ;language-tag is defined in section 1440 14.13 of RFC 2068 1442 3.3.6 Example 1444 INDEX /user/yarong/dav_drafts/ HTTP/1.1 1445 Host: www.microsoft.com 1446 Depth: 1 1448 HTTP/1.1 200 OK 1449 Content-Type: application/xml 1450 Content-Length: xxx 1451 Last-Modified: xxx 1452 ETag: "fooyyybar" 1454 1455 http://www.ietf.org/standards/dav/D 1457 1458 1459 namespace.doc 1460 false 1461 application/msword 1462 false 1463 Thu, 20 Mar 1997 23:05:25 GMT 1464 Fri, 22 Aug 1997 18:22:56 GMT 1465 8675309 1466 WebDAV Name Space Operations Draft 1467 en 1468 1469 1470 This example shows the result of the INDEX method applied to the 1471 collection resource 1472 http://www.microsoft.com/er/yarong/dav_drafts/. It returns a 1473 response body in XML format, which gives information about the 1474 container�s sole member, 1475 http://www.microsoft.com/users/yarong/dav_drafts/namespace.doc. 1477 3.4 Behavior of RFC 2068 Methods on Collections 1479 With the introduction of the collection resource type to the HTTP 1480 object model, it is necessary to define the behavior of the 1481 existing methods (defined in RFC 2068) when invoked on a 1482 collection resource to avoid ambiguity. While some methods, such 1483 as OPTIONS and TRACE behave identically when applied to 1484 collections, GET, HEAD, POST, PUT, and DELETE require some 1485 additional explanation. 1487 3.4.1 GET, HEAD for Collections 1489 The semantics of GET are unchanged when applied to a collection, 1490 since GET is defined as, "retrieve whatever information (in the 1491 form of an entity) is identified by the Request-URI" [Fielding et 1492 al., 1997]. GET when applied to a collection MAY return the 1493 contents of an "index.html" resource, a human-readable view of 1494 the contents of the collection, or something else altogether, and 1495 hence it is possible the result of a GET on a collection will 1496 bear no correlation to the state of the collection. 1498 Similarly, since the definition of HEAD is a GET without a 1499 response message body, the semantics of HEAD do not require any 1500 modification when applied to collection resources. 1502 3.4.2 POST for Collections 1504 Since by definition the actual function performed by POST is 1505 determined by the server and often depends on the particular 1506 resource, the behavior of POST when applied to collections cannot 1507 be modified because it is largely undefined. Thus the semantics 1508 of POST do not require any modification when applied to a 1509 collection. 1511 3.4.3 PUT for Collections 1513 In HTTP/1.1, PUT stores the request entity under the Request-URI, 1514 and hence its semantics are limited to non-collection resources. 1515 If a PUT is invoked on a collection resource it MUST fail. 1517 When the PUT operation creates a new non-collection resource, a 1518 server MAY add that resource�s URI to one or more collections 1519 within the server�s controlled namespace. 1521 3.4.4 DELETE for Collections 1523 When DELETE is applied to a collection resource, all internal 1524 members MUST be recursively deleted. The dav:link/propagate 1525 external members MUST be deleted and their links must be removed. 1526 dav:link/nopropagate external members MUST have only their link 1527 removed; the resources MUST not be deleted. 1529 The Depth header does not apply to the DELETE method. It cannot 1530 be used to limit the extent of the operation. If it is present it 1531 MUST be ignored. 1533 When applied to any resource, the DELETE method deletes all 1534 properties on the Request-URI. 1536 During DELETE processing, a server MAY remove the URI of the 1537 deleted resource(s) from collections within its controlled 1538 namespace. 1540 3.4.4.1 New Response Codes for DELETE 1542 207 (Partial Success) Only some of the member resources were 1543 deleted. The response entity will describe any errors. 1545 500 (Server Error) The resource was in such a state that it could 1546 not be deleted. The response entity will describe reason for the 1547 error. 1549 3.5 COPY Method 1551 3.5.1 Problem Description 1553 Currently, in order to create a copy of a resource, the client 1554 must GET an entity and then PUT that entity to the desired 1555 destination. This requires (1) an entity to be transmitted to and 1556 from the server and (2) that the resource be expressible as an 1557 entity with complete fidelity. This is problematic because of 1558 the network traffic involved in making a copy, and because there 1559 is often no way to fully express a resource as an entity without 1560 a loss of fidelity. 1562 3.5.2 Solution Requirements 1564 The solution: 1565 - MUST allow a principal to create a copy of a resource 1566 without having to transmit the resource to and from the server. 1568 3.5.3 The Request 1570 The COPY method creates a duplicate of the source resource, given 1571 by the Request-URI, in the destination resource, given by the 1572 Destination header. The Destination header MUST be present. The 1573 exact behavior of the COPY method depends on the type of the 1574 source resource. 1576 3.5.3.1 COPY for HTTP/1.1 resources 1578 When the source resource is not a collection, and is not a 1579 property, the body of the destination resource MUST be octet-for- 1580 octet identical to the body of the source resource. Alterations 1581 to the destination resource do not modify the source resource. 1582 Alterations to the source resource do not modify the destination 1583 resource. Thus, all copies are performed "by-value". 1585 If the Duplicate-Properties header is "false," then properties 1586 SHOULD NOT be copied to the destination resource. If the 1587 Duplicate-Properties header is "false" and the Enforce-Live- 1588 Properties header is also present, the request MUST fail with a 1589 412 (Precondition Failed) status code. [Ed. Note: what if 1590 resource to be copied has no properties, and no properties are 1591 explicitly named in the header?] 1593 All properties on a source resource SHOULD be duplicated on the 1594 destination resource following the definition for copying 1595 properties. 1597 3.5.3.2 COPY for Properties 1599 Live properties SHOULD be duplicated as identically behaving live 1600 properties at the destination resource. Since they are live 1601 properties, the server determines the syntax and semantics (hence 1602 value) of these properties. Properties named by the Enforce- 1603 Live- 1604 Properties header MUST be live on the destination resource, or 1605 the method MUST fail. If a property is not named by Enforce- 1606 Live- 1607 Properties and cannot be copied live, then its value MUST be 1608 duplicated in an identically named, dead resource on the 1609 destination resource. 1611 For every dead property defined on the source resource, there 1612 SHOULD be an octet-for-octet identical dead property on the 1613 destination resource. 1615 3.5.3.3 COPY for Collections 1617 The Depth and Overwrite headers govern the behavior of COPY for 1618 collections. 1620 When performing a recursive copy, all HTTP/1.1 request headers 1621 are duplicated on the propagated method request except for the 1622 precondition headers If-Modified-Since, If-Match, If-None-Match, 1623 If-Range, If-Unmodified-Since, which should only be applied to 1624 the Request-URI in order to determine if the operation should be 1625 performed. The Destination header MUST be rewritten to preserve 1626 the membership of the destination collection, i.e., by appending 1627 the relative URI of the member to the URI of the destination 1628 collection. 1630 A Depth of "0" indicates the collection MUST duplicate all of its 1631 external members in a new collection at the Destination. Since 1632 the COPY method is not propagated to its members, no internal 1633 member resource is duplicated. 1635 A Depth of "1" indicates the collection MUST propagate the COPY 1636 to all internal, non-collection members. If the Overwrite header 1637 is "true" the COPY method duplicates all of its external members 1638 in a new collection at the Destination. If the Overwrite header 1639 is "false" and the destination resource is a collection, the COPY 1640 method does not duplicate its external members, but is propagated 1641 to all internal, non-collection members. 1643 A Depth of "infinity" indicates the collection MUST propagate the 1644 COPY method to all internal members. If the Overwrite header is 1645 "true," the COPY method MUST duplicate all of its external 1646 members in a new collection at the Destination. If the Overwrite 1647 header is "false" and the destination resource is a collection, 1648 then the COPY method does not duplicate its external members, but 1649 is propagated to all internal members. 1651 3.5.3.4 Type Interactions 1653 If the destination resource identifies a property and the source 1654 resource is not a property, then the copy SHOULD fail. 1656 If the destination resource identifies a collection and the 1657 Overwrite header is "true," prior to performing the copy, the 1658 server MUST perform a DELETE operation on the collection. 1660 3.5.4 The Response 1662 200 (OK) The source resource was successfully copied to a pre- 1663 existing destination resource. 1665 201 (Created) The source resource was successfully copied. The 1666 copy operation resulted in the creation of a new resource. 1668 207 (Partial Success) Only some of the member resources were 1669 copied. The return entity body describes the status code for each 1670 resource. 1672 412 (Precondition Failed) This status code MUST be returned if 1673 the server was unable to maintain the liveness of the properties 1674 listed in the Enforce-Live-Properties header, or if the Overwrite 1675 header is false, and the state of the destination resource is 1676 non- 1677 null. 1679 500 (Server Error) The resource was in such a state that it could 1680 not be copied. This may occur if the Destination header indicated 1681 an external (from the point of view of the server) resource and 1682 the server has no capability to copy to an external resource. 1684 502 (Bad Gateway) - This may occur when copying to external 1685 resources and the destination server refused to accept the 1686 resource. 1688 3.5.5 Examples 1690 3.5.5.1 Overwrite Example 1692 This example shows resource 1693 http://www.ics.uci.edu/~fielding/index.html being copied to the 1694 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1695 contents of the destination resource were overwritten, if non- 1696 null. 1698 COPY /~fielding/index.html HTTP/1.1 1699 Host: www.ics.uci.edu 1700 Destination: 1701 http://www.ics.uci.edu/users/f/fielding/index.html 1702 Overwrite: "true" 1704 HTTP/1.1 200 OK 1705 3.5.5.2 No Overwrite Example 1707 The following example shows the same copy operation being 1708 performed, except with the Overwrite header set to "false." A 1709 response of 412, Precondition Failed, is returned because the 1710 destination resource has a non-null state. 1711 COPY /~fielding/index.html HTTP/1.1 1712 Host: www.ics.uci.edu 1713 Destination: 1714 http://www.ics.uci.edu/users/f/fielding/index.html 1716 HTTP/1.1 412 Precondition Failed 1718 3.6 MOVE Method 1720 3.6.1 Problem Description 1722 The move operation on a resource is the logical equivalent of a 1723 copy followed by a delete. 1725 In HTTP 1.1, the procedure could be performed in several steps. 1726 First, the client could issue a GET to retrieve a representation 1727 of a resource, issue a DELETE to remove the resource from the 1728 server, then use PUT to place the resource on the server with a 1729 new URI. As is the case for COPY - because of the network traffic 1730 involved in making a move, and because there is often no way to 1731 fully express a resource as an entity without a loss of fidelity 1732 - server move functionality is preferable. 1734 With a DAV server, a principal may accomplish this task by 1735 issuing a COPY and then DELETE. Network load decreases, but the 1736 server load may still be significant because the server must 1737 create a duplicate resource. Were a server to know beforehand 1738 that a principal intended to perform COPY and DELETE operations 1739 in succession, it could avoid the creation of a duplicate 1740 resource. 1742 3.6.2 Solution Requirements 1744 The solution: 1745 - Must prevent the unneeded transfer of entity bodies from and 1746 to the server. 1747 - Must prevent the unneeded creation of copies by the server. 1749 3.6.3 The Request 1751 The MOVE method is defined as the logical equivalent of a COPY 1752 followed by a DELETE of the source resource, performed 1753 atomically. 1755 3.6.4 The Response 1757 200 (OK) - The resource was moved. A successful response must 1758 contain the Content-Location header, set equal to the URI in 1759 source. This lets caches properly flush any cached entries for 1760 the source. Unfortunately the Content-Location header only allows 1761 a single value so it is not possible for caches unfamiliar with 1762 the MOVE method to properly clear their caches. 1764 207 (Partial Success) Only some of the member resources were 1765 moved. The return entity body will give the status code for each 1766 resource. 1768 412 (Precondition Failed) This status code MUST be returned if 1769 the server was unable to maintain the liveness of the properties 1770 listed in the Enforce-Live-Properties header, or if the Overwrite 1771 header is false, and the state of the destination resource is 1772 non- 1773 null. 1775 501 (Not Implemented) - This may occur if the Destination header 1776 specifies a resource which is outside its domain of control 1777 (e.g., stored on another server) resource and the server either 1778 refuses or is incapable of moving to an external resource. 1780 502 (Bad Gateway) - This may occur when moving to external 1781 resources and the destination server refused to accept the 1782 resource. 1784 3.6.5 Examples 1786 3.6.5.1 Overwrite Example 1787 This example shows resource 1788 http://www.ics.uci.edu/~fielding/index.html being moved to the 1789 location http://www.ics.uci.edu/users/f/fielding/index.html. The 1790 contents of the destination resource were overwritten, if non- 1791 null. 1792 MOVE /~fielding/index.html HTTP/1.1 1793 Host: www.ics.uci.edu 1794 Destination: 1795 http://www.ics.uci.edu/users/f/fielding/index.html 1796 Overwrite: true 1798 HTTP/1.1 200 OK 1799 Content-Location: 1800 http://www.ics.uci.edu/users/f/fielding/index.html 1802 3.7 ADDREF Method 1804 3.7.1 Problem Definition 1806 There needs to be a way to add an external member to a 1807 collection. 1809 3.7.2 Solution Requirements 1811 The solution must: 1812 - allow access control 1813 - allow referencing to URIs of external members 1814 - not require a body 1816 3.7.3 The Request 1818 The ADDREF method adds the URI specified in the Collection-Member 1819 header as an external member to the collection specified by the 1820 Request-URI. The value in the Collection-Member header MUST be an 1821 absolute URI meeting the requirements of an external member URI. 1822 The propagation type of the external URI is specified in the 1823 Collection-Member Header. 1825 3.8 DELREF Method 1827 3.8.1 Problem Definition 1829 There needs to be a way to remove an external member from a 1830 collection. 1832 3.8.2 Solution Requirements 1834 The solution must: 1835 - allow access control 1836 - allow referencing to URIs of external members 1837 - not require a body 1839 3.8.3 The Request 1841 The DELREF method removes the URI specified in the Collection- 1842 Member header from the collection specified by the Request-URI. 1844 3.9 PATCH Method 1846 3.9.1 Problem Definition 1848 At present, if a principal wishes to modify a resource, they must 1849 issue a GET against the resource, modify their local copy of the 1850 resource, and then issue a PUT to place the modified resource on 1851 the server. This procedure is inefficient because the entire 1852 entity for a resource must be transmitted to and from the server 1853 in order to make even small changes. Ideally, the update entity 1854 transmitted to the server should be proportional in size to the 1855 modifications. 1857 3.9.2 Solution Requirements 1859 The solution must: 1860 - allow partial modification of a resource without having to 1861 transmit the entire modified resource 1862 - allow byte-range patching 1863 - allows extensions so that patches can be done beyond simple 1864 byte-range patching 1865 - allow ranges to be deleted, inserted, and replaced 1867 3.9.3 The Request 1869 The PATCH method contains a list of differences between the 1870 original version of the resource identified by the Request-URI 1871 and the desired content of the resource after the PATCH action 1872 has been applied. The list of differences is in a format defined 1873 by the media type of the entity (e.g., "application/diff") and 1874 must include sufficient information to allow the server to 1875 convert the original version of the resource to the desired 1876 version. 1878 Since the semantics of PATCH are non-idempotent, responses to 1879 this method are not cacheable. 1881 If the request appears (at least initially) to be acceptable, the 1882 server MUST transmit an interim 100 response message after 1883 receiving the empty line terminating the request headers and 1884 continue processing the request. 1886 While server support for PATCH is optional, if a server does 1887 support PATCH, it MUST support at least the application/xml diff 1888 format defined below. Support for the VTML difference format 1889 [VTML] is recommended, but not required. 1891 3.9.4 application/XML elements for PATCH 1893 The resourceupdate XML elementXML element contains a set of XML 1894 sub-entities that describe modification operations. The name and 1895 meaning of these XML elements is given below. Processing of these 1896 directives MUST be performed in the order encountered within the 1897 XML document. A directive operates on the resource as modified 1898 by all previous directives (executed in sequential order). 1900 3.9.4.1 ResourceUpdate 1902 Name: http://www.ietf.org/standards/dav/patch/resourceupdate 1903 Purpose: Contains an ordered set of changes to a non-collection, 1904 non-property resource. 1905 Schema: http://www.ietf.org/standards/dav/patch/ 1906 Parent: 1907 Value: *(Insert | Delete | Replace) 1909 3.9.4.2 Insert 1911 Name: http://www.ietf.org/standards/dav/patch/insert 1912 Purpose: Insert the XML elementXML element�s contents starting 1913 exactly at the specified octet. 1914 Schema: http://www.ietf.org/standards/dav/patch/ 1915 Parent: ResourceUpdate 1916 Value: The insert XML elementXML element MUST contain an octet 1917 XML elementXML element that specifies an octet position within 1918 the body of a resource. A value of "end" specifies the end of 1919 the resource. The body of the insert XML elementXML element 1920 contains the octets to be inserted. 1922 3.9.4.3 Delete 1924 Name: http://www.ietf.org/standards/dav/patch/delete 1925 Purpose: Removes the specified range of octets. 1926 Schema: http://www.ietf.org/standards/dav/patch/ 1927 Parent: ResourceUpdate 1928 Value: The Delete XML elementXML element MUST contain an 1929 octet- 1930 range XML elementXML element. The value of this XML elementXML 1931 element is empty. 1932 Discussion: The octets which are deleted are removed, which means 1933 the resource is collapsed and the length of the resource is 1934 decremented by the size of the octet range. It is not 1935 appropriate to replace deleted octets with zeroed-out octets, 1936 since zero is a valid octet value. 1938 3.9.4.4 Replace 1940 Name: http://www.ietf.org/standards/dav/patch/replace 1941 Purpose: Replaces the specified range of octets with the 1942 contents of the XML element. If the number of octets in the XML 1943 element is different from the number of octets specified, the 1944 update MUST be rejected. 1945 Schema: http://www.ietf.org/standards/dav/patch/ 1946 Parent: ResourceUpdate 1947 Value: The Replace XML element MUST contain an octet-range XML 1948 element. The contents of the entity are the replacement octets. 1950 3.9.4.5 Octet-Range Attribute 1952 Name: http://www.ietf.org/standards/dav/patch/octet- 1953 range 1954 Purpose: Specifies a range of octets which the enclosing 1955 property effects. 1956 Schema: http://www.ietf.org/standards/dav/patch/ 1957 Parent: Insert, Delete, Replace 1958 Value: number ["-" (number | "end")] 1959 Number = 1*Digit 1960 Description: Octet numbering begins with 0. If the octet contains 1961 a single number then the operation is to begin at that octet and 1962 to continue for a length specified by the operation. In the case 1963 of a delete, this would mean to delete but a single octet. In the 1964 case of an insert this would mean to begin the insertion at the 1965 specified octet and to continue for the length of the included 1966 value, extending the resource if necessary. In the case of 1967 replace, the replace begins at the specified octet and overwrites 1968 all that follow to the length of the included value. Octet 1969 values MUST specify locations in the state of the resource prior 1970 to the processing of the PATCH method. 1972 3.9.5 The Response 1974 200 (OK) - The request entity body was processed without error, 1975 resulting in an update to the state of the resource. 1977 409 (Conflict) - If the update information in the request message 1978 body does not make sense given the current state of the resource 1979 (e.g., an instruction to delete a non-existent line), this status 1980 code MAY be returned. 1982 415 (Unsupported Media Type) - The server does not support the 1983 content type of the update instructions in the request message 1984 body. 1986 416 (Unprocessable Entity) - A new status code. The server 1987 understands the content type of the request entity, but was 1988 unable to process the contained instructions. 1990 3.9.6 Examples 1992 3.9.6.1 HTML file modification 1994 The following example shows a modification of the title and 1995 contents of the HTML resource http://www.example.org/hello.html. 1996 Before: 1997 1998 1999 Hello world HTML page 2000 2001 2002

Hello, world!

2003 2004 2005 PATCH Request: Response: 2006 PATCH hello.html HTTP/1.1 2007 Host: www.example.org 2008 Content-Type: application/xml 2009 Content-Length: xxx 2011 HTTP/1.1 100 Continue 2012 2013 http://www.ietf.org/standards/dav/patch/ 2014 D 2015 2016 14&003CTITLE&003ENew 2017 Title&003C/TITLE&003E 2018 38-50 2019 86&003CP&003ENew 2020 paragraph&003C/P&003E 2021 2022 2023 HTTP/1.1 200 OK 2024 After: 2025 2026 2027 New Title 2028 2029 2030

Hello, world!

2031

New paragraph

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