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

Hello, world!

2116 2117 2118 PATCH Request: Response: 2119 PATCH hello.html HTTP/1.1 2120 Host: www.example.org 2121 Content-Type: text/xml 2122 Content-Length: xxx 2124 HTTP/1.1 100 Continue 2125 2127 2128 14&003CTITLE&003ENew Title&003C/TITLE&003E 2130 38-50 2131 86& 2132 003CP&003ENew paragraph&003C/P&003E 2133 2134 HTTP/1.1 200 OK 2135 After: 2136 2137 2138 New Title 2139 2140 2141

Hello, world!

2142

New paragraph

2143 2144 2146 3.11 Headers 2148 3.11.1 Destination Header 2150 The Destination header specifies a destination resource for 2151 methods such as COPY and MOVE, which take two URIs as parameters. 2152 Destination= "Destination" ":" URI 2154 3.11.2 Enforce-Live-Properties Header 2156 The Enforce-Live-Properties header specifies properties that MUST 2157 be "live" after they are copied (moved) to the destination 2158 resource of a copy (or move). If the value "*" is given for the 2159 header, then it designates all live properties on the source 2160 resource. If the value is "Omit" then the server MUST NOT 2161 duplicate on the destination resource any properties that are 2162 defined on the source resource. If this header is not included 2163 then the server is expected to act as defined by the default 2164 property handling behavior of the associated method. 2166 EnforceLiveProperties = "Enforce-Live-Properties" ":" ("*" | 2167 "Omit" | 1#(Property-Name)) 2168 Property-Name = "<" URI ">" 2169 3.11.3 Overwrite Header 2171 The Overwrite header specifies whether the server should 2172 overwrite the state of a non-null destination resource during a 2173 COPY or MOVE. A value of "false" states that the server MUST NOT 2174 perform the COPY or MOVE operation if the state of the 2175 destination resource is non-null. By default, the value of 2176 Overwrite is "true," and a client MAY omit this header from a 2177 request when its value is "true." While the Overwrite header 2178 appears to duplicate the functionality of the If-Match: * header 2179 of HTTP/1.1, If-Match applies only to the Request-URI, and not to 2180 the Destination of a COPY or MOVE. 2182 Overwrite = "Overwrite" ":" ("true" | "false") 2184 If there is a conflict and the Overwrite header equals "true", or 2185 is absent and thus defaults to "true", then the method MUST fail 2186 with a 409 Conflict. 2188 3.11.4 Destroy Header 2190 When deleting a resource the client often wishes to specify 2191 exactly what sort of delete is being enacted. The Destroy header, 2192 used with the Mandatory header, allows the client to specify the 2193 end result they desire. The Destroy header is specified as 2194 follows: 2196 The Undelete token requests that, if possible, the resource 2197 should be left in a state such that it can be undeleted. The 2198 server is not required to honor this request. 2200 The NoUndelete token requests that the resource MUST NOT be left 2201 in a state such that it can be undeleted. 2203 The VersionDestroy token includes the functionality of the 2204 NoUndelete token and extends it to include having the server 2205 remove all versioning references to the resource that it has 2206 control over. 2208 DestroyHeader = "Destroy" ":" #Choices 2210 Choices = "VersionDestroy" | "NoUndelete" | "Undelete" | token 2211 |"<" URI ">" ; a token extension MUST NOT be used unless it is 2212 specified in a RFC16, otherwise a URI MUST be used for 2213 extensions. 2215 3.11.5 Collection-Member Header 2217 The Collection-Member header specifies the URI of an external 2218 resource to be added/deleted to/from a collection. 2220 CollectionMember = "Collection-Member" ":" URI 2222 3.12 Links 2224 3.12.1 Source Link Property Type 2226 Name: http://www.ietf.org/standards/dav/link/source 2227 Purpose: The destination of the source link identifies the 2228 resource that contains the unprocessed source of the link�s 2229 source. 2231 Schema: http://www.ietf.org/standards/dav/link/ 2232 Parent: Any 2233 Value: An XML document with zero or more link XML 2234 elements. 2236 Discussion: The source of the link (src) is typically the URI of 2237 the output resource on which the link is defined, and there is 2238 typically only one destination (dst) of the link, which is the 2239 URI where the unprocessed source of the resource may be accessed. 2240 When more than one link destination exists, this specification 2241 asserts no policy on ordering. 2243 4 State Tokens 2245 4.1 Overview 2247 4.1.1 Problem Description 2249 There are times when a principal will want to predicate 2250 successful execution of a method on the current state of a 2251 resource. While HTTP/1.1 provides a mechanism for conditional 2252 execution of methods using entity tags via the "If-Match" and 2253 "If-None-Match" headers, the mechanism is not sufficiently 2254 extensibleto express conditional statements involving more 2255 generic state indicators, such as lock tokens. 2257 The fundamental issue with entity tags is that they can only be 2258 generated by a resource. However there are times when a client 2259 will want to be able to share state tokens between resources, 2260 potentially on different servers, as well as be able to generate 2261 certain types of lock tokens without first having to communicate 2262 with a server. 2264 For example, a principal may wish to require that resource B have 2265 a certain state in order for a method to successfully execute on 2266 resource A. If the client submits an e-tag from resource B to 2267 resource A, then A has no way of knowing that the e-tag is meant 2268 to describe resource B. 2270 Another example occurs when a principal wishes to predicate the 2271 successful completion of a method on the absence of any locks on 2272 a resource. It is not sufficient to submit an "If-None-Match: *" 2273 as this refers to the existence of an entity, not of a lock. 2275 This draft defines the term "state token" as an identifier for a 2276 state of a resource. The sections below define requirements for 2277 state tokens and provide a state token syntax, along with two 2278 new headers which can accept the new state token syntax. 2280 4.1.2 Solution Requirements 2282 4.1.2.1 Syntax 2284 Self-Describing. A state token must be self describing such that 2285 upon inspecting a state token it is possible to determine what 2286 sort of state token it is, what resource(s) it applies to, and 2287 what state it represents. 2289 This self-describing nature allows servers to accept tokens from 2290 other servers and potentially be able to coordinate state 2291 information cross resource and cross site through standardized 2292 protocols. For example, the execution of a request on resource A 2293 can be predicated on the state of resource B, where A and B are 2294 potentially on different servers. 2296 Client Generable. The state token syntax must allow, when 2297 appropriate, for clients to generate a state token without having 2298 first communicated with a server. 2300 One drawback of entity tags is that they are set by the server, 2301 and there is no interoperable algorithm for calculating an entity 2302 tag. Consequently, a client cannot generate an entity tag from a 2303 particular state of a resource. However, a state token which 2304 encodes an MD5 state hash could be calculated by a client based 2305 on a client-held state of a resource, and then submitted to a 2306 server in a conditional method invocation. 2308 Another potential use for client generable state tokens is for a 2309 client to generate lock tokens with wild card fields, and hence 2310 be able to express conditionals such as: "only execute this GET 2311 if there are no write locks on this resource." 2313 4.1.2.2 Conditonals 2315 Universal. A solution must be applicable to all requests. 2316 Positive and Negative. Conditional expressions must allow for the 2317 expression of both positive and negative state requirements. 2319 4.2 State Token Syntax 2320 State tokens are URLs employing the following syntax: 2321 State-Token = "StateToken:" Type ":" Resources ":" State-Info 2322 Type = "Type" "=" Caret-encoded-URL 2323 Resources = "Res" "=" Caret-encoded-URL 2324 Caret-encoded-URL = "^" Resource "^" 2325 Resource = 2326 State-Info = *(uchar | reserved) ; uchar, reserved defined 2327 section 3.2.1 of RFC 2068 2329 This proposal has created a new URL scheme for state tokens 2330 because a state token names a network resource using its normal 2331 name, which is typically state-invariant, along with additional 2332 information that specifies a particular state of the resource. 2333 Encoding the state information into the native URL scheme of the 2334 network resource was not felt to be safe, since freedom from name 2335 space collisions could not be guaranteed. If this proposal is 2336 accepted, the StateToken URL scheme will need to be defined and 2337 registered with IANA. 2339 State Token URLs begin with the URL scheme name "StateToken" 2340 rather than the name of the particular state token type they 2341 represent in order to make the URL self describing. Thus it is 2342 possible to examine the URL and know, at a minimum, that it is a 2343 state token. 2345 Labeled name/value pairs are used within the token to allow new 2346 fields to be added. Processors of state tokens MUST be prepared 2347 to accept the fields in whatever order they are present and MUST 2348 ignore any fields they do not understand. 2349 The "Type" field specifies the type of the state information 2350 encoded in the state token. A URL is used in order to avoid 2351 namespace collisions. 2353 The "Res" field identifies the resource for which the state token 2354 specifies a particular state. Since commas and spaces are 2355 acceptable URL characters, a caret is used to delimit a URL. 2356 Since a caret is an acceptable URL character, any instances of it 2357 must be escaped using the % escape convention. 2359 The State-Info production is expanded upon in descriptions of 2360 specific state token types, and is intended to contain the state 2361 description information for a particular state token. 2363 4.3 State Token Conditional Headers 2365 4.3.1 If-State-Match 2367 If-State-Match = "If-State-Match" ":" ("AND" | "OR") 1#("<" 2368 State-Token ">") 2370 The If-State-Match header is intended to have similar 2371 functionality to the If-Match header defined in section 14.25 of 2372 RFC 2068. 2374 If the AND keyword is used and all of the state tokens identify 2375 the state of the resource, then the server MAY perform the 2376 requested method. If the OR keyword is used and any of the state 2377 tokens identifies the current state of the resource, then server 2378 MAY perform the requested method. If neither of the keyword 2379 requirements is met, the server MUST NOT perform the requested 2380 method, and MUST return a 412 (Precondition Failed) response. 2382 4.3.2 If-None-State-Match 2384 If-None-State-Match = "If-None-State-Match" ":" 1#("<" State- 2385 Token ">") 2387 The If-None-State-Match header is intended to have similar 2388 functionality to the If-None-Match header defined in section 2389 14.26 of RFC 2068. 2391 If any of the state tokens identifies the current state of the 2392 resource, the server MUST NOT perform the requested method. 2393 Instead, if the request method was GET, HEAD, INDEX, or GETMETA, 2394 the server SHOULD respond with a 304 (Not Modified) response, 2395 including the cache-related entity-header fields (particularly 2396 ETag) of the current state of the resource. For all other 2397 request methods, the server MUST respond with a status of 412 2398 (Precondition Failed). 2400 If none of the state tokens identifies the current state of the 2401 resource, the server MAY perform the requested method. 2403 Note that the "AND" and "OR" keywords specified with the If- 2404 State-Match header are intentionally not defined for If-None- 2405 State-Match, because this functionality is not required. 2407 4.4 State Token Header 2409 State-Token-Header = "State-Token" ":" 1#("<" State-Token ">") 2410 The State Token header is intended to have similar functionality 2411 to the etag header defined in section 14.20 of RFC 2068. The 2412 purpose of the tag is to return state tokens defined on a 2413 resource in a response. The contents of the state-token are not 2414 guaranteed to be exhaustive and are generally used to return a 2415 new state token that has been defined as the result of a method. 2416 For example, if a LOCK method were successfully executed on a 2417 resource the response would include a state token header with the 2418 lock state token included. 2420 4.5 E-Tags 2421 E-tags have already been deployed using the If-Match and If-None- 2422 Match headers. Introducing two mechanisms to express e-tags 2423 would only confuse matters, therefore e-tags should continue to 2424 be expressed using quoted strings and the If-Match and If-None- 2425 Match headers. 2427 5 Locking 2429 5.1 Locking: Introduction 2431 Locking is used to arbitrate access to a resource amongst 2432 principals that have equal access rights to that resource. 2434 This specification allows locks to vary over two parameters, the 2435 number of principals involved and the type of access to be 2436 granted. Furthermore, this document only provides the definition 2437 of locking for one access type, write. However, the syntax is 2438 extensible, and allows the specification of other access types. 2440 5.1.1 Exclusive Vs. Shared Locks 2442 The most basic form of lock is an exclusive lock. This is a lock 2443 where the access right in question is only granted to a single 2444 principal. The need for this arbitration results from a desire to 2445 avoid having to constantly merge results. In fact, many users so 2446 dislike having to merge that they would rather serialize their 2447 access to a resource rather than have to constantly perform 2448 merges. 2450 However, there are times when the goal of a lock is not to 2451 exclude others from exercising an access right but rather to 2452 provide a mechanism for principals to indicate that they intend 2453 to exercise their access right. Shared locks are provided for 2454 this case. A shared lock allows multiple principals to receive a 2455 lock, hence any principal with appropriate access can get the 2456 lock. 2458 With shared locks there are two trust sets that affect a 2459 resource. The first trust set is created by access permissions. 2460 Principals who are trusted, for example, may have permission to 2461 write the resource, those who are not, don't. Among those who 2462 have access permission to write the resource, the set of 2463 principals who have taken out a shared lock also must trust each 2464 other, creating a (typically) smaller trust set within the access 2465 permission write set. 2467 Starting with every possible principal on the Internet, in most 2468 situations the vast majority of these principals will not have 2469 write access to a given resource. Of the small number who do 2470 have write access, some principals may decide to guarantee their 2471 edits are free from overwrite conflicts by using exclusive write 2472 locks. Others may decide they trust their collaborators (the 2473 potential set of collaborators being the set of principals who 2474 have write permission) and use a shared lock, which informs their 2475 collaborators that a principal is potentially working on the 2476 resource. 2478 The WebDAV extensions to HTTP do not need to provide all of the 2479 communications paths necessary for principals to coordinate their 2480 activities. When using shared locks, principals may use any out 2481 of band communication channel to coordinate their work (e.g., 2482 face-to-face interaction, written notes, post-it notes on the 2483 screen, telephone conversation, email, etc.) The intent of a 2484 shared lock is to let collaborators know who else is potentially 2485 working on a resource. 2487 Shared locks are included because experience from web distributed 2488 authoring systems has indicated that exclusive write locks are 2489 often too rigid. An exclusive write lock is used to enforce a 2490 particular editing process: take out exclusive write lock, read 2491 the resource, perform edits, write the resource, release the 2492 lock. What happens if the lock isn't released? While the time- 2493 out mechanism provides one solution, if you need to force the 2494 release of a lock immediately, it doesn't help much. Granted, an 2495 administrator can release the lock for you, but this could become 2496 a significant burden for large sites. In addition there is the 2497 problem that an administrator may not be immediately available. 2499 Despite their potential problems, exclusive write locks are 2500 extremely useful, since often a guarantee of freedom from 2501 overwrite conflicts is what is needed. The tradeoff described in 2502 this specification is to provide exclusive write locks, but also 2503 to provide a less strict mechanism in the form of shared locks 2504 which can be used by a set of people who trust each other and who 2505 have access to a communications channel external to HTTP which 2506 can be used to negotiate writing to the resource. 2508 5.1.2 Required Support 2510 A WebDAV compliant server is not required to support locking in 2511 any form. If the server does support locking it may choose to 2512 support any combination of exclusive and shared locks for any 2513 access types. 2515 The reason for this flexibility is that server implementers have 2516 said that they are willing to accept minimum requirements on all 2517 services but locking. Locking policy strikes to the very heart of 2518 their resource management and versioning systems and they require 2519 control over what sort of locking will be made available. For 2520 example, some systems only support shared write locks while 2521 others only provide support for exclusive write locks while yet 2522 others use no locking at all. As each system is sufficiently 2523 different to merit exclusion of certain locking features, the 2524 authors are proposing that locking be allowed as the sole axis of 2525 negotiation within WebDAV. 2527 5.2 LOCK Method 2529 The following sections describe the LOCK method, which is used to 2530 take out a lock of any access type. These sections on the LOCK 2531 method describe only those semantics that are specific to the 2532 LOCK method and are independent of the access type of the lock 2533 being requested. Once the general LOCK method has been 2534 described, subsequent sections describe the semantics of the 2535 "write" access type, and the write lock. 2537 5.2.1 Operation 2538 A LOCK method invocation creates the lock specified by the Lock- 2539 Info header on the Request-URI. Lock method requests SHOULD NOT 2540 have a request body. A user-agent SHOULD submit an Owner header 2541 field with a lock request. 2543 A successful response to a lock invocation MUST include Lock- 2544 Token and Time-Out headers. 2546 5.2.2 The Effect of Locks on Properties and Containers 2548 By default the scope of a lock is the entire state of the 2549 resource, including its body and associated properties. As a 2550 result, a lock on a resource also locks the resource's 2551 properties, and a lock on a property may lock a property's 2552 resource or may restrict the ability to lock the property's 2553 resource. Only a single lock token MUST be used when a lock 2554 extends to cover both a resource and its properties. Note that 2555 certain lock types MAY override this behavior. 2557 For containers, a lock also affects the ability to add or remove 2558 members. The nature of the effect depends upon the type of access 2559 control involved. 2561 5.2.3 Locking Replicated Resources 2563 Some servers automatically replicate resources across multiple 2564 URLs. In such a circumstance the server MAY only accept a lock on 2565 one of the URLs if the server can guarantee that the lock will be 2566 honored across all the URLs. 2568 5.2.4 Locking Multiple Resources 2570 The LOCK method supports locking multiple resources 2571 simultaneously by allowing for the listing of several URIs in the 2572 LOCK request. These URIs, in addition to the Request-URI, are 2573 then to be locked as a result of the LOCK method's invocation. 2574 When multiple resources are specified the LOCK method only 2575 succeeds if all specified resources are successfully locked. 2577 The Lock-Tree option of the lock request specifies that the 2578 resource and all its internal children (including internal 2579 collections, and their internal members) are to be locked. This 2580 is another mechanism by which a request for a lock on multiple 2581 resources can be specified. 2583 Currently existing locks can not be extended to cover more or 2584 less resources, and any request to expand or contract the number 2585 of resources in a lock MUST fail with a 409 Conflict status code. 2586 So, for example, if resource A is exclusively write locked and 2587 then the same principal asked to exclusively write lock resources 2588 A, B, and C, the request would fail as A is already locked and 2589 the lock can not be extended. 2591 A successful result will return a single lock token which 2592 represents all the resources that have been locked. If an UNLOCK 2593 is executed on this token, all associated resources are unlocked. 2595 If the lock can not be granted to all resources, a 406 Conflict 2596 status code MUST be returned with a response entity body 2597 containing a multiresponse XML element describing which 2598 resource(s) prevented the lock from being granted. 2600 5.2.5 Interaction with other Methods 2602 The interaction of a LOCK with various methods is dependent upon 2603 the lock type. However, independent of lock type, a successful 2604 DELETE of a resource MUST cause all of its locks to be removed. 2606 5.2.6 Lock Compatibility Table 2608 The table below describes the behavior that occurs when a lock 2609 request is made on a resource. 2611 Current lock state/ Shared Lock Exclusive Lock 2612 Lock request 2613 None True True 2614 Shared Lock True False 2615 Exclusive Lock False False* 2617 Legend: True = lock MAY be granted. False = lock MUST NOT be 2618 granted. *=if the principal requesting the lock is the owner of 2619 the lock, the lock MAY be regranted. 2621 The current lock state of a resource is given in the leftmost 2622 column, and lock requests are listed in the first row. The 2623 intersection of a row and column gives the result of a lock 2624 request. For example, if a shared lock is held on a resource, 2625 and an exclusive lock is requested, the table entry is "false", 2626 indicating the lock must not be granted. 2628 If an exclusive or shared lock is re-requested by the principal 2629 who owns the lock, the lock MUST be regranted. If the lock is 2630 regranted, the same lock token that was previously issued MUST be 2631 returned. 2633 5.2.7 Status Codes 2635 409 "Conflict" - The resource is locked, so the method has been 2636 rejected. 2638 412 "Precondition Failed" - The included state-token was not 2639 enforceable on this resource or the request in the lock-info 2640 header could not be satisfied by the server. 2642 5.2.8 Lock-Info Request Header 2644 The Lock-Info request header specifies the scope and type of a 2645 lock for a LOCK method request. The syntax specification below is 2646 extensible, allowing new type and scope identifiers to be added. 2648 LockInfo = "Lock-Info" ":" DAVLockType SP DAVLockScope [SP 2649 AdditionalLocks] [SP Lock-Tree] 2650 DAVLockType = "LockType" "=" DAVLockTypeValue 2651 DAVLockTypeValue = ("Write" | *(uchar | reserved)) 2652 DAVLockScope = "LockScope" "=" DAVLockScopeValue 2653 DAVLockScopeValue = ("Exclusive" |"Shared" | *(uchar | reserved)) 2654 AdditionalLocks = "AddLocks" "=" 1*("<" URI ">") 2655 Lock-Tree = "Lock-Tree" "=" ("True" | "False") 2657 The LockType field specifies the access type of the lock. At 2658 present, this specification only defines one lock type, the 2659 "Write" lock. The LockScope field specifies whether the lock is 2660 an exclusive lock, or a shared lock. The AddLocks field 2661 specifies additional URIs, beyond the Request-URI, to which the 2662 lock request applies. The LockTree field is used to specify 2663 recursive locks. If the LockTree field is "true", the lock 2664 request applies to the hierarchy traversal of the internal 2665 members resources of the Request-URI, and the AddLocks URIs, 2666 inclusive of the Request-URI and the AddLocks URIs. It is not an 2667 error if LockTree is true, and the Request-URI or the AddLocks 2668 URIs have no internal member resources. By default, the value of 2669 LockTree is "false", and this field MAY be omitted when its value 2670 is false. 2672 5.2.9 Owner Request Header 2674 5.2.9.1 Problem Description 2676 When discovering the list of owners of locks on a resource, a 2677 principal may want to be able to contact the owner directly. For 2678 this to be possible the lock discovery mechanism must provide 2679 enough information for the lock owner to be contacted. 2680 Additionally, programs may wish to be able to record structured 2681 information in the owner header so that other programs may be 2682 able to parse it later. Note, however, that these programs may 2683 not necessarily be coordinating so there need be no guarantee 2684 that the information can be parsed. 2686 5.2.9.2 Solution Requirements 2688 Not all systems have authentication procedures that provide 2689 sufficient information to identify a particular user in a way 2690 that is meaningful to a person. In addition, many systems that do 2691 have sufficient information, such as a name and e-mail address, 2692 do not have the ability to associate this information with the 2693 lock discovery mechanism. Therefore a means is needed to allow 2694 principals to provide authentication in a manner which will be 2695 meaningful to a person. 2697 The From header (defined in RFC 2068), which contains only an 2698 email mailbox, is not sufficient for the purposes of quick 2699 identification. When desperately looking for someone to remove a 2700 lock, e-mail is often not sufficient. A telephone number (cell 2701 number, pager number, etc.) would be better. Furthermore, the 2702 email address in the From header only optionally includes the 2703 owners name and that name is often set to an alias anyway. 2704 Therefore a header more flexible than From is required. 2706 The value also needs to be such that both man and machine can 2707 place values in it and later retrieve those values. 2709 5.2.9.3 Syntax 2711 Owner = "Owner" ":" (Coded-XML | quoted-string) 2712 Coded-XML = field-content ; XML where any character which is 2713 not legal in field-content (see section 4.2 of [Fielding et al., 2714 1997]) is XML encoded 2716 The XML SHOULD provide information sufficient for either directly 2717 contacting the principal (such as a telephone number or e-mail 2718 URI), or for discovering the principal (such as the URL of a 2719 homepage) who owns the lock. The quoted string SHOULD provide a 2720 means for directly contacting the principal who owns the lock, 2721 such as a name and telephone number. 2723 5.2.10 Time-Out Header 2725 5.2.10.1 Problem Description 2727 In a perfect world principals take out locks, work on the 2728 resource, and then remove the lock when it is no longer needed. 2729 However, this process is frequently not completed, leaving active 2730 but unused locks. Reasons for this include client programs 2731 crashing and losing information about locks, users leaving their 2732 systems for the day and forgetting to remove their locks, etc. As 2733 a result of this behavior, servers need to establish a policy by 2734 which they can remove a lock without input from the lock owner. 2735 Once such a policy is instituted, the server also needs a 2736 mechanism to inform the principal of the policy. 2738 5.2.10.2 Solution Requirements 2740 There are two basic lock removal policies: administrator and time 2741 based removal. In the case of administrator based removal, a 2742 principal other than the lock owner has sufficient access rights 2743 to order the lock removed, even though they did not take it out. 2744 The second policy type is time based removal. In this case, a 2745 timer is set as soon as the lock is created. Every time a method 2746 is executed on any resource covered by the lock, the timer is 2747 reset. If the timer runs out, the lock is removed. 2749 User-agents MUST assume that locks may arbitrarily disappear at 2750 any time. If their actions require confirmation of the existence 2751 of a lock then the If-State headers are available. 2753 5.2.10.3 Syntax 2755 TimeOut = "Time-Out" ":" 1#TimeType 2756 TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Extend) 2757 DAVTimeOutVal = 1*digit 2758 Extend = RFC-Reg | URL "-" Token ; The URL format is used for 2759 unregistered TimeTypes 2760 RFC-Req = Token ; This is a TimeType that has been published as 2761 an RFC 2763 Clients MAY include TimeOut headers in their LOCK requests. 2764 However the server is not required to honor or even consider the 2765 request. Clients MUST NOT submit a Time-Out request header with 2766 any method other than a LOCK method. 2768 A Time-Out request header MUST contain at least one TimeType and 2769 MAY contain multiple TimeType entries. The purpose of listing 2770 multiple TimeType is to indicate multiple different values and 2771 value types that are acceptable to the client. The client lists 2772 the TimeType entries in order of preference. 2774 The Time-Out response header MUST use a Second value, Infinite, 2775 or a TimeType the client has indicated familiarity with. The 2776 server MAY assume a client is familiar with any TimeType 2777 submitted in a Time-Out header. 2779 The "Second" TimeType specifies the number of seconds that MUST 2780 elapse between granting of the lock at the server, and the 2781 automatic removal of the lock. A server MUST not generate a time 2782 out value for "Second" greater than 2^32-1. 2784 The time out counter is restarted any time the client sends a 2785 method to any member of the lock, including unsupported methods, 2786 or methods which are unsuccessful. It is recommended that the 2787 HEAD method be used when the goal is simply to restart the time 2788 out counter. 2790 If the timeout expires then the lock is lost. Specifically the 2791 server SHOULD act as if an UNLOCK method was executed by the 2792 server on the resource using the lock token of the timed-out 2793 lock, performed with its override authority. Thus logs, 2794 notifications, and other mechanisms that act as side effects to 2795 the granting and removal of a lock will be properly informed as 2796 to the disposition of the lock. 2798 Servers are advised to pay close attention to the values 2799 submitted by clients, as they will be indicative of the type of 2800 activity the client intends to perform. For example, an applet 2801 running in a browser may need to lock a resource, but because of 2802 the instability of the environment within which the applet is 2803 running, the applet may be turned off without warning. As a 2804 result, the applet is likely to ask for a relatively small time- 2805 out value so that if the applet dies, the lock can be quickly 2806 harvested. However a document management system is likely to ask 2807 for an extremely long time-out because its user may be planning 2808 on going off-line. 2810 5.2.11 Lock Response 2812 A successful lock response MUST contain a Lock-Token response 2813 header, a Time-Out header and a PROP element in the response body 2814 which contains the value of the LockDiscovery property. 2816 5.2.11.1 Lock-Token Response Header 2818 If a resource is successfully locked then a lock-token header 2819 will be returned containing the lock token that represents the 2820 lock. 2822 Lock-Token = "Lock-Token" ":" URI 2824 5.2.12 Example - Simple Lock Request 2826 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2827 Host: webdav.sb.aol.com 2828 Lock-Info: LockType=Write LockScope=Exclusive 2829 Time-Out: Infinite; Second-4100000000 2830 Owner: http://www.ics.uci.edu/~ejw/contact.html 2834 HTTP/1.1 200 OK 2835 Lock-Token: OpaqueLockToken:xyz122393481230912asdfa09s8df09s7df08 2836 sd0f98a098sda 2837 Time-Out: Second-604800 2838 Content-Type: text/xml 2839 Content-Length: xxxxx 2841 2843 2844 2845 2846 write 2847 exclusive 2848 2849 2850 http://www.ics.uci.edu/~ejw/contact.html 2851 2852 Second-604800 2853 2854 2855 OpaqueLockToken:xyz122393481230912asdfa09s8df09s7d 2856 f08sd0f98a098sda 2857 2858 2859 2860 2861 2863 This example shows the successful creation of an exclusive write 2864 lock on resource 2865 http://webdav.sb.aol.com/workspace/webdav/proposal.doc. The 2866 resource http://www.ics.uci.edu/~ejw/contact.html contains 2867 contact information for the owner of the lock. The server has an 2868 activity-based timeout policy in place on this resource, which 2869 causes the lock to automatically be removed after 1 week (604800 2870 seconds). The response has a Lock-Token header that gives the 2871 state token URL for the lock token generated by this lock 2872 request. 2874 5.2.13 Example - Multi-Resource Lock Request 2876 LOCK /workspace/webdav/proposal.doc HTTP/1.1 2877 Host: webdav.sb.aol.com 2878 Lock-Info: LockType=Write LockScope=Exclusive 2879 Addlocks= 2881 Time-Out: Infinite, Second-4100000000 2882 Owner: 2884 HTTP/1.1 409 Conflict 2885 Content-Type: text/xml 2886 Content-Length: xxxxx 2888 2890 2891 2892 2893 http://webdav.sb.aol.com/workspace/webdav/proposal.doc 2894 2895 2896 http://webdav.sb.aol.com/workspace/webdav/ 2897 2898 HTTP/1.1 202 Accepted 2899 2900 2901 http://foo.bar/blah 2902 HTTP/1.1 403 Forbidden 2903 2904 2905 This example shows a request for an exclusive write lock on three 2906 resources, 2907 http://webdav.sb.aol.com/workspace/webdav/proposal.doc, 2908 http://webdav.sb.aol.com/workspace/, and http://foo.bar/blah. In 2909 this request, the client has specified that it desires an 2910 infinite length lock, if available, otherwise a timeout of 4.1 2911 billion seconds, if available. The Owner header field specifies 2912 the web address for contact information for the principal taking 2913 out the lock. 2915 This lock request has failed, because the server rejected the 2916 lock request for http://foo.bar/blah. The 409 Conflict status 2917 code indicates that the server was unable to satisfy the request 2918 because there is a conflict between the state of the resources 2919 and the operation named in the request. Within the 2920 multiresponse, the 202 Accepted status code indicates that the 2921 lock method was accepted by the resources, and would have been 2922 completed if all resources named in the request were able to be 2923 locked. The 403 Forbidden status code indicates that the server 2924 does not allow lock requests on this resource. 2926 5.3 Write Lock 2928 This section describes the semantics specific to the write access 2929 type for locks. The write lock is a specific instance of a lock 2930 type, and is the only lock type described in this specification. 2932 5.3.1 Methods Restricted by Write Locks 2934 A write lock prevents a principal without the lock from 2935 successfully executing a PUT, POST, PATCH, PROPPATCH, MOVE, 2936 DELETE, MKCOL, ADDREF or DELREF on the locked resource. All other 2937 current methods, GET in particular, function independent of the 2938 lock. 2940 Note, however, that as new methods are created it will be 2941 necessary to specify how they interact with a write lock. 2943 5.3.2 Write Locks and Properties 2945 While those without a write lock may not alter a property on a 2946 resource it is still possible for the values of live properties 2947 to change, even while locked, due to the requirements of their 2948 schemas. Only dead properties and live properties defined to 2949 respect locks are guaranteed to not change while write locked. 2951 If a property is write locked then a LOCK request on the 2952 associated resource MUST fail with a 409 "Conflict". Note that a 2953 write lock on a property MAY be extended to include the 2954 associated resource without the principal having explicitly 2955 requested the extension. 2957 5.3.3 Write Locks and Null Resources 2959 It is possible to assert a write lock on a null resource in order 2960 to lock the name. Please note, however, that locking a null 2961 resource effectively makes the resource non-null as the resource 2962 now has lock related properties defined on it. 2964 5.3.4 Write Locks and Collections 2965 A write lock on a collection prevents the addition or removal of 2966 members of the collection. As a consequence, when a principal 2967 issues a request to create a new internal member of a collection 2968 using PUT or POST, or to remove an existing internal member of a 2969 collection using DELETE, this request MUST fail if the principal 2970 does not have a write lock on the collection. 2972 However, if a write lock request is issued to a collection 2973 containing internal member resources that are currently locked, 2974 the request MUST fail with a 409 Conflict status code. 2976 5.3.5 Write Locks and COPY/MOVE 2978 The owner of a write lock MUST NOT execute a MOVE method on a 2979 resource they have locked. This specification intentionally does 2980 not define what happens if a MOVE method request is made on a 2981 locked resource by the lock's owner. 2983 A COPY method invocation MUST NOT duplicate any write locks 2984 active on the source. 2986 5.3.6 Re-issuing Write Locks 2988 If a principal already owns a write lock on a resource, any 2989 future requests for the same type of write lock, on the same 2990 resource, while the principal's previous write lock is in effect, 2991 MUST result in a successful response with the same lock token as 2992 provided for the currently existing lock. Two lock requests are 2993 defined to be identical if their Lock-Info headers are identical. 2995 5.3.7 Write Locks and The State-Token Header 2997 5.3.7.1 Problem Definition 2999 If a user agent is not required to have knowledge about a lock 3000 when requesting an operation on a locked resource, the following 3001 scenario might occur. Program A, run by User A, takes out a write 3002 lock on a resource. Program B, also run by User A, has no 3003 knowledge of the lock taken out by Program A, yet performs a PUT 3004 to the locked resource. In this scenario, the PUT succeeds 3005 because locks are associated with a principal, not a program, and 3006 thus program B, because it is acting with principal A�s 3007 credential, is allowed to perform the PUT. However, had program B 3008 known about the lock, it would not have overwritten the resource, 3009 preferring instead to present a dialog box describing the 3010 conflict to the user. Due to this scenario, a mechanism is needed 3011 to prevent different programs from accidentally ignoring locks 3012 taken out by other programs with the same authorization. 3014 5.3.7.2 Solution Requirement 3016 The solution must not require principals to perform discovery in 3017 order to prevent accidental overwrites as this could cause race 3018 conditions. 3020 The solution must not require that clients guess what sorts of 3021 locks might be used and use if-state-match headers with wildcards 3022 to prevent collisions. The problem with trying to "guess" which 3023 locks are being used is that new lock types might be introduced, 3024 and the program would not know to "guess them". So, for example, 3025 a client might put in an if-state-match header with a wildcard 3026 specifying that if any write lock is outstanding then the 3027 operation should fail. However a new read/write lock could be 3028 introduced which the client would not know to put in the header. 3030 5.3.7.3 State-Token Header 3032 The State-Token header, containing a lock token owned by the 3033 requesting principal, is used by the principal to indicate that 3034 the principal is aware of the existence of the lock specified by 3035 the lock token. It is used in the following way. 3037 If the following conditions are met: 3038 1. a user-agent has authenticated itself as a principal, 3039 2. the user-agent is submitting a method request to a 3040 resource 3041 on which the principal owns a write lock, 3042 3. the method is restricted by a write lock, as defined in 3043 the 3044 section "Methods Restricted by a Write Lock", 3045 then the method request MUST include a State-Token header with 3046 the lock token of the write lock, or the method fails with a 409 3047 Conflict status code. If multiple resources are involved with a 3048 method, such as a COPY or MOVE method, then the lock tokens, if 3049 any, for all involved resources, MUST be included in the State- 3050 Token request header. 3052 For example, Program A, used by user A, takes out a write lock on 3053 a resource. Program A then makes a number of PUT requests on the 3054 locked resource, all the requests contain a State-Token header 3055 which includes the write lock state token. Program B, also run by 3056 User A, then proceeds to perform a PUT to the locked resource. 3057 However program B was not aware of the existence of the lock and 3058 so does not include the appropriate state-token header. The 3059 method is rejected even though principal A is authorized to 3060 perform the PUT. Program B can, if it so chooses, now perform 3061 lock discovery and obtain the lock token. Note that program A and 3062 B can perform GETs without using the state-token header because 3063 the ability to perform a GET is not affected by a write lock. 3065 Having a lock state token provides no special access rights. 3066 Anyone can find out anyone else�s lock state token by performing 3067 lock discovery. Locks are to be enforced based upon whatever 3068 authentication mechanism is used by the server, not based on the 3069 secrecy of the token values. 3071 5.3.7.3.1 Example 3073 COPY /~fielding/index.html HTTP/1.1 3074 Host: www.ics.uci.edu 3075 Destination: http://www.ics.uci.edu/users/f/fielding/index.html 3076 State-Token: 3077 3079 HTTP/1.1 200 OK 3081 In this example, both the source and destination are locked so 3082 two lock tokens must be submitted. If only one of the two 3083 resources was locked, then only one token would have to be 3084 submitted. 3086 5.4 Lock Tokens 3088 5.4.1 Problem Description 3090 It is possible that once a lock has been granted it may be 3091 removed without the lock owner�s knowledge. This can cause 3092 serialization problems if the lock owner executes methods 3093 thinking their lock is still active. Due to this, a mechanism is 3094 needed for a principal to predicate the successful execution of a 3095 message upon the continuing existence of a lock. 3097 5.4.2 Lock Token Introduction 3099 A lock token is a type of state token that describes a particular 3100 lock. A lock token is returned by every successful LOCK 3101 operation, and can also be discovered through lock discovery on a 3102 resource. 3104 There are two types of lock tokens, a generic lock token, which 3105 is unique only for a particular resource, and an opaque lock 3106 token, which is unique across all resources for all time. 3108 Uniqueness for a particular resource prevents problems with long 3109 held outstanding lock tokens being confused with newer tokens. 3110 This uniqueness requirement is the same as for e-tags. Uniqueness 3111 across all resources for all time allows for tokens to be 3112 submitted across resources and servers without fear of confusion. 3114 Generic lock tokens, because of their relaxed uniqueness 3115 requirements, are faster to generate than opaque lock tokens. 3117 5.4.3 Generic Lock Tokens 3119 Any valid URI can be used by the resource as a generic lock 3120 token. The only requirement is that the lock token MUST never 3121 have been issued previously on that resource. Because a lock 3122 token is only guaranteed to be unique on the resource that 3123 generated it, the lock token MUST NOT be submitted in a state- 3124 token request header or an if-state[-not]-match header on any 3125 resource but the resource that generated it. 3127 5.4.4 OpaqueLockToken Lock Token 3129 The opaquelocktoken scheme is designed to be unique across all 3130 resources for all time. Due to this uniqueness quality, a client 3131 MAY submit an opaque lock token in a state-token request header 3132 and an if-state[-not]-match header on a resource other than the 3133 one that returned it. 3135 All resources MUST recognize the opaquelocktoken scheme and be 3136 able to, at minimum, recognize that the lock token was not 3137 generated by the resource. Note, however, that resources are not 3138 required to generate opaquelocktokens. 3140 In order to guarantee uniqueness across all resources for all 3141 time the opaquelocktoken requires the use of the GUID mechanism. 3143 Opaquelocktoken generators however have a choice of how they 3144 create these tokens. They can either generate a new GUID for 3145 every lock token they create, which is potentially very 3146 expensive, or they can create a single GUID and then add 3147 extension characters. If the second method is selected then the 3148 program generating the extensions MUST guarantee that the same 3149 extension will never be used twice with the associated GUID. 3151 Opaque-Lock-Token = "OpaqueLockToken" ":" GUID [Extension] 3152 GUID = ; As defined in [LEACH] 3153 Extension = *urlc ;urlc is defined in [Berners-Lee et al., 3154 1997] (draft-fielding-url-syntax-07.txt) 3156 5.5 UNLOCK Method 3158 5.5.1 Problem Definition 3160 The UNLOCK method removes the lock identified by the lock token 3161 in the State-Token header from the Request-URI, and all other 3162 resources included in the lock. 3164 5.5.2 Example 3166 UNLOCK /workspace/webdav/info.doc HTTP/1.1 3167 Host: webdav.sb.aol.com 3168 State-Token: OpaqueLockToken:123AbcEfg1284h23h2 3170 HTTP/1.1 200 OK 3172 In this example, the lock identified by the lock token 3173 "OpaqueLockToken:123AbcEfg1284h23h2" is successfully removed from 3174 the resource http://webdav.sb.aol.com/workspace/webdav/info.doc. 3175 If this lock included more than just one resource, the lock is 3176 removed from those resources as well. 3178 5.6 Discovery Mechanisms 3180 5.6.1 Lock Capability Discovery 3182 5.6.1.1 Problem Definition 3184 Since server lock support is optional, a client trying to lock a 3185 resource on a server can either try the lock and hope for the 3186 best, or perform some form of discovery to determine what lock 3187 capabilities the server supports. This is known as lock 3188 capability discovery. Lock capability discovery differs from 3189 discovery of supported access control types, since there may be 3190 access control types without corresponding lock types. 3192 5.6.1.2 SupportedLock Property 3194 Name: http://www.ietf.org/standards/dav/lock/supportedlock 3195 Purpose: To provide a listing of the lock capabilities supported 3196 by the resource. 3197 Schema: http://www.ietf.org/standards/dav/ 3198 Values: An XML document containing zero or more LockEntry XML 3199 elements. 3200 Description: The SupportedLock property of a resource returns a 3201 listing of the combinations of scope and access types which may 3202 be specified in a lock request on the resource. Note that the 3203 actual contents are themselves controlled by access controls so a 3204 server is not required to provide information the client is not 3205 authorized to see. If SupportedLock is available on "*" then it 3206 MUST define the set of locks allowed on all resources on that 3207 server. 3209 5.6.1.3 LOCKENTRY XML Element 3211 Name: http://www.ietf.org/standards/dav/lockentry 3212 Purpose: Defines a DAVLockType/LockScope pair which may be 3213 legally used with a LOCK on the specified resource. 3214 Schema: http://www.ietf.org/standards/dav/ 3215 Parent: A SupportedLock entry 3216 Values: LockType LockScope 3218 5.6.1.4 LOCKTYPE XML Element 3220 Name: http://www.ietf.org/standards/dav/locktype 3221 Purpose: Lists a DAVLockType 3222 Schema: http://www.ietf.org/standards/dav/ 3223 Parent: LOCKENTRY 3224 Values: DAVLockTypeValue 3226 5.6.1.5 LOCKSCOPE XML Element 3228 Name: http://www.ietf.org/standards/dav/lockscope 3229 Purpose: Lists a DAVLockScope 3230 Schema: http://www.ietf.org/standards/dav/ 3231 Parent: LOCKENTRY 3232 Values: DAVLockScopeValue 3234 5.6.1.6 Example 3236 PROPFIND /container/ HTTP/1.1 3237 Host: www.foo.bar 3238 Content-Length: xxxx 3239 Content-Type: text/xml 3241 3243 3244 3245 3247 HTTP/1.1 207 Multi-Response 3248 Content-Type: text/xml 3249 Content-Length: xxxxx 3251 3253 3254 3255 3256 3257 3258 Write 3259 Exclusive 3260 3261 3262 Write 3263 Shared 3264 3265 3266 3267 HTTP/1.1 200 Success 3268 3269 3271 5.6.2 Active Lock Discovery 3273 5.6.2.1 Problem Definition 3275 If another principal locks a resource that a principal wishes to 3276 access, it is useful for the second principal to be able to find 3277 out who the first principal is. 3279 5.6.2.2 Solution Requirements 3281 The lock discovery mechanism should provide a list of who has the 3282 resource locked, what locks they have, and what their lock tokens 3283 are. The lock tokens are useful in shared lock situations where 3284 two principals may want to guarantee that they do not overwrite 3285 each other. The lock tokens are also useful for administrative 3286 purposes so that an administrator can remove a lock by referring 3287 to its token. 3289 5.6.2.3 LOCKDISCOVERY Property 3291 Name: http://www.ietf.org/standards/dav/lockdiscovery 3292 Purpose: To discover what locks are active on a resource 3293 Schema: http://www.ietf.org/standards/dav/ 3294 Values= An XML document containing zero or more ActiveLock XML 3295 elements. 3297 Description: The LOCKDISCOVERY property returns a listing of who 3298 has a lock, what type of lock they have, the time out type and 3299 the time remaining on the time out, and the associated lock 3300 token. The server is free to withhold any or all of this 3301 information if the requesting principal does not have sufficient 3302 access rights to see the requested data. A server which supports 3303 locks MUST provide the LOCKDISCOVERY property on any resource 3304 with locks on it. 3306 5.6.2.4 ACTIVELOCK XML Element 3308 Name: http://www.ietf.org/standards/dav/activelock 3309 Purpose: A multivalued XML element that describes a particular 3310 active lock on a resource 3311 Schema: http://www.ietf.org/standards/dav/ 3312 Parent: A LOCKDISCOVERY entry 3313 Values= LOCKTYPE LOCKSCOPE [ADDLOCKS] OWNER TIMEOUT LOCKTOKEN 3315 5.6.2.5 OWNER XML Element 3317 Name: http://www.ietf.org/standards/dav/lock/owner 3318 Purpose: Returns owner information 3319 Schema: http://www.ietf.org/standards/dav/ 3320 Parent: ACTIVELOCK 3321 Values= XML:REF | {any valid XML string} 3322 5.6.2.6 TIMEOUT XML Element 3324 Name: http://www.ietf.org/standards/dav/timeout 3325 Purpose: Returns information about the timeout associated with 3326 the lock 3327 Schema: http://www.ietf.org/standards/dav/ 3328 Parent: ACTIVELOCK 3329 Values= TimeType 3331 5.6.2.7 ADDLOCKS XML Element 3333 Name: http://www.ietf.org/standards/dav/addlocks 3334 Purpose: Lists additional resources associated with this lock, if 3335 any. 3336 Schema: http://www.ietf.org/standards/dav/ 3337 Parent: ACTIVELOCK 3338 Values= 1*HREF 3340 5.6.2.8 LOCKTOKEN XML Element 3342 Name: http://www.ietf.org/standards/dav/statetoken 3343 Purpose: Returns the lock token 3344 Schema: http://www.ietf.org/standards/dav/ 3345 Parent: ACTIVELOCK 3346 Values= HREF 3347 Description: The HREF contains a Lock-Token-URL. 3349 5.6.2.9 Example 3351 PROPFIND /container/ HTTP/1.1 3352 Host: www.foo.bar 3353 Content-Length: xxxx 3354 Content-Type: text/xml 3356 3358 3359 3360 3362 HTTP/1.1 207 Multi-Response 3363 Content-Type: text/xml 3364 Content-Length: xxxxx 3366 3368 3369 3370 3371 3372 3373 write 3374 exclusive 3375 3376 http://foo.com/doc/ 3377 3378 Jane Smith 3379 Infinite 3380 3381 iamuri:unique!!!!! 3382 3383 3384 3385 3386 HTTP/1.1 200 Success 3387 3388 3390 This resource has a single exclusive write lock on it, with an 3391 infinite time out. This same lock also covers the resource 3392 http://foo.com/doc/. 3394 6 Version Control 3395 [TBD] 3397 7 Internationalization Support 3398 [TBD] 3400 8 Security Considerations 3401 [TBD] 3403 9 Copyright 3405 Copyright (C) The Internet Society October 13, 1997. All Rights 3406 Reserved. 3408 This document and translations of it may be copied and furnished 3409 to others, and derivative works that comment on or otherwise 3410 explain it or assist in its implementation may be prepared, 3411 copied, published and distributed, in whole or in part, without 3412 restriction of any kind, provided that the above copyright notice 3413 and this paragraph are included on all such copies and derivative 3414 works. However, this document itself may not be modified in any 3415 way, such as by removing the copyright notice or references to 3416 the Internet Society or other Internet organizations, except as 3417 needed for the purpose of developing Internet standards in which 3418 case the procedures for copyrights defined in the Internet 3419 Standards process must be followed, or as required to translate 3420 it into languages other than English. 3422 The limited permissions granted above are perpetual and will not 3423 be revoked by the Internet Society or its successors or 3424 assignees. 3426 This document and the information contained herein is provided on 3427 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 3428 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 3429 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE 3430 OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY 3431 IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR 3432 PURPOSE. 3434 10 Acknowledgements 3436 Terry Allen, Harald Alvestrand, Alan Babich, Dylan Barrell, 3437 Bernard Chester, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., 3438 Jim Davis, Keith Dawson, Mark Day, Martin Duerst, David Durand, 3439 Lee Farrell, Chuck Fay, Roy Fielding, Mark Fisher, Alan Freier, 3440 George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis 3441 Hamilton, Steve Henning, Alex Hopmann, Andre van der Hoek, Ben 3442 Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven Martin, 3443 Larry Masinter, Michael Mealling, Keith Moore, Henrik Nielsen, 3444 Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff, Saveen Reddy, 3445 Henry Sanders, Christopher Seiwald, Judith Slein, Mike Spreitzer, 3446 Einar Stefferud, Ralph Swick, Kenji Takahashi, Robert Thau, John 3447 Turner, Sankar Virdhagriswaran, Fabio Vitali, Gregory Woodhouse, 3448 Lauren Wood 3450 11 References 3452 [Berners-Lee, 1997] T. Berners-Lee, "Metadata Architecture." 3453 Unpublished white paper, January 1997. 3454 http://www.w3.org/pub/WWW/DesignIssues/Metadata.html. 3456 [Bradner, 1997] S. Bradner, "Key words for use in RFCs to 3457 Indicate Requirement Levels." RFC 2119, BCP 14. Harvard 3458 University. March, 1997. 3460 [Bray, Sperberg-McQueen, 1997] T. Bray, C. M. Sperberg-McQueen, 3461 "Extensible Markup Language (XML): Part I. Syntax", WD-xml- 3462 lang.html, http://www.w3.org/pub/WWW/TR/WD-xml-lang.html. 3464 [Connolly et al, 1997] D. Connolly, R. Khare, H.F. Nielsen, "PEP 3465 - an Extension Mechanism for HTTP", Internet draft, work-in- 3466 progress. draft-ietf-http-pep-04.txt, 3467 ftp://ds.internic.net/internet-drafts/draft-ietf-http-pep-04.txt. 3469 [Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H. 3470 Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- 3471 HTTP/1.1." RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997. 3472 ftp://ds.internic.net/rfc/rfc2068.txt 3474 [Lasher, Cohen, 1995] R. Lasher, D. Cohen, "A Format for 3475 Bibliographic Records," RFC 1807. Stanford, Myricom. June, 1995. 3476 ftp://ds.internic.net/rfc/rfc1807.txt 3478 [Maloney, 1996] M. Maloney, "Hypertext Links in HTML." Internet 3479 draft (expired), work-in-progress, January, 1996. 3481 [MARC, 1994] Network Development and MARC Standards, Office, ed. 3482 1994. "USMARC Format for Bibliographic Data", 1994. Washington, 3483 DC: Cataloging Distribution Service, Library of Congress. 3485 [Miller et al., 1996] J. Miller, T. Krauskopf, P. Resnick, W. 3486 Treese, "PICS Label Distribution Label Syntax and Communication 3487 Protocols" Version 1.1, W3C Recommendation REC-PICS-labels- 3488 961031. http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html. 3490 [Slein et al., 1997] J. A. Slein, F. Vitali, E. J. Whitehead, 3491 Jr., D. Durand, "Requirements for Distributed Authoring and 3492 Versioning on the World Wide Web." Internet-draft, work-in- 3493 progress, draft-ietf-webdav-requirements-04.txt, 3494 ftp://ds.internic.net/internet-drafts/draft-ietf-webdav- 3495 requirements-04.txt. 3497 [WebDAV, 1997] WEBDAV Design Team. "A Proposal for Web Metadata 3498 Operations." Unpublished manuscript. 3499 http://www.ics.uci.edu/~ejw/authoring/proposals/metadata.html 3501 [Weibel et al., 1995] S. Weibel, J. Godby, E. Miller, R. Daniel, 3502 "OCLC/NCSA Metadata Workshop Report." 3503 http://purl.oclc.org/metadata/dublin_core_report. 3505 [Yergeau, 1997] F. Yergeau, "UTF-8, a transformation format of 3506 Unicode and ISO 10646", Internet Draft, work-in-progress, draft- 3507 yergeau-utf8-rev-00.txt, http://www.internic.net/internet- 3508 drafts/draft-yergeau-utf8-rev-00.txt. 3510 12 Authors' Addresses 3512 Y. Y. Goland 3513 Microsoft Corporation 3514 One Microsoft Way 3515 Redmond, WA 98052-6399 3516 Email yarong@microsoft.com 3518 E. J. Whitehead, Jr. 3519 Dept. Of Information and Computer Science 3520 University of California, Irvine 3521 Irvine, CA 92697-3425 3522 Email: ejw@ics.uci.edu 3524 A. Faizi 3525 Netscape 3526 685 East Middlefield Road 3527 Mountain View, CA 94043 3528 Email: asad@netscape.com 3530 S. R Carter 3531 Novell 3532 1555 N. Technology Way 3533 M/S ORM F111 3534 Orem, UT 84097-2399 3535 Email srcarter@novell.com 3537 D. Jensen 3538 Novell 3539 1555 N. Technology Way 3540 M/S ORM F111 3541 Orem, UT 84097-2399 3542 Email dcjensen@novell.com