idnits 2.17.1 draft-pot-webdav-notifications-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 27, 2016) is 2859 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Pot 3 Internet-Draft fruux GmbH 4 Expires: December 29, 2016 C. Daboo 5 Apple Inc. 6 June 27, 2016 8 WebDAV: User Notifications 9 draft-pot-webdav-notifications-03 11 Abstract 13 This specification defines an extension to WebDAV that allows the 14 server to provide notifications to users. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on December 29, 2016. 33 Copyright Notice 35 Copyright (c) 2016 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Conventions Used in This Document . . . . . . . . . . . . . . 2 52 3. Requirements Overview . . . . . . . . . . . . . . . . . . . . 3 53 4. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4.1. Mime type . . . . . . . . . . . . . . . . . . . . . . . . 4 55 4.2. Additional Principal Properties . . . . . . . . . . . . . 4 56 4.2.1. DAV:notification-URL Property . . . . . . . . . . . . 4 57 4.3. Properties on Notification Resources . . . . . . . . . . 5 58 4.3.1. DAV:notificationtype Property . . . . . . . . . . . . 5 59 4.4. XML Element Definitions . . . . . . . . . . . . . . . . . 6 60 4.4.1. DAV:notifications . . . . . . . . . . . . . . . . . . 6 61 4.4.2. DAV:notification . . . . . . . . . . . . . . . . . . 6 62 4.4.3. DAV:dtstamp . . . . . . . . . . . . . . . . . . . . . 6 63 5. Notification Definitions . . . . . . . . . . . . . . . . . . 7 64 5.1. System Status Notification . . . . . . . . . . . . . . . 7 65 5.1.1. DAV:systemstatus Element Definition . . . . . . . . . 7 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 67 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 68 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 71 9.2. Informative References . . . . . . . . . . . . . . . . . 10 72 Appendix A. Backwards-compatibility with earlier drafts . . . . 10 73 Appendix B. Change History (to be removed prior to publication 74 as an RFC . . . . . . . . . . . . . . . . . . . . . 11 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 77 1. Introduction 79 It is often useful for servers to communicate arbitrary information 80 to the end-users of a WebDAV system, such as a system status, message 81 of the day or to notify users of changes that were made to shared 82 resources by other users. 84 This specification defines a generic "notification" mechanism that 85 allows a server to do that. Whilst primarily aimed at CalDAV 86 [RFC4791] and CardDAV [RFC6352] this mechanism has been designed to 87 be adaptable to other applications of WebDAV [RFC4918]. 89 2. Conventions Used in This Document 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 93 document are to be interpreted as described in [RFC2119]. 95 When XML element types in the namespace "DAV:" is referenced in this 96 document outside of the context of an XML fragment, the string "DAV:" 97 will be prefixed to the element type name. 99 The DTD samples used in this document are for illustrative purposes 100 only. All XML documents in this document follow the conventions and 101 restrictions described in [RFC4918] section 17. 103 3. Requirements Overview 105 To add support for WebDAV notifications, a server MUST at least have 106 support for WebDAV Class 3 [RFC4918]. 108 WebDAV notifications also defines new properties on principal 109 resources (RFC3744 [RFC3744]), which is defined in Section 4.2.1. 111 4. Notifications 113 When this feature is available, a DAV:notification-URL 114 (Section 4.2.1) property appears on principal resources for those 115 principals who are able to receive notifications. That property 116 specifies a single DAV:href element whose content refers to a WebDAV 117 collection resource. Notification "messages" are deposited into this 118 collection and can be retrieved by clients and acted on accordingly. 120 The notification collection referenced by the DAV:notification-URL 121 (Section 4.2.1) property MUST have a DAV:resourcetype property with 122 DAV:collection and DAV:notifications (Section 4.4.1) child elements. 124 Notification "messages" are XML documents stored as resources in the 125 notification collection. Each XML document contains a 126 DAV:notification (Section 4.4.2) element as its root. The root 127 element contains a DAV:dtstamp element, and one additional element 128 which represents the type of notification being conveyed in the 129 message. That child element will typically contain additional 130 content that describes the notification. 132 Each notification resource has a DAV:notificationtype (Section 4.3.1) 133 property which contains as its single child element an empty element 134 that matches the child element of the notification resource XML 135 document root. Any attributes on the child element in the XML 136 document are also present in the property child element. 138 Notifications are automatically generated by the server with an 139 appropriate resource stored in the notifications collection of the 140 user to whom the notification is targeted. Clients SHOULD monitor 141 the notification collection looking for new notification resources. 142 When doing so, clients SHOULD look at the DAV:notificationtype 143 (Section 4.3.1) property to ensure that the notification is of a type 144 that the client can handle. Once a client has handled the 145 notification in whatever way is appropriate it SHOULD delete the 146 notification resource. Clients SHOULD remove notifications being 147 displayed to a user when the notification resource is removed from 148 the notification collection, to enable the user to dismiss a 149 notification on one device and have it automatically removed from 150 others. Clients MUST ignore all notifications for types they do not 151 recognize. Servers MAY delete notification resources on their own if 152 they determine that the notifications are no longer relevant or 153 valid. Servers MAY coalesce notifications as appropriate. 155 Servers MUST prevent clients from adding resources in the 156 notification collection. 158 4.1. Mime type 160 The "application/davnotification+xml" MIME media type MUST be used 161 for transfer of WebDAV notifications. 163 This is an example of a Content-Type header: 165 Content-Type: application/davnotification+xml 167 HTTP GET requests that expect to receive a WebDAV notification 168 resource, SHOULD include an "Accept" header that includes 169 "application/davnotification+xml". 171 Requests that do not include this header, SHOULD be rejected with a 172 HTTP 406 status code. 174 4.2. Additional Principal Properties 176 This section defines new properties for WebDAV principal resources as 177 defined in RFC3744 [RFC3744]. These properties are likely to be 178 protected but the server MAY allow them to be written by appropriate 179 users. 181 4.2.1. DAV:notification-URL Property 183 Name: notification-URL 185 Namespace: DAV: 187 Purpose: Identify the URL of the notification collection owned by 188 the associated principal resource. 190 Protected: This property SHOULD be protected. 192 PROPFIND behavior: This property SHOULD NOT be returned by a 193 PROPFIND allprop request (as defined in Section 14.2 of 194 [RFC4918]). 196 COPY/MOVE behavior: This property value SHOULD be preserved in COPY 197 and MOVE operations. 199 Description: This property is needed for a client to determine where 200 the notification collection of the current user is located so that 201 processing of notification messages can occur. If not present, 202 then the associated principal is not enabled for notification 203 messages on the server. 205 Definition: 207 209 4.3. Properties on Notification Resources 211 The following new WebDAV properties are defined for notification 212 resources. 214 4.3.1. DAV:notificationtype Property 216 Name: notificationtype 218 Namespace: DAV: 220 Purpose: Identify the type of notification of the corresponding 221 resource. 223 Protected: This property MUST be protected. 225 PROPFIND behavior: This property SHOULD NOT be returned by a 226 PROPFIND allprop request (as defined in Section 14.2 of 227 [RFC4918]). 229 COPY/MOVE behavior: This property value MUST be preserved in COPY 230 and MOVE operations. 232 Description: This property allows a client, via a PROPFIND Depth:1 233 request, to quickly find notification messages that the client can 234 handle in a notification collection. The single child element is 235 the notification resource root element's child defining the 236 notification itself. This element MUST be empty, though any 237 attributes on the element in the notification resource MUST be 238 present in the property element. 240 Definition: 242 243 246 4.4. XML Element Definitions 248 4.4.1. DAV:notifications 250 Name: notifications 252 Namespace: DAV: 254 Purpose: Indicates a notification collection. 256 Description: This XML element is used in a DAV:resourcetype element 257 to indicate that the corresponding resource is a notification 258 collection. 260 Definition: 262 264 4.4.2. DAV:notification 266 Name: notification 268 Namespace: DAV: 270 Purpose: Notification message root element. 272 Description: The root element used in notification resources. 274 Definition: 276 277 280 4.4.3. DAV:dtstamp 282 Name: dtstamp 284 Namespace: DAV: 286 Purpose: Date-time stamp. 288 Description: DAV:dtstamp is an element whose content MUST conform to 289 the "date-time" production in [RFC3339]. In addition, an 290 uppercase "T" character MUST be used to separate date and time, 291 and an uppercase "Z" character MUST be present. 293 Definition: 295 296 298 5. Notification Definitions 300 This section defines a set of common notification types. 302 5.1. System Status Notification 304 The system status notification is used to convey an URI and/or 305 textual description to the user. The assumption is that the URI 306 points to a webpage where the current system status is described in 307 detail, with the provided description being a summary of that. A 308 "type" attribute on the element is used to indicate the importance of 309 the current status notification, and has the values "low", "medium" 310 and "high", representing the increasing level of importance of the 311 message respectively. 313 Servers might have knowledge of an agent's language preferences, in 314 which case it MAY localise the DAV:description value as appropriate 315 based on the calendar user accessing the notification, but if it 316 does, it SHOULD include an xml:lang attribute on the DAV:description 317 element to indicate what language is being used. 319 5.1.1. DAV:systemstatus Element Definition 321 Name: systemstatus 323 Namespace: DAV: 325 Purpose: Indicates a system status notification. 327 Description: This XML element is used in a DAV:notification element 328 to describe a system status notification. 330 Definition: 332 333 334 335 Example: This is an example of the body of a notification resource 336 for an emergency system outage: 338 339 340 2011-12-09T06:12:53Z 341 342 http://example.com/emergency_shutdown.html 343 344 Emergency shutdown now 345 346 347 349 Example: This is an example of the WebDAV property on the example 350 notification resource above: 352 353 354 355 357 6. Security Considerations 359 TBD: More? 361 7. IANA Considerations 363 This document defines a MIME media type for use of WebDAV 364 notifications in an XML format. This media type SHOULD be used for 365 the transfer of WebDAV notifications. 367 Type name: application 369 Subtype name: davnotification+xml 371 Required parameters: none 373 Optional parameters: none 375 Encoding considerations: Identical to those of "application/xml" as 376 described in RFC7303 [RFC7303]. 378 Security considerations: See Section 6. 380 Interoperability considerations: There are no known interoperability 381 issues. 383 Published specification: This specification. 385 Applications that use this media type: No known applications 386 currently use this media type. 388 Fragment identifier considerations: N/A. 390 Additional information 392 Deprecated alias names for this type N/A. 394 Magic number(s) N/A. 396 File extension(s) xml 398 Macintosh file type code(s) TEXT 400 Person & email address to contact for further information: 401 me@evertpot.com 403 Intended usage COMMON 405 Restrictions on usage There are no restrictions on where this media 407 Author See the "Authors' Addresses" section of this document. 409 Change Controller IETF 411 8. Acknowledgments 413 The authors would like to thank the members of the Calendaring and 414 Scheduling Consortium's SharingTechnical Committee. In particular, 415 the following individuals have made important contributions to this 416 work: Richard Brigham, John Chaffee, Michael Douglass and Ken 417 Murchison and Dave Thewlis. 419 This specification originated from work at the Calendaring and 420 Scheduling Consortium, which has supported the development and 421 testing of implementations of the specification. 423 9. References 425 9.1. Normative References 427 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 428 Requirement Levels", BCP 14, RFC 2119, 429 DOI 10.17487/RFC2119, March 1997, 430 . 432 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 433 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 434 . 436 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 437 Authoring and Versioning (WebDAV)", RFC 4918, 438 DOI 10.17487/RFC4918, June 2007, 439 . 441 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, 442 DOI 10.17487/RFC7303, July 2014, 443 . 445 9.2. Informative References 447 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web 448 Distributed Authoring and Versioning (WebDAV) Access 449 Control Protocol", RFC 3744, DOI 10.17487/RFC3744, May 450 2004, . 452 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 453 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 454 DOI 10.17487/RFC4791, March 2007, 455 . 457 [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed 458 Authoring and Versioning (WebDAV)", RFC 6352, 459 DOI 10.17487/RFC6352, August 2011, 460 . 462 Appendix A. Backwards-compatibility with earlier drafts 464 An earlier draft of this specification is already widely deployed 465 among both servers and clients. 467 That draft, informally known as 'caldav-notifications' largely uses 468 the same structure as this specification, but where the "DAV:" xml 469 namespace is used in this specification, the earlier draft uses 470 "http://calendarserver.org/ns/". 472 It is possible to conform to both that draft and this specification 473 by either creating two different collections, as identified by 474 "notification-URL" in each respective namespace. Alternatively it's 475 possible to use the same resource for both, but use content- 476 negotation using the Accept header to ask the server for a specific 477 representation of a notification. 479 Appendix B. Change History (to be removed prior to publication as an 480 RFC 482 Changes in -03: 484 1. Fixed a number of spelling / language issues.. 486 Changes in -02: 488 1. No significant changes. 490 Changes in -01: 492 1. Added a paragraph about xml/dtd handling with a reference to 493 RFC4917 495 Authors' Addresses 497 Evert Pot 498 fruux GmbH 499 Koenigsstrasse 32 500 Muenster, NRW 48143 501 Germany 503 Email: me@evertpot.com 504 URI: https://fruux.com/ 506 Cyrus Daboo 507 Apple Inc. 508 1 Infinite Loop 509 Cupertino, CA 95014 510 USA 512 Email: cyrus@daboo.name 513 URI: http://www.apple.com/