7Internet Engineering Task Force (IETF) C. Daboo
8Request for Comments: 6578 Apple Inc.
9Category: Standards Track A. Quillaud
14 Collection Synchronization
15 for Web Distributed Authoring and Versioning (WebDAV)
19 This specification defines an extension to Web Distributed Authoring
20 and Versioning (WebDAV) that allows efficient synchronization of the
21 contents of a WebDAV collection.
25 This is an Internet Standards Track document.
27 This document is a product of the Internet Engineering Task Force
28 (IETF). It represents the consensus of the IETF community. It has
29 received public review and has been approved for publication by the
30 Internet Engineering Steering Group (IESG). Further information on
31 Internet Standards is available in Section 2 of RFC 5741.
33 Information about the current status of this document, any errata,
34 and how to provide feedback on it may be obtained at
35 http://www.rfc-editor.org/info/rfc6578.
58Daboo & Quillaud Standards Track [Page 1]
60RFC 6578 WebDAV Sync March 2012
65 Copyright (c) 2012 IETF Trust and the persons identified as the
66 document authors. All rights reserved.
68 This document is subject to BCP 78 and the IETF Trust's Legal
69 Provisions Relating to IETF Documents
70 (http://trustee.ietf.org/license-info) in effect on the date of
71 publication of this document. Please review these documents
72 carefully, as they describe your rights and restrictions with respect
73 to this document. Code Components extracted from this document must
74 include Simplified BSD License text as described in Section 4.e of
75 the Trust Legal Provisions and are provided without warranty as
76 described in the Simplified BSD License.
78 This document may contain material from IETF Documents or IETF
79 Contributions published or made publicly available before November
80 10, 2008. The person(s) controlling the copyright in some of this
81 material may not have granted the IETF Trust the right to allow
82 modifications of such material outside the IETF Standards Process.
83 Without obtaining an adequate license from the person(s) controlling
84 the copyright in such materials, this document may not be modified
85 outside the IETF Standards Process, and derivative works of it may
86 not be created outside the IETF Standards Process, except to format
87 it for publication as an RFC or to translate it into languages other
114Daboo & Quillaud Standards Track [Page 2]
116RFC 6578 WebDAV Sync March 2012
121 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
122 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
123 3. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 5
124 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5
125 3.2. DAV:sync-collection Report . . . . . . . . . . . . . . . . 6
126 3.3. Depth Behavior . . . . . . . . . . . . . . . . . . . . . . 8
127 3.4. Types of Changes Reported on Initial Synchronization . . . 9
128 3.5. Types of Changes Reported on Subsequent
129 Synchronizations . . . . . . . . . . . . . . . . . . . . . 10
130 3.5.1. Changed Member . . . . . . . . . . . . . . . . . . . . 10
131 3.5.2. Removed Member . . . . . . . . . . . . . . . . . . . . 10
132 3.6. Truncation of Results . . . . . . . . . . . . . . . . . . 11
133 3.7. Limiting Results . . . . . . . . . . . . . . . . . . . . . 12
134 3.8. Example: Initial DAV:sync-collection Report . . . . . . . 12
135 3.9. Example: DAV:sync-collection Report with Token . . . . . . 14
136 3.10. Example: Initial DAV:sync-collection Report with
137 Truncation . . . . . . . . . . . . . . . . . . . . . . . . 16
138 3.11. Example: Initial DAV:sync-collection Report with Limit . . 17
139 3.12. Example: DAV:sync-collection Report with Unsupported
140 Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 18
141 3.13. Example: DAV:sync-level Set to Infinite, Initial
142 DAV:sync-collection Report . . . . . . . . . . . . . . . . 19
143 4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 22
144 5. DAV:sync-token Use with If Header . . . . . . . . . . . . . . 22
145 5.1. Example: If Precondition with PUT . . . . . . . . . . . . 22
146 5.2. Example: If Precondition with MKCOL . . . . . . . . . . . 23
147 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 24
148 6.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 24
149 6.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 24
150 6.3. DAV:sync-level XML Element . . . . . . . . . . . . . . . . 24
151 6.4. DAV:multistatus XML Element . . . . . . . . . . . . . . . 25
152 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
153 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25
154 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
155 9.1. Normative References . . . . . . . . . . . . . . . . . . . 25
156 9.2. Informative References . . . . . . . . . . . . . . . . . . 26
157 Appendix A. Backwards-Compatible Handling of Depth . . . . . . . 27
158 Appendix B. Example of a Client Synchronization Approach . . . . 27
170Daboo & Quillaud Standards Track [Page 3]
172RFC 6578 WebDAV Sync March 2012
177 WebDAV [RFC4918] defines the concept of 'collections', which are
178 hierarchical groupings of WebDAV resources on an HTTP [RFC2616]
179 server. Collections can be of arbitrary size and depth (i.e.,
180 collections within collections). WebDAV clients that cache resource
181 content need a way to synchronize that data with the server (i.e.,
182 detect what has changed and update their cache). Currently, this can
183 be done using a WebDAV PROPFIND request on a collection to list all
184 members of a collection along with their DAV:getetag property values,
185 which allows the client to determine which were changed, added, or
186 deleted. However, this does not scale well to large collections, as
187 the XML response to the PROPFIND request will grow with the
190 This specification defines a new WebDAV report that results in the
191 server returning to the client only information about those member
192 URLs that were added or deleted, or whose mapped resources were
193 changed, since a previous execution of the report on the collection.
195 Additionally, a new property is added to collection resources that is
196 used to convey a "synchronization token" that is guaranteed to change
197 when the collection's member URLs or their mapped resources have
2002. Conventions Used in This Document
202 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
203 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
204 document are to be interpreted as described in [RFC2119].
206 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
207 3.2) as a purely notational convention. WebDAV request and response
208 bodies cannot be validated by a DTD due to the specific extensibility
209 rules defined in Section 17 of [RFC4918] and due to the fact that all
210 XML elements defined by this specification use the XML namespace name
211 "DAV:". In particular:
213 1. Element names use the "DAV:" namespace.
215 2. Element ordering is irrelevant unless explicitly stated
218 3. Extension elements (elements not already defined as valid child
219 elements) may be added anywhere, except when explicitly stated
226Daboo & Quillaud Standards Track [Page 4]
228RFC 6578 WebDAV Sync March 2012
231 4. Extension attributes (attributes not already defined as valid for
232 this element) may be added anywhere, except when explicitly
235 When an XML element type in the "DAV:" namespace is referenced in
236 this document outside of the context of an XML fragment, the string
237 "DAV:" will be prefixed to the element type.
239 This document inherits, and sometimes extends, DTD productions from
240 Section 14 of [RFC4918].
2423. WebDAV Synchronization
246 One way to synchronize data between two entities is to use some form
247 of synchronization token. The token defines the state of the data
248 being synchronized at a particular point in time. It can then be
249 used to determine what has changed between one point in time and
252 This specification defines a new WebDAV report that is used to enable
253 client-server collection synchronization based on such a token.
255 In order to synchronize the contents of a collection between a server
256 and client, the server provides the client with a synchronization
257 token each time the synchronization report is executed. That token
258 represents the state of the data being synchronized at that point in
259 time. The client can then present that same token back to the server
260 at some later time, and the server will return only those items that
261 are new, have changed, or were deleted since that token was
262 generated. The server also returns a new token representing the new
263 state at the time the report was run.
265 Typically, the first time a client connects to the server it will
266 need to be informed of the entire state of the collection (i.e., a
267 full list of all member URLs that are currently in the collection).
268 That is done by the client sending an empty token value to the
269 server. This indicates to the server that a full listing is
272 As an alternative, the client might choose to do its first
273 synchronization using some other mechanism on the collection (e.g.,
274 some other form of batch resource information retrieval such as
275 PROPFIND, SEARCH [RFC5323], or specialized REPORTs such as those
276 defined in CalDAV [RFC4791] and CardDAV [RFC6352]) and ask for the
282Daboo & Quillaud Standards Track [Page 5]
284RFC 6578 WebDAV Sync March 2012
287 DAV:sync-token property to be returned. This property (defined in
288 Section 4) contains the same token that can be used later to issue a
289 DAV:sync-collection report.
291 In some cases, a server might only wish to maintain a limited amount
292 of history about changes to a collection. In that situation, it will
293 return an error to the client when the client presents a token that
294 is "out of date". At that point, the client has to fall back to
295 synchronizing the entire collection by re-running the report request
296 using an empty token value.
298 Typically, a client will use the synchronization report to retrieve
299 the list of changes and will follow that with requests to retrieve
300 the content of changed resources. It is possible that additional
301 changes to the collection could occur between the time of the
302 synchronization report and resource content retrieval, which could
303 result in an inconsistent view of the collection. When clients use
304 this method of synchronization, they need to be aware that such
305 additional changes could occur and track them, e.g., by differences
306 between the ETag values returned in the synchronization report and
307 those returned when actually fetching resource content, by using
308 conditional requests as described in Section 5, or by repeating the
309 synchronization process until no changes are returned.
3113.2. DAV:sync-collection Report
313 If the DAV:sync-collection report is implemented by a WebDAV server,
314 then the server MUST list the report in the
315 "DAV:supported-report-set" property on any collection that supports
318 To implement the behavior for this report, a server needs to keep
319 track of changes to any member URLs and their mapped resources in a
320 collection (as defined in Section 3 of [RFC4918]). This includes
321 noting the addition of new member URLs, the changes to the mapped
322 resources of existing member URLs, and the removal of member URLs.
323 The server will track each change and provide a synchronization
324 "token" to the client that describes the state of the server at a
325 specific point in time. This "token" is returned as part of the
326 response to the "sync-collection" report. Clients include the last
327 token they got from the server in the next "sync-collection" report
328 that they execute, and the server provides the changes from the
329 previous state (represented by the token) to the current state
330 (represented by the new token returned).
332 The synchronization token itself MUST be treated as an "opaque"
333 string by the client, i.e., the actual string data has no specific
334 meaning or syntax. However, the token MUST be a valid URI to allow
338Daboo & Quillaud Standards Track [Page 6]
340RFC 6578 WebDAV Sync March 2012
343 its use in an If precondition request header (see Section 5). For
344 example, a simple implementation of such a token could be a numeric
345 counter that counts each change as it occurs and relates that change
346 to the specific object that changed. The numeric value could be
347 appended to a "base" URI to form the valid sync-token.
351 The request-URI MUST identify a collection. The request body MUST
352 be a DAV:sync-collection XML element (see Section 6.1), which MUST
353 contain one DAV:sync-token XML element, one DAV:sync-level
354 element, and one DAV:prop XML element, and MAY contain a DAV:limit
357 This report is only defined when the Depth header has value "0";
358 other values result in a 400 (Bad Request) error response. Note
359 that [RFC3253], Section 3.6, states that if the Depth header is
360 not present, it defaults to a value of "0".
362 The response body for a successful request MUST be a
363 DAV:multistatus XML element, which MUST contain one DAV:sync-token
364 element in addition to one DAV:response element for each member
365 URL that was added, has had its mapped resource changed, or was
366 deleted since the last synchronization operation as specified by
367 the DAV:sync-token provided in the request. A given member URL
368 MUST appear only once in the response. In the case where multiple
369 member URLs of the request-URI are mapped to the same resource, if
370 the resource is changed, each member URL MUST be returned in the
373 The content of each DAV:response element differs depending on how
374 the member was altered:
376 For members that have changed (i.e., are new or have had their
377 mapped resource modified), the DAV:response MUST contain at
378 least one DAV:propstat element and MUST NOT contain any
381 For members that have been removed, the DAV:response MUST
382 contain one DAV:status with a value set to '404 Not Found' and
383 MUST NOT contain any DAV:propstat element.
385 For members that are collections and are unable to support the
386 DAV:sync-collection report, the DAV:response MUST contain one
387 DAV:status with a value set to '403 Forbidden', a DAV:error
388 containing DAV:supported-report or DAV:sync-traversal-supported
389 (see Section 3.3 for which is appropriate) and MUST NOT contain
390 any DAV:propstat element.
394Daboo & Quillaud Standards Track [Page 7]
396RFC 6578 WebDAV Sync March 2012
399 The conditions under which each type of change can occur are
400 further described in Section 3.5.
404 (DAV:valid-sync-token): The DAV:sync-token element value MUST be a
405 valid token previously returned by the server for the collection
406 targeted by the request-URI. Servers might need to invalidate
407 tokens previously returned to clients. Doing so will cause the
408 clients to fall back to doing full synchronization using the
409 report, though that will not require clients to download resources
410 that are already cached and have not changed. Even so, servers
411 MUST limit themselves to invalidating tokens only when absolutely
412 necessary. Specific reasons include:
414 * Servers might be unable to maintain all of the change data for
415 a collection due to storage or performance reasons, e.g.,
416 servers might only be able to maintain up to 3 weeks worth of
417 changes to a collection, or only up to 10,000 total changes, or
418 not wish to maintain changes for a deleted collection.
420 * Change to server implementation: servers might be upgraded to a
421 new implementation that tracks the history in a different
422 manner, and thus previous synchronization history is no longer
427 (DAV:number-of-matches-within-limits): The number of changes
428 reported in the response must fall within the client-specified
429 limit. This condition might be triggered if a client requests a
430 limit on the number of responses (as per Section 3.7), but the
431 server is unable to truncate the result set at or below that
436 Servers MUST support only Depth:0 behavior with the
437 DAV:sync-collection report, i.e., the report targets only the
438 collection being synchronized in a single request. However, clients
439 do need to "scope" the synchronization to different levels within
440 that collection -- specifically, immediate children (level "1") and
441 all children at any depth (level "infinite"). To specify which level
442 to use, clients MUST include a DAV:sync-level XML element in the
450Daboo & Quillaud Standards Track [Page 8]
452RFC 6578 WebDAV Sync March 2012
455 o When the client specifies the DAV:sync-level XML element with a
456 value of "1", only appropriate internal member URLs (immediate
457 children) of the collection specified as the request-URI are
460 o When the client specifies the DAV:sync-level XML element with a
461 value of "infinite", all appropriate member URLs of the collection
462 specified as the request-URI are reported, provided child
463 collections themselves also support the DAV:sync-collection
466 o DAV:sync-token values returned by the server are not specific to
467 the value of the DAV:sync-level XML element used in the request.
468 As such, clients MAY use a DAV:sync-token value from a request
469 with one DAV:sync-level XML element value for a similar request
470 with a different DAV:sync-level XML element value; however, the
471 utility of this is limited.
473 Note that when a server supports a DAV:sync-level XML element with a
474 value of "infinite", it might not be possible to synchronize some
475 child collections within the collection targeted by the report. When
476 this occurs, the server MUST include a DAV:response element for the
477 child collection with status 403 (Forbidden). The 403 response MUST
478 be sent once, when the collection is first reported to the client.
479 In addition, the server MUST include a DAV:error element in the
480 DAV:response element, indicating one of two possible causes for this:
482 The DAV:sync-collection report is not supported at all on the
483 child collection. The DAV:error element MUST contain the
484 DAV:supported-report element.
486 The server is unwilling to report results for the child collection
487 when a DAV:sync-collection report with the DAV:sync-level XML
488 element set to "infinite" is executed on a parent resource. This
489 might happen when, for example, the synchronization state of the
490 collection resource is controlled by another subsystem. In such
491 cases clients can perform the DAV:sync-collection report directly
492 on the child collection instead. The DAV:error element MUST
493 contain the DAV:sync-traversal-supported element.
4953.4. Types of Changes Reported on Initial Synchronization
497 When the DAV:sync-collection request contains an empty DAV:sync-token
498 element, the server MUST return all member URLs of the collection
499 (taking account of the DAV:sync-level XML element value as per
500 Section 3.3, and optional truncation of the result set as per
501 Section 3.6) and it MUST NOT return any removed member URLs. All
502 types of member (collection or non-collection) MUST be reported.
506Daboo & Quillaud Standards Track [Page 9]
508RFC 6578 WebDAV Sync March 2012
5113.5. Types of Changes Reported on Subsequent Synchronizations
513 When the DAV:sync-collection request contains a valid value for the
514 DAV:sync-token element, two types of member URL state changes can be
515 returned (changed or removed). This section defines what triggers
516 each of these to be returned. It also clarifies the case where a
517 member URL might have undergone multiple changes between two
518 synchronization report requests. In all cases, the DAV:sync-level
519 XML element value (as per Section 3.3) and optional truncation of the
520 result set (as per Section 3.6) are taken into account by the server.
524 A member URL MUST be reported as changed if it has been newly mapped
525 as a member of the target collection since the request sync-token was
526 generated (e.g., when a new resource has been created as a child of
527 the collection). For example, this includes member URLs that have
528 been newly mapped as the result of a COPY, MOVE, BIND [RFC5842], or
529 REBIND [RFC5842] request. All types of member URL (collection or
530 non-collection) MUST be reported.
532 In the case where a mapping between a member URL and the target
533 collection was removed, then a new mapping with the same URI was
534 created, the member URL MUST be reported as changed and MUST NOT be
537 A member URL MUST be reported as changed if its mapped resource's
538 entity tag value (defined in Section 3.11 of [RFC2616]) has changed
539 since the request sync-token was generated.
541 A member URL MAY be reported as changed if the user issuing the
542 request was granted access to this member URL, due to access control
545 Collection member URLs MUST be returned as changed if they are mapped
546 to an underlying resource (i.e., entity body) and if the entity tag
547 associated with that resource changes. There is no guarantee that
548 changes to members of a collection will result in a change in any
549 entity tag of that collection, so clients cannot rely on a series of
550 reports using the DAV:sync-level XML element value set to "1" at
551 multiple levels to track all changes within a collection. Instead, a
552 DAV:sync-level XML element with a value of "infinite" has to be used.
556 A member MUST be reported as removed if its mapping under the target
557 collection has been removed since the request sync-token was
558 generated, and it has not been remapped since it was removed. For
562Daboo & Quillaud Standards Track [Page 10]
564RFC 6578 WebDAV Sync March 2012
567 example, this includes members that have been unmapped as the result
568 of a MOVE, UNBIND [RFC5842], or REBIND [RFC5842] operation. This
569 also includes collection members that have been removed, including
570 ones that themselves do not support the DAV:sync-collection report.
572 If a member was added (and its mapped resource possibly modified),
573 then removed between two synchronization report requests, it MUST be
574 reported as removed. This ensures that a client that adds a member
575 is informed of the removal of the member, if the removal occurs
576 before the client has had a chance to execute a synchronization
579 A member MAY be reported as removed if the user issuing the request
580 no longer has access to this member, due to access control changes.
582 For a report with the DAV:sync-level XML element value set to
583 "infinite", where a collection is removed, the server MUST NOT report
584 the removal of any members of the removed collection. Clients MUST
585 assume that if a collection is reported as being removed, then all
586 members of that collection have also been removed.
5883.6. Truncation of Results
590 A server MAY limit the number of member URLs in a response, for
591 example, to limit the amount of work expended in processing a
592 request, or as the result of an explicit limit set by the client. If
593 the result set is truncated, the response MUST use status code 207
594 (Multi-Status), return a DAV:multistatus response body, and indicate
595 a status of 507 (Insufficient Storage) for the request-URI. That
596 DAV:response element SHOULD include a DAV:error element with the
597 DAV:number-of-matches-within-limits precondition, as defined in
598 [RFC3744] (Section 9.2). DAV:response elements for all the changes
599 being reported are also included.
601 When truncation occurs, the DAV:sync-token value returned in the
602 response MUST represent the correct state for the partial set of
603 changes returned. That allows the client to use the returned
604 DAV:sync-token to fetch the next set of changes. In this way, the
605 client can effectively "page" through the entire set of changes in a
608 Clients MUST handle the 507 status on the request-URI in the response
611 For example, consider a server that records changes using a strictly
612 increasing integer to represent a "revision number" and uses that
613 quantity as the DAV:sync-token value (appropriately encoded as a
614 URI). Assume the last DAV:sync-token used by the client was
618Daboo & Quillaud Standards Track [Page 11]
620RFC 6578 WebDAV Sync March 2012
623 "http://example.com/sync/10", and since then 15 additional changes to
624 different resources have occurred. If the client executes a
625 DAV:sync-collection request with a DAV:sync-token of
626 "http://example.com/sync/10", without a limit, the server would
627 return 15 DAV:response elements and a DAV:sync-token with value
628 "http://example.com/sync/25". But if the server chooses to limit
629 responses to at most 10 changes, then it would return only 10
630 DAV:response elements and a DAV:sync-token with value
631 "http://example.com/sync/20", together with an additional
632 DAV:response element for the request-URI with a status code of 507.
633 Subsequently, the client can reissue the request with the
634 DAV:sync-token value returned from the server and fetch the remaining
639 A client can limit the number of results returned by the server
640 through use of the DAV:limit element ([RFC5323], Section 5.17) in the
641 request body. This is useful when clients have limited space or
642 bandwidth for the results. If a server is unable to truncate the
643 result at or below the requested number, then it MUST fail the
644 request with a DAV:number-of-matches-within-limits postcondition
645 error. When the results can be correctly limited by the server, the
646 server MUST follow the rules above for indicating a result set
647 truncation to the client.
6493.8. Example: Initial DAV:sync-collection Report
651 In this example, the client is making its first synchronization
652 request to the server, so the DAV:sync-token element in the request
653 is empty. It also asks for the DAV:getetag property and for a
654 proprietary property. The server responds with the items currently
655 in the targeted collection. The current synchronization token is
661 REPORT /home/cyrusdaboo/ HTTP/1.1
662 Host: webdav.example.com
664 Content-Type: text/xml; charset="utf-8"
667 <?xml version="1.0" encoding="utf-8" ?>
668 <D:sync-collection xmlns:D="DAV:">
670 <D:sync-level>1</D:sync-level>
674Daboo & Quillaud Standards Track [Page 12]
676RFC 6578 WebDAV Sync March 2012
679 <D:prop xmlns:R="urn:ns.example.com:boxschema">
689 HTTP/1.1 207 Multi-Status
690 Content-Type: text/xml; charset="utf-8"
693 <?xml version="1.0" encoding="utf-8" ?>
694 <D:multistatus xmlns:D="DAV:">
697 >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
700 <D:getetag>"00001-abcd1"</D:getetag>
701 <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
702 <R:BoxType>Box type A</R:BoxType>
705 <D:status>HTTP/1.1 200 OK</D:status>
710 >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
713 <D:getetag>"00002-abcd1"</D:getetag>
715 <D:status>HTTP/1.1 200 OK</D:status>
719 <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
721 <D:status>HTTP/1.1 404 Not Found</D:status>
726 >http://webdav.example.com/home/cyrusdaboo/calendar.ics</D:href>
730Daboo & Quillaud Standards Track [Page 13]
732RFC 6578 WebDAV Sync March 2012
737 <D:getetag>"00003-abcd1"</D:getetag>
739 <D:status>HTTP/1.1 200 OK</D:status>
743 <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
745 <D:status>HTTP/1.1 404 Not Found</D:status>
748 <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
7513.9. Example: DAV:sync-collection Report with Token
753 In this example, the client is making a synchronization request to
754 the server and is using the DAV:sync-token element returned from the
755 last report it ran on this collection. The server responds, listing
756 the items that have been added, changed, or removed. The (new)
757 current synchronization token is also returned.
762 REPORT /home/cyrusdaboo/ HTTP/1.1
763 Host: webdav.example.com
764 Content-Type: text/xml; charset="utf-8"
767 <?xml version="1.0" encoding="utf-8" ?>
768 <D:sync-collection xmlns:D="DAV:">
769 <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
770 <D:sync-level>1</D:sync-level>
771 <D:prop xmlns:R="urn:ns.example.com:boxschema">
786Daboo & Quillaud Standards Track [Page 14]
788RFC 6578 WebDAV Sync March 2012
794 HTTP/1.1 207 Multi-Status
795 Content-Type: text/xml; charset="utf-8"
798 <?xml version="1.0" encoding="utf-8" ?>
799 <D:multistatus xmlns:D="DAV:">
802 >http://webdav.example.com/home/cyrusdaboo/file.xml</D:href>
805 <D:getetag>"00004-abcd1"</D:getetag>
807 <D:status>HTTP/1.1 200 OK</D:status>
811 <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
813 <D:status>HTTP/1.1 404 Not Found</D:status>
818 >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
821 <D:getetag>"00002-abcd2"</D:getetag>
823 <D:status>HTTP/1.1 200 OK</D:status>
827 <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
829 <D:status>HTTP/1.1 404 Not Found</D:status>
834 >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
835 <D:status>HTTP/1.1 404 Not Found</D:status>
837 <D:sync-token>http://example.com/ns/sync/1238</D:sync-token>
842Daboo & Quillaud Standards Track [Page 15]
844RFC 6578 WebDAV Sync March 2012
8473.10. Example: Initial DAV:sync-collection Report with Truncation
849 In this example, the client is making its first synchronization
850 request to the server, so the DAV:sync-token element in the request
851 is empty. It also asks for the DAV:getetag property. The server
852 responds with the items currently in the targeted collection but
853 truncated at two items. The synchronization token for the truncated
854 result set is returned.
859 REPORT /home/cyrusdaboo/ HTTP/1.1
860 Host: webdav.example.com
862 Content-Type: text/xml; charset="utf-8"
865 <?xml version="1.0" encoding="utf-8" ?>
866 <D:sync-collection xmlns:D="DAV:">
868 <D:sync-level>1</D:sync-level>
878 HTTP/1.1 207 Multi-Status
879 Content-Type: text/xml; charset="utf-8"
882 <?xml version="1.0" encoding="utf-8" ?>
883 <D:multistatus xmlns:D="DAV:">
886 >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
889 <D:getetag>"00001-abcd1"</D:getetag>
891 <D:status>HTTP/1.1 200 OK</D:status>
898Daboo & Quillaud Standards Track [Page 16]
900RFC 6578 WebDAV Sync March 2012
904 >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
907 <D:getetag>"00002-abcd1"</D:getetag>
909 <D:status>HTTP/1.1 200 OK</D:status>
914 >http://webdav.example.com/home/cyrusdaboo/</D:href>
915 <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
916 <D:error><D:number-of-matches-within-limits/></D:error>
918 <D:sync-token>http://example.com/ns/sync/1233</D:sync-token>
9213.11. Example: Initial DAV:sync-collection Report with Limit
923 In this example, the client is making its first synchronization
924 request to the server, so the DAV:sync-token element in the request
925 is empty. It requests a limit of 1 for the responses returned by the
926 server. It also asks for the DAV:getetag property. The server
927 responds with the items currently in the targeted collection, but
928 truncated at one item. The synchronization token for the truncated
929 result set is returned.
934 REPORT /home/cyrusdaboo/ HTTP/1.1
935 Host: webdav.example.com
937 Content-Type: text/xml; charset="utf-8"
940 <?xml version="1.0" encoding="utf-8" ?>
941 <D:sync-collection xmlns:D="DAV:">
943 <D:sync-level>1</D:sync-level>
945 <D:nresults>1</D:nresults>
954Daboo & Quillaud Standards Track [Page 17]
956RFC 6578 WebDAV Sync March 2012
962 HTTP/1.1 207 Multi-Status
963 Content-Type: text/xml; charset="utf-8"
966 <?xml version="1.0" encoding="utf-8" ?>
967 <D:multistatus xmlns:D="DAV:">
970 >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
973 <D:getetag>"00001-abcd1"</D:getetag>
975 <D:status>HTTP/1.1 200 OK</D:status>
980 >http://webdav.example.com/home/cyrusdaboo/</D:href>
981 <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
982 <D:error><D:number-of-matches-within-limits/></D:error>
984 <D:sync-token>http://example.com/ns/sync/1232</D:sync-token>
9873.12. Example: DAV:sync-collection Report with Unsupported Limit
989 In this example, the client is making a synchronization request to
990 the server with a valid DAV:sync-token element value. It requests a
991 limit of 100 for the responses returned by the server. It also asks
992 for the DAV:getetag property. The server is unable to limit the
993 results to the maximum specified by the client, so it responds with a
994 507 status code and appropriate postcondition error code.
999 REPORT /home/cyrusdaboo/ HTTP/1.1
1000 Host: webdav.example.com
1002 Content-Type: text/xml; charset="utf-8"
1003 Content-Length: xxxx
1010Daboo & Quillaud Standards Track [Page 18]
1012RFC 6578 WebDAV Sync March 2012
1015 <?xml version="1.0" encoding="utf-8" ?>
1016 <D:sync-collection xmlns:D="DAV:">
1017 <D:sync-token>http://example.com/ns/sync/1232</D:sync-token>
1018 <D:sync-level>1</D:sync-level>
1020 <D:nresults>100</D:nresults>
1025 </D:sync-collection>
1031 HTTP/1.1 507 Insufficient Storage
1032 Content-Type: text/xml; charset="utf-8"
1033 Content-Length: xxxx
1035 <?xml version="1.0" encoding="utf-8" ?>
1036 <D:error xmlns:D="DAV:">
1037 <D:number-of-matches-within-limits/>
10403.13. Example: DAV:sync-level Set to Infinite, Initial
1041 DAV:sync-collection Report
1043 In this example, the client is making its first synchronization
1044 request to the server, so the DAV:sync-token element in the request
1045 is empty, and it is using DAV:sync-level set to "infinite". It also
1046 asks for the DAV:getetag property and for a proprietary property.
1047 The server responds with the items currently in the targeted
1048 collection. The current synchronization token is also returned.
1050 The collection /home/cyrusdaboo/collection1/ exists and has one child
1051 resource that is also reported. The collection /home/cyrusdaboo/
1052 collection2/ exists but has no child resources. The collection
1053 /home/cyrusdaboo/shared/ is returned with a 403 status indicating
1054 that a collection exists, but it is unable to report on changes
1055 within it in the scope of the current DAV:sync-level "infinite"
1056 report. Instead, the client can try a DAV:sync-collection report
1057 directly on the collection URI.
1066Daboo & Quillaud Standards Track [Page 19]
1068RFC 6578 WebDAV Sync March 2012
1074 REPORT /home/cyrusdaboo/ HTTP/1.1
1075 Host: webdav.example.com
1077 Content-Type: text/xml; charset="utf-8"
1078 Content-Length: xxxx
1080 <?xml version="1.0" encoding="utf-8" ?>
1081 <D:sync-collection xmlns:D="DAV:">
1083 <D:sync-level>infinite</D:sync-level>
1084 <D:prop xmlns:R="urn:ns.example.com:boxschema">
1088 </D:sync-collection>
1094 HTTP/1.1 207 Multi-Status
1095 Content-Type: text/xml; charset="utf-8"
1096 Content-Length: xxxx
1098 <?xml version="1.0" encoding="utf-8" ?>
1099 <D:multistatus xmlns:D="DAV:">
1101 <D:href>/home/cyrusdaboo/collection1/</D:href>
1104 <D:getetag>"00001-abcd1"</D:getetag>
1105 <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
1106 <R:BoxType>Box type A</R:BoxType>
1109 <D:status>HTTP/1.1 200 OK</D:status>
1113 <D:href>/home/cyrusdaboo/collection1/test.doc</D:href>
1116 <D:getetag>"00001-abcd1"</D:getetag>
1117 <R:bigbox xmlns:R="urn:ns.example.com:boxschema">
1118 <R:BoxType>Box type A</R:BoxType>
1122Daboo & Quillaud Standards Track [Page 20]
1124RFC 6578 WebDAV Sync March 2012
1129 <D:status>HTTP/1.1 200 OK</D:status>
1133 <D:href>/home/cyrusdaboo/collection2/</D:href>
1138 <D:status>HTTP/1.1 404 Not Found</D:status>
1142 <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
1144 <D:status>HTTP/1.1 404 Not Found</D:status>
1148 <D:href>/home/cyrusdaboo/calendar.ics</D:href>
1151 <D:getetag>"00003-abcd1"</D:getetag>
1153 <D:status>HTTP/1.1 200 OK</D:status>
1157 <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
1159 <D:status>HTTP/1.1 404 Not Found</D:status>
1163 <D:href>/home/cyrusdaboo/shared/</D:href>
1164 <D:status>HTTP/1.1 403 Forbidden</D:status>
1165 <D:error><D:sync-traversal-supported/></D:error>
1167 <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
1178Daboo & Quillaud Standards Track [Page 21]
1180RFC 6578 WebDAV Sync March 2012
11834. DAV:sync-token Property
1189 Purpose: Contains the value of the synchronization token as it would
1190 be returned by a DAV:sync-collection report.
1192 Value: Any valid URI.
1194 Protected: MUST be protected because this value is created and
1195 controlled by the server.
1197 COPY/MOVE behavior: This property value is dependent on the final
1198 state of the destination resource, not the value of the property
1199 on the source resource.
1201 Description: The DAV:sync-token property MUST be defined on all
1202 resources that support the DAV:sync-collection report. It
1203 contains the value of the synchronization token as it would be
1204 returned by a DAV:sync-collection report on that resource at the
1205 same point in time. It SHOULD NOT be returned by a PROPFIND
1206 DAV:allprop request (as defined in Section 14.2 of [RFC4918]).
1210 <!ELEMENT sync-token #PCDATA>
1212 <!-- Text MUST be a valid URI -->
12145. DAV:sync-token Use with If Header
1216 WebDAV provides an If precondition header that allows for "state
1217 tokens" to be used as preconditions on HTTP requests (as defined in
1218 Section 10.4 of [RFC4918]). This specification allows the
1219 DAV:sync-token value to be used as one such token in an If header.
1220 By using this, clients can ensure requests only complete when there
1221 have been no changes to the content of a collection, by virtue of an
1222 unchanged DAV:sync-token value. Servers MUST support use of
1223 DAV:sync-token values in If request headers.
12255.1. Example: If Precondition with PUT
1227 In this example, the client has already used the DAV:sync-collection
1228 report to synchronize the collection /home/cyrusdaboo/collection/.
1229 Now it wants to add a new resource to the collection, but only if
1230 there have been no other changes since the last synchronization.
1234Daboo & Quillaud Standards Track [Page 22]
1236RFC 6578 WebDAV Sync March 2012
1239 Note that because the DAV:sync-token is defined on the collection and
1240 not on the resource targeted by the request, the If header value
1241 needs to use the "Resource_Tag" construct for the header syntax to
1242 correctly identify that the supplied state token refers to the
1243 collection resource.
1248 PUT /home/cyrusdaboo/collection/newresource.txt HTTP/1.1
1249 Host: webdav.example.com
1250 If: </home/cyrusdaboo/collection/>
1251 (<http://example.com/ns/sync/12345>)
1252 Content-Type: text/plain; charset="utf-8"
1253 Content-Length: xxxx
1255 Some content here...
1261 HTTP/1.1 201 Created
12635.2. Example: If Precondition with MKCOL
1265 In this example, the client has already used the DAV:sync-collection
1266 report to synchronize the collection /home/cyrusdaboo/collection/.
1267 Now, it wants to add a new collection to the collection, but only if
1268 there have been no other changes since the last synchronization.
1269 Note that because the DAV:sync-token is defined on the collection and
1270 not on the resource targeted by the request, the If header value
1271 needs to use the "Resource_Tag" construct for the header syntax to
1272 correctly identify that the supplied state token refers to the
1273 collection resource. In this case, the request fails as another
1274 change has occurred to the collection corresponding to the supplied
1280 MKCOL /home/cyrusdaboo/collection/child/ HTTP/1.1
1281 Host: webdav.example.com
1282 If: </home/cyrusdaboo/collection/>
1283 (<http://example.com/ns/sync/12346>)
1290Daboo & Quillaud Standards Track [Page 23]
1292RFC 6578 WebDAV Sync March 2012
1298 HTTP/1.1 412 Precondition Failed
13006. XML Element Definitions
13026.1. DAV:sync-collection XML Element
1304 Name: sync-collection
1308 Purpose: WebDAV report used to synchronize data between client and
1311 Description: See Section 3.
1313 <!ELEMENT sync-collection (sync-token, sync-level, limit?, prop)>
1315 <!-- DAV:limit defined in RFC 5323, Section 5.17 -->
1316 <!-- DAV:prop defined in RFC 4918, Section 14.18 -->
13186.2. DAV:sync-token XML Element
1324 Purpose: The synchronization token provided by the server and
1325 returned by the client.
1327 Description: See Section 3.
1329 <!ELEMENT sync-token CDATA>
1331 <!-- Text MUST be a URI -->
13336.3. DAV:sync-level XML Element
1339 Purpose: Indicates the "scope" of the synchronization report
1342 Description: See Section 3.3.
1346Daboo & Quillaud Standards Track [Page 24]
1348RFC 6578 WebDAV Sync March 2012
1351 <!ELEMENT sync-level CDATA>
1353 <!-- Text MUST be either "1" or "infinite" -->
13556.4. DAV:multistatus XML Element
1361 Purpose: Extends the DAV:multistatus element to include
1362 synchronization details.
1364 Description: See Section 3.
1366 <!ELEMENT multistatus (response*, responsedescription?,
1369 <!-- DAV:multistatus originally defined in RFC 4918, Section 14.16
1370 but overridden here to add the DAV:sync-token element -->
1371 <!-- DAV:response defined in RFC 4918, Section 14.24 -->
1372 <!-- DAV:responsedescription defined in RFC 4918, Section 14.25 -->
13747. Security Considerations
1376 This extension does not introduce any new security concerns beyond
1377 those already described in HTTP and WebDAV.
1381 The following individuals contributed their ideas and support for
1382 writing this specification: Bernard Desruisseaux, Werner Donne, Mike
1383 Douglass, Ciny Joy, Andrew McMillan, Julian Reschke, and Wilfredo
1384 Sanchez. We would like to thank the Calendaring and Scheduling
1385 Consortium for facilitating interoperability testing for early
1386 implementations of this specification.
13909.1. Normative References
1392 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1393 Requirement Levels", BCP 14, RFC 2119, March 1997.
1395 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1396 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
1397 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1402Daboo & Quillaud Standards Track [Page 25]
1404RFC 6578 WebDAV Sync March 2012
1407 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
1408 Whitehead, "Versioning Extensions to WebDAV
1409 (Web Distributed Authoring and Versioning)", RFC 3253,
1412 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
1413 Distributed Authoring and Versioning (WebDAV)
1414 Access Control Protocol", RFC 3744, May 2004.
1416 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
1417 Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
1419 [RFC5323] Reschke, J., Reddy, S., Davis, J., and A. Babich, "Web
1420 Distributed Authoring and Versioning (WebDAV) SEARCH",
1421 RFC 5323, November 2008.
1423 [W3C.REC-xml-20081126]
1424 Sperberg-McQueen, C., Yergeau, F., Paoli, J., Maler, E.,
1425 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
1426 Edition)", World Wide Web Consortium
1427 Recommendation REC-xml-20081126, November 2008,
1428 <http://www.w3.org/TR/2008/REC-xml-20081126>.
14309.2. Informative References
1432 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
1433 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
1436 [RFC5842] Clemm, G., Crawford, J., Reschke, J., and J. Whitehead,
1437 "Binding Extensions to Web Distributed Authoring and
1438 Versioning (WebDAV)", RFC 5842, April 2010.
1440 [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed
1441 Authoring and Versioning (WebDAV)", RFC 6352, August 2011.
1458Daboo & Quillaud Standards Track [Page 26]
1460RFC 6578 WebDAV Sync March 2012
1463Appendix A. Backwards-Compatible Handling of Depth
1465 In prior draft versions of this specification, the Depth request
1466 header was used instead of the DAV:sync-level element to indicate the
1467 "scope" of the synchronization request. Servers that wish to be
1468 backwards compatible with clients conforming to the older
1469 specification should do the following: if a DAV:sync-level element is
1470 not present in the request body, use the Depth header value as the
1471 equivalent value for the missing DAV:sync-level element.
1473Appendix B. Example of a Client Synchronization Approach
1475 This appendix gives an example of how a client might accomplish
1476 collection synchronization using the WebDAV sync report defined in
1477 this specification. Note that this is provided purely as an example,
1478 and is not meant to be treated as a normative "algorithm" for client
1481 This example assumes a WebDAV client interacting with a WebDAV server
1482 supporting the sync report. The client keeps a local cache of
1483 resources in a targeted collection, "/collection/". Local changes
1484 are assumed to not occur. The client is only tracking changes to the
1485 immediate children of the collection resource.
1489 The client starts out with an empty local cache.
1491 The client starts out with no DAV:sync-token stored for
1495 ** Initial Synchronization **
1497 The client issues a sync report request to the server with an
1498 empty DAV:sync-token element, and DAV:sync-level set to "1". The
1499 request asks for the server to return the DAV:getetag WebDAV
1500 property for each resource it reports.
1514Daboo & Quillaud Standards Track [Page 27]
1516RFC 6578 WebDAV Sync March 2012
1519 The server returns a response containing the list of current
1520 resources (with their associated DAV:getetag properties) as well
1521 as a new DAV:sync-token value.
1523 The client associates the new DAV:sync-token value with the
1526 For each reported resource, the client creates a set of (resource
1527 path, DAV:getetag) tuples.
1529 For each tuple, the client issues an HTTP GET request to the
1530 server to retrieve its content, and updates the (resource path,
1531 DAV:getetag) entry in its local cache for that resource with the
1532 ETag response header value returned in the GET request.
1535 ** Routine Synchronization **
1537 The client issues a sync report request to the server with the
1538 DAV:sync-token set to the current cached value from the last sync,
1539 and DAV:sync-level set to "1". The request asks for the server to
1540 return the DAV:getetag WebDAV property for each resource it
1543 The server returns a response containing the list of changes as
1544 well as a new DAV:sync-token value.
1546 The client associates the new DAV:sync-token value with the
1549 * Process Removed Resources *
1551 For each resource reported with a 404 response status, the client
1552 removes the corresponding resource from its local cache.
1554 * Process Resources *
1556 For each remaining reported resource, the client creates a new set
1557 of (resource path, DAV:getetag) tuples.
1559 The client then determines which resources are in the new set but
1560 not in the current cache, and which resources are in the new set
1561 and the current cache but have a different DAV:getetag value. For
1562 each of those, the client issues an HTTP GET request to the server
1563 to retrieve the resource content, and updates the (resource path,
1564 DAV:getetag) entry in its local cache for that resource with the
1565 ETag response header value returned in the GET request.
1570Daboo & Quillaud Standards Track [Page 28]
1572RFC 6578 WebDAV Sync March 2012
1583 EMail: cyrus@daboo.name
1584 URI: http://www.apple.com/
1589 180, Avenue de l'Europe
1590 Saint Ismier cedex 38334
1593 EMail: arnaud.quillaud@oracle.com
1594 URI: http://www.oracle.com/
1626Daboo & Quillaud Standards Track [Page 29]