SIMPLE H. Khartabil Internet-Draft M. Lonnfors Expires: September 30, 2003 J. Costa-Requena E. Leppanen Nokia April 2003 An Extensible Markup Language (XML) Based Format for Event Notification Filtering draft-khartabil-simple-filter-format-00 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on September 30, 2003. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract The SIP event notification framework describes the usage of the Session Initiation Protocol (SIP) for subscriptions and notifications of changes to a state of a resource. The document does not describe a mechanism of how filtering of event notification information can be achieved. In order to enable this, a format is needed to enable the subscriber to choose when notifications are to be sent to it and what they are to contain. This document presents a solution in the form of an XML Khartabil, et al. Expires September 30, 2003 [Page 1] Internet-Draft XML Based Format for Filtering April 2003 document format. Table of Contents 1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 Motivation for Using XML . . . . . . . . . . . . . . . . . 4 3. Structure of XML-Encoded Filter Criteria . . . . . . . . . 4 3.1 The Root Element . . . . . . . . . . . . . 5 3.2 The Element . . . . . . . . . . . . . . . . . 5 3.3 The Element . . . . . . . . . . . . . . . . . . . . 5 3.3.1 Defining the Delivered Content . . . . . . . . . . . . . . 5 3.4 The Element . . . . . . . . . . . . . . . . . . 6 3.4.1 The Element . . . . . . . . . . . . . . . . . . 6 3.4.1.1 The "changed-from" Attribute . . . . . . . . . . . . . . . 7 3.4.1.2 The "changed-to" Attribute . . . . . . . . . . . . . . . . 7 3.4.1.3 The "changed-by" Attribute . . . . . . . . . . . . . . . . 7 3.4.1.4 Combination of Attributes . . . . . . . . . . . . . . . . 7 3.4.2 The Element . . . . . . . . . . . . . . . . . . . 7 3.4.3 The Element . . . . . . . . . . . . . . . . . . 8 4. IANA Considerations . . . . . . . . . . . . . . . . . . . 8 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.1 Filter Using Element . . . . . . . . . . . . . . . 8 5.2 Filter Using Element . . . . . . . . . . . . . . 8 5.3 Filter Using and Elements . . . . . . . . 9 6. XML Schema for Filter Criteria . . . . . . . . . . . . . . 9 7. Security Requirements . . . . . . . . . . . . . . . . . . 10 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 11 References . . . . . . . . . . . . . . . . . . . . . . . . 11 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 12 Intellectual Property and Copyright Statements . . . . . . 14 Khartabil, et al. Expires September 30, 2003 [Page 2] Internet-Draft XML Based Format for Filtering April 2003 1. Conventions In this document, the key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' are to be interpreted as described in RFC 2119 [1] and indicate requirement levels for compliant implementations. 2. Introduction SIP event notification is described in [5]. It defines a general framework for sending subscriptions and receiving notifications in SIP based systems. It introduces the concept of event packages, which are concrete applications of the general event framework to a specific usage of events. Filtering is a mechanism for controlling the content of event notifications and for specifying the rules for when a notification should be sent. See requirements in [8] and [9]. The filtering mechanism is expected to be particularly valuable to users of mobile wireless access devices. The characteristics of the devices typically include high latency, low bandwidth, low data processing capabilities, small display, and limited battery power. Such devices can benefit from the ability to filter the amount of information generated at the source of the event notification. It is stated in [5] that the notifier may send a NOTIFY at any time, but typically it is sent when the state of the resource changes. It also states that the notifications would contain the complete and current state of the resource authorized for a certain subscriber to see. The format of such resource state information is package specific. In this memo, we assume that the NOTIFY for any package contains an XML document. There is a separate approach for the rate limiting of SIP event notifications, namely the throttling mechanism [10]. This throttling mechanism allows the subscriber to specify a maximum rate at which event notifications are generated by a single notifier. The solution for such requirements is out of scope for this document. This document presents an XML format whereby a subscriber describes its preference when notifications are to be sent to it and what they are to contain. The scope of the "when" part is triggering. Triggering is defined as enabling a subscriber to specify triggering rules for notifications where the criteria are based on changes of the package specific state information, e.g., for the presence information document [4] the change in the value of the element. Khartabil, et al. Expires September 30, 2003 [Page 3] Internet-Draft XML Based Format for Filtering April 2003 2.1 Motivation for Using XML When trying to select the schema and protocol for defining the filter criteria, it can be found that there are several alternatives available. The best practice is to modularise the problem and work on smaller modules (the protocol and the filter information schema). The selection of the schema for defining the filter criteria requires a readable syntax with enough flexibility to define the semantics. Among the multiple possibilities (i.e. XML, Perl, TCL, CPL, etc), XML provides a generic framework for defining an XML schema for the filter criteria. The XML schema provides an extensible mechanism where the logic required for the filtering functionality can be built. A globally unique URI is associated to the XML schema specified for the filtering. The XML schema is shown as a namespace in a filter criteria. The XML also enables the use of XPath [16] for referencing items in an XML document (which is in the case of Presence [4] in the format of the PIDF). Some of the content-types of the event notifications are extensible XML documents, e.g. PIDF [2]. Since there is a need to reference the extensions in filters, a solution where fixed data element names of an XML document are referenced is not appropriate. In addition, by using XML the need for reliance on the transport protocol in order to interpret the filter criteria can be eliminated. 3. Structure of XML-Encoded Filter Criteria The filter criteria is an XML document [15] that MUST be well-formed and SHOULD be valid. The filter criteria XML documents MUST have the XML declaration and it SHOULD contain an encoding declaration in the XML declaration, for example; "". This specification makes use of XML namespaces for identifying the XML schema of the filter criteria documents and document fragments. The namespace identifier for elements defined by this specification is a URN [12], using the namespace identifier 'ietf' defined by [13] and extended by [11]. This urn is: urn:ietf:params:xml:ns:simple-filter+xml. This namespace declaration indicates the namespace on which the filter criteria are based on. Khartabil, et al. Expires September 30, 2003 [Page 4] Internet-Draft XML Based Format for Filtering April 2003 3.1 The Root Element The root element of the filter criteria is . The root element MUST contain the namespace mentioned above. This element MUST contain one or more elements. 3.2 The Element The element is used to specify the content of an individual filter. MUST have an 'id' attribute. The value of the 'id' attribute MUST be unique within the root element. MAY have an 'uri' attribute. The value of the 'uri' attribute is the URI of the resource that is being subscribed to. The URI of the resource is useful in cases where the 'eventlist' extension [6] is used with a package and different filter criteria are defined for one or more members of the list. The 'uri' attribute in the element identifies the member within list to whom that specific filter criteria apply. If the does not contain the 'uri' attribute, the filter criteria apply to all the members in the list unless a member of the list has its own filter criteria attributed by the 'uri' attribute. The element MAY contain a element and MAY contain one or more elements, but MUST contain either the element or the element. 3.3 The Element The element is used to specify the content to be delivered to the subscriber. It does not specify the exact content but the rules that are used to construct that information. 3.3.1 Defining the Delivered Content It must be possible in the filter criteria to be able to select XML attributes and/or elements of the default information format specific to an event package. It must also be possible to reference any extensions to the default information formats that are valid for that event package. A general way to reference any items (XML elements and attributes) of the NOTIFY information document is specified. The referencing mechanism support hierarchy of the items since there may be several nested XML elements and attributes in the NOTIFY document. Khartabil, et al. Expires September 30, 2003 [Page 5] The preferred elements are indicated using the capabilities of XPath [16]. The XPath clause is stated in the value of the element. The items addressed with the XPath are indicated with the expanded name, which means that the URI of the namespace referenced in the XPath expression is included in addition to the reference to the information element or attribute. The XPath expression needs to specifically request values of elements and attributes to be included in the newly constructed XML document. This means that specifying only the XML element or attribute path is not enough for receiving the values. This is achieved using the XPath "text()" function. This way of constructing XPath expressions makes it possible for the subscribers to retrieve the structure of an XML document with or without element or attribute values. For example, to request a tuple from a presence document that has a element with value 'open', and to request that the values of all the sub-elements in that tuple to be included in the constructed XML document, you need to specify an XPath expression that look like: //*[status/basic="open"]/descendant::* | //*[status/basic="open"]/ ancestor-or-self::* | //*[status/basic="open"]/descendant::*/text() | //*[status/basic="open"]/ancestor-or-self::*/text() 3.4 The Element The element is used to identify the package specific changes that a resource has to encounter before a notification is delivered to the subscriber. It can appear more than once in a filter document. Multiple appearances of this element denotes the "OR" operation. This means that updates to a resource that satisfy any of the elements criteria constitute a notification to be delivered. The element MAY contain the element, the element or the , but MUST contain at least one of the three elements. Any combination of the 3 elements is possible. Multiple appearances of those element within a element denotes the "AND" operation. This means that updates to a resource that satisfy ALL of the , and elements' criteria within the element constitute a notification to be delivered. The XPath expression in all the elements inside the element may comtain a reference to an element/attribute or to the value of the element/attribute. Both are interpreted as references to the value. 3.4.1 The Element The element is used to identify the XML element or attribute, from the package specific XML document, that must change, Khartabil, et al. Expires September 30, 2003 [Page 6] Internet-Draft XML Based Format for Filtering April 2003 compared to the previous XML document, in order to activate the trigger and cause the NOTIFY to be delivered. The XML element or attribute is indicated using the capabilities of XPath. The XPath expression MUST only reference one element or attribute. [16]. The element MAY contain the "changed-from" attribute, "changed-to" attribute, "changed-by" attribute, or any combination of the three. 3.4.1.1 The "changed-from" Attribute A trigger is active when the element or attribute identified with the element has changed from the value indicated by this attribute to a different value. 3.4.1.2 The "changed-to" Attribute A trigger is active when the element or attribute identified with the element has changed to the value indicated by this attribute from a different value. 3.4.1.3 The "changed-by" Attribute A trigger is active when the element or attribute identified with the element has changed by the value indicated by this attribute from a different value. 3.4.1.4 Combination of Attributes Any combination of the "changed-from", "changed-to", and "changed-by" attributes in the element is possible. For example, if the "changed-from" attribute was combined with the "changed-to" attribute it is interpreted as: the trigger is active when the XML element or attribute identified with the element has changed from the "changed-from" value to the "changed-to" value. Note that if the "changed-by" attribute is used in combination with the other attributes, the other attribute types MUST match the "changed-by" type of decimal. 3.4.2 The Element The element is used to trigger a NOTIFY when the element or attribute, identified in it, has been added to the new XML document in comparison to the previous XML document. It can be used, for example, by subscribers to learn of new services and/or capabilities subscribed to by the notifier, or services and/or capabilities that the notifier has now allowed the subscriber to see. Khartabil, et al. Expires September 30, 2003 [Page 7] Internet-Draft XML Based Format for Filtering April 2003 3.4.3 The Element The element is used to trigger a NOTIFY when the element or attribute, identified in it, has been removed from the new XML document in comparison to the previous XML document. 4. IANA Considerations A new content type "application/simple-filter+xml" is defined to represent an XML MIME for the filter criteria. This specification follows the guidelines of RFC3023 [14] OPEN ISSUE: IANA registration template must be added later. 5. Examples 5.1 Filter Using Element This XPath expression selects all the upper, lower and parallel level presence information elements that match the criteria (this means the whole tuple and the base element). That criteria are: select