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/