RFC 4661
An Extensible Markup Language (XML)-Based Format for Event Notification Filtering
An Extensible Markup Language (XML)-Based Format for Event Notification Filtering ✨
Okay bestie, let's get into RFC 4661 🎀 It's a Standards Track doc from September 2006, so it's an actual Internet standard and not just a vibe. The authors are H. Khartabil (Telio), E. Leppanen, M. Lonnfors, and J. Costa-Requena (all Nokia except Khartabil). It's part of the Network Working Group series, and the header has no "Obsoletes" or "Updates" line, so it doesn't replace or patch anything 💅
Request for Comments: 4661 · Category: Standards Track · September 2006 🌸
Status of This Memo
Okay so this section is the fine print 💜 It says this doc specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements. If you want to know where this protocol stands, check the current edition of "Internet Official Protocol Standards" (STD 1). And yes, distribution of this memo is unlimited 🦋
Copyright Notice
The copyright line reads: Copyright (C) The Internet Society (2006). 🔥
Abstract
So the SIP event notification framework already covers how Session Initiation Protocol (SIP) is used for subscriptions and for notifications when a resource's state changes ✨ What it does NOT cover is filtering, meaning how you pick which notification info actually gets delivered and what triggers the delivery. That's the gap this doc fills 🙈
Filtering is basically defining the preferred notification info you want, plus the triggers that make it show up. So the subscriber needs a way to say which state changes should send them a notification and what that notification should contain. This document does that with an XML document format 💖
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Structure of XML-Encoded Simple-Filter . . . . . . . . . . . . 4
3.1. MIME Type for Simple-Filter Document . . . . . . . . . . 4
3.2. The <filter-set> Root Element . . . . . . . . . . . . . 4
3.3. The <ns-bindings> Element . . . . . . . . . . . . . . . 4
3.4. The <filter> Element . . . . . . . . . . . . . . . . . . 5
3.5. The <what> Element . . . . . . . . . . . . . . . . . . . 6
3.5.1. The <include> Element . . . . . . . . . . . . . 6
3.5.2. The <exclude> Element . . . . . . . . . . . . . 7
3.5.3. The 'type' Attribute . . . . . . . . . . . . . . 7
3.6. The <trigger> Element . . . . . . . . . . . . . . . . . 8
3.6.1. The <changed> Element . . . . . . . . . . . . . 8
3.6.2. The <added> Element . . . . . . . . . . . . . . 9
3.6.3. The <removed> Element . . . . . . . . . . . . . 10
4. XML Schema Extensibility . . . . . . . . . . . . . . . . . . . 10
5. Syntax for Referencing XML Items and Making Logical
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 10
6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Filter Criteria Using <what> Element . . . . . . . . . . 12
6.2. Filter Criteria Using <trigger> Element . . . . . . . . 13
6.3. Filter Criteria Using <what> and <trigger> Elements . . 13
6.4. Content Filter Using Namespaces . . . . . . . . . . . . 14
6.5. Content Filter Using Only <include> Elements . . . . . . 14
6.6. Two Content Filters as Filter Criteria . . . . . . . . . 15
7. XML Schema for Filter Criteria . . . . . . . . . . . . . . . . 16
8. Security Considerations . . . . . . . . . . . . . . . . . . . 18
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
9.1. application/simple-filter+xml MIME TYPE . . . . . . . . 19
9.2. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:simple-filter . . . . . . . . . . . 20
9.3. Schema Registration . . . . . . . . . . . . . . . . . . 20
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
11.1. Normative References . . . . . . . . . . . . . . . . . . 20
11.2. Informative References . . . . . . . . . . . . . . . . . 211. Introduction ✨
So the SIP event notification framework [2] is the base layer 🍓 It explains how SIP is used for subscriptions and for notifications about changes to a resource's state. Still, it doesn't say how to do filtering, so that's what we're adding here 💅
Filtering is a mechanism for defining the preferred notification information (called content) that should be delivered, and for setting the rules for when that information should go out ✨
This is especially useful for people on mobile wireless devices 📱 Those devices usually have high latency, low bandwidth, low data processing power, a small display, and limited battery life. Filtering helps a lot because it lets you cut down the info generated at the source of the notification 🫶 BUT, and this is important, implementers need to watch out for the computational burden on the notification source. Section 8 goes into that more.
The filter criteria get described with the XML schema, and they're presented as an XML document. That document holds the user's preference for when notifications should be sent and what they should contain. The "when" part is called triggering 🔥
Triggering lets a subscriber set triggering rules for notifications. These rules are based on changes to the event package [2] specific state info. For example, with the presence information document [15], you could trigger on a change in the value of the <status> element 🦋
And the actual functionality of filtering for SIP event notifications is specified in [3] 👑
2. Conventions 💜
In this doc, the key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' are to be read as described in RFC 2119 [1], and they show the requirement levels for compliant implementations 🎀
Throughout the doc, the "resulting XML document" means the final XML document that carries the state info to be delivered to the subscriber, after the filters have been applied to it ✨
"Content" means the XML document that shows up in a notification and reflects the state of a resource 🌈
3. Structure of XML-Encoded Simple-Filter 🧚
Okay so a simple-filter is an XML document [8] that MUST be well formed, and it MUST be valid according to the schemas that are available to the validater and apply to the XML document (that includes extension schemas) 💖 On top of that, simple-filter documents MUST be based on XML 1.0 and MUST be encoded using UTF-8 🫶
The namespace identifier for elements defined here is a URN [5]. It uses the namespace identifier 'ietf' that's defined by [6] and extended by [4]. The URN is:
urn:ietf:params:xml:ns:simple-filterThis namespace declaration tells you which namespace the filter criteria are based on 🌸
3.1. MIME Type for Simple-Filter Document 🦋
The MIME type for the simple-filter document is application/simple-filter+xml. Now, any transport protocol that carries the filters AND carries payload type info MUST label the payload as MIME type application/simple-filter+xml. SIP [12] is one example, and the way you'd do it there is with a Content-Type header field 💅
3.2. The <filter-set> Root Element 👑
The root element of the filter criteria is <filter-set> ✨
The <filter-set> element contains the namespace definition we just talked about. With the optional 'package' attribute, you can define which package the filter criteria apply to. This is super handy when the XML doc with the filter criteria is separated from the events that use it, or from the protocol that normally carries it 💜
The <filter-set> element may contain one <ns-bindings> element 🍓
The <filter-set> element contains one or more <filter> elements 🎀
3.3. The <ns-bindings> Element 🌈
The <ns-bindings> element binds namespaces to local prefixes. Those prefixes get used in expressions that select elements or attributes, using the syntax in Section 5. The prefixes apply to the <include>, <exclude>, <changed>, <added>, and <removed> elements 🫶
The <ns-bindings> element contains one or more <ns-binding> elements. Each <ns-binding> element has a 'prefix' attribute. The value of 'prefix' is the prefix that qualifies the elements the expression points to. Each <ns-binding> also has a 'urn' attribute, which identifies the namespace that the prefix stands for ✨
3.4. The <filter> Element 🔥
The <filter> element is how you specify the content of an individual filter 💖
The <filter> element has an 'id' attribute. The value of 'id' MUST be unique within the <filter-set> element. The <filter> MAY have a 'uri' attribute, and its value is the URI of the resource the filter applies to. The <filter> MAY also have a 'domain' attribute, and its value is the domain of the resources the filter applies to. The 'uri' and 'domain' attributes MUST NOT appear together in the <filter> 🙈
Here's why the uri thing matters: a subscription to an event package might be addressed to an event list, and the 'event list' extension [17] is what makes that possible. So the 'uri' attribute lets the subscriber set a filter for one specific resource inside that list. That resource could be another list too 🦋 The 'uri' attribute can also carry the URI of the list itself. And if the <filter> doesn't have a 'uri' attribute, the filter applies to the resource identified in the subscription request 🌸
The 'domain' attribute carries a domain. In that case the filter applies to resources whose URI has a domain part that matches it. This comes in handy when a subscription is for an event list with lots of resources from different domains 👑
URI matching follows the matching rules defined for the particular scheme. When you're matching domains, the user part of the URI is ignored 🧚
The <filter> MAY have a 'remove' attribute. Together with the 'id' attribute, it shows which existing filter should be removed. The 'remove' attribute is a "Boolean" type, and its default value is false ✨
The <filter> MAY have an 'enabled' attribute that says whether a filter is enabled or disabled. The 'enabled' attribute is a "Boolean" type, and its default value is true 🍓
The <filter> element MAY contain a <what> element and MAY contain one or more <trigger> elements. BUT it MUST contain either the <what> element or the <trigger> element when the filter is being enabled for the first time 🎀 When you disable a filter by setting 'enabled' to false, the <what> and <trigger> elements MAY be omitted. Same deal when you re-enable it by setting 'enabled' to true: those elements MAY be omitted too 🫶
You can change the contents of a filter by changing the stuff inside <what> and <trigger>, as long as you keep the same value for the filter's 'id' attribute 💅🌈
3.5. The <what> Element 🎀
okay bestie, the <what> element is where you tell the subscription what you actually want delivered 💖 It doesn't name the exact content. It describes the rules used to build that info ✨
The <what> element may contain one or more <include> elements and one or more <exclude> elements. When you have more than one <include>, the results are additive, so each one adds an element or attribute to the resulting XML document 🌸 When you have more than one <exclude>, each one depletes the contents of the resulting XML document. It's giving subtraction energy 💅
3.5.1. The <include> Element 🦋
The <include> element selects the content you want delivered. Its value can point at an XML element, an attribute, or a namespace of an XML document you want filtered 🧚 You tell it which one using the 'type' attribute.
Note that the resulting XML document MUST be valid. So besides the elements named in your <include> values, every other mandatory XML element and/or attribute has to be pulled into the resulting XML document too, so it stays valid 🫶 In practice, that means a subscriber defining a filter only needs to <include> optional elements and/or attributes, but can <include> mandatory ones as well. There are also cases where a filter selects an attribute that belongs to an optional element. In that case the optional element needs to appear in the resulting XML document, no cap 🙈
The syntax defined in Section 5 (see the definition of "selection") MUST be used. This example selects the <basic> element defined in the PIDF [13]. That results in the <basic> element getting selected, plus all its ancestors, i.e., <status> and <tuple> 🍓
<include type="xpath">/presence/tuple/status/basic</include>.3.5.2. The <exclude> Element 🌈
The <exclude> element lets you define exceptions to the set of XML elements and/or attributes selected by the <include> elements. So XML elements (including their lower-level "child" elements) and/or attributes defined by the <exclude> element don't get delivered 🙅♀️ It's most useful when an <include> element identifies a namespace.
The <exclude> element has the optional 'type' attribute (see the definition of the 'type' in Section 3.5.3).
Note that the resulting XML document MUST be valid. So if applying the <exclude> element value to an XML document results in an invalid document according to the schema, that step MUST be reversed. The elements and/or attributes get re-introduced into the resulting XML document with their previous values, so it's valid again 🔁 This, in practice, means a subscriber defining a filter only needs to <exclude> optional elements and/or attributes, but SHOULD NOT <exclude> mandatory elements and/or attributes. Don't yeet the required stuff, bestie 😭
The syntax MUST follow Section 5.
3.5.3. The 'type' Attribute 💜
The 'type' attribute describes the value of the <include> and <exclude> elements. The pre-defined values are "xpath" and "namespace" ✨ The 'type' attribute is optional, and if you leave it out, the default value is "xpath".
The "xpath" value is used when the <include> or <exclude> element contains a value following the syntax in Section 5 that selects an element or an attribute 🎯
The "namespace" value is used when the <include> or <exclude> element contains a value of a namespace. The value is the URI of that namespace, and the resulting XML document is made up of the elements defined within the namespace 🌷
3.6. The <trigger> Element 🔥
The <trigger> element identifies the package-specific changes that a resource has to go through before the content gets delivered to the subscriber 👑 It can appear more than once in a <filter> element. Multiple appearances of this element denote the "OR" operation, which means updates to a resource that satisfy ANY of the <trigger> criteria are what gets delivered. Main character energy 🦋
The <trigger> element MAY contain the <changed>, <added>, or <removed> elements, but it MUST contain at least one of the three elements. Any combination of the 3 elements is possible. Multiple appearances of those elements within a <trigger> element denote the "AND" operation, which means updates to a resource have to satisfy ALL of the <changed>, <added>, and <removed> criteria within that <trigger> element before the content is delivered ✨
3.6.1. The <changed> Element 🌸
The <changed> element identifies the XML element or attribute, from the package-specific XML document, whose value MUST change from that of the "previous XML document". That activates the trigger and causes the content to be delivered. "Previous XML document" here means the raw version of the most recent XML document that was sent to the subscriber, before any filters were applied to it 🕰️ The XML element or attribute MUST be expressed using the syntax defined in Section 5 for the "reference" ABNF.
The <changed> element MAY contain the 'from' attribute, the 'to' attribute, the 'by' attribute, or any combination of the three. If none of those attributes are there, any change at all to the value of the element or attribute activates the trigger. An update to the element or attribute with an identical value is not a change, so don't get it twisted 🙈
Comparison of a change is done according to the element or attribute's lexical rules 💅
3.6.1.1. The 'from' Attribute 🧚
A trigger is active when the XML element or attribute identified with the <changed> element has changed from the value indicated by this attribute to a different value.
3.6.1.2. The 'to' Attribute 🍓
A trigger is active when the XML element or attribute identified with the <changed> element has changed to the value indicated by this attribute from a different value.
3.6.1.3. The 'by' Attribute 💖
A trigger is active when the XML element or attribute identified with the <changed> element has changed by at least the amount indicated by this attribute from a different value. The 'by' attribute only applies to numerical values, and it indicates a delta with respect to the current value that the attribute or element (identified in the <changed> element) needs to change by before it's selected 📈 For example, if the 'by' attribute is set to 2 and the current value of the element/attribute is 6, the element/attribute gets selected when it reaches (or exceeds) the value 8, or when it decreases to 4 or a lower value. Math that slaps 🔢
3.6.1.4. Combination of Attributes 🫶
Any combination of the 'from', 'to', and 'by' attributes in the <changed> element is possible. For example, if the 'from' attribute is combined with the 'to' attribute, the trigger is active when the XML element or attribute identified with the <changed> element has changed from the 'from' value to the 'to' value 🦋 Note that if the 'by' attribute is used in combination with the other attributes, the other attribute types MUST match the 'by' type of decimal.
3.6.2. The <added> Element 🌈
The <added> element triggers content delivery when the XML element it identifies has been added to the document being filtered. That means this instance of the element appears in the current document but not in the previous document 🎉 It can be used, for example, to learn about new services and/or capabilities the user has subscribed to, or services and/or capabilities the user has now allowed the subscriber to see. The XML element or attribute MUST be expressed using the syntax defined in Section 5 for the "reference" ABNF.
Note that if a filter includes both the content filter (<what>) part and the <added> element, then the definitions of the <what> part SHOULD also cover the added elements. Otherwise, the content gets delivered without the items defined in the <added> element, and that's a whole mood 😭
3.6.3. The <removed> Element 👑
The <removed> element triggers content delivery when the XML element it identifies has been removed from the document being filtered. That means this instance of the element appeared in the previous document but not in this one 🫥 The XML element or attribute MUST be expressed using the syntax defined in Section 5 for the "reference" ABNF.
4. XML Schema Extensibility 🧚
The simple-filter document is meant to be extended! 🌟 An extension happens by defining a new set of elements in a new namespace, governed by a new schema. Every extension MUST have an appropriate XML namespace assigned to it. The XML namespace of the extension MUST be different from the namespaces defined in this specification. The extension MUST NOT change the syntax or semantics of the schemas defined in this document. All XML tags and attributes that are part of the extension MUST be appropriately qualified so they sit within that namespace, and MUST be designed such that receivers can safely ignore such extensions 🛡️
This specification defines explicit places where new elements or attributes from an extension can go. These are marked in the schemas by the <any> and <anyAttribute> elements. Extensions to this specification MUST specify where their elements can be placed within the document 📍
As a result, a document that contains extensions will need multiple schemas to figure out its validity: a schema defined in this document, along with the schemas defined by the extensions present in the document 🧩 Because extensions happen by adding new elements and attributes governed by new schemas, the schemas defined in this document are fixed and would only change through a revision to this specification. Such a revision, should it happen, would endeavor to let documents compliant with the previous schema stay compliant with the new one. So the schemas defined here don't provide explicit schema versions, since that's not expected to be needed 💅✨
5. Syntax for Referencing XML Items and Making Logical Expressions ✨
okay so the syntax for these expressions is written in ABNF [10], and it's basically XPATH [9] vibes 💅 but with a smaller set of powers. If you already know XPATH you'll recognise everything, and [9] has the full scoop on what each piece means. The "abbreviated syntax" of the "node test" is what shows up in the references ("reference") 🎀 The expression part lines up with the predicate, comparison, and logical stuff in XPATH. One important thing: if an XPATH expression lands on more than one element at a given step, the filter applies to all of them. So if a filter catches 2 elements, you get both of them back, no drama 🦋
selection = reference [expression]
expression = "[" (elem-expr / attr-expr)
1*[oper (elem-expr / attr-expr)] "]"
elem-expr = (elem-path / "." / "..") compar value
elem-path = (element / "*") 1*["/" / "*" / element] ["*" / element]
attr-expr = [elem-path "/"] attribute compar value
reference = elem-reference / attr-reference
elem-reference = "/" 1*("/" / "/*" / ("/" element))
attr-reference = reference attribute
oper = "and" / "or"
compar = "=" / "<" / ">"
element = [ns] string
attribute = "@" [ns] string
ns = string ":"
string = <any sequence of data supported by XML in names of XML
element, and/or attribute or prefixes of namespaces>
value = <any sequence of data supported by XML as a value of the
XML element and/or attribute>When you're pointing at XML elements or attributes, the value can have two parts: the selector (which element or attribute you mean) and the condition (the comparison and logic stuff) 🌸 The selector comes first, and then the condition goes in square brackets. In the selector part you can spell out the whole path like "/presence/tuple/status/basic", or you can match a name at any depth with "//tuple/status/basic", or use the * wildcard to mean "anything at this level", like "/*/watcher" ✨
Here are some example references, bestie 🫶
- Selecting an element by using an XML element as a condition:
//*[status/basic="open"]/presence/tuple[*/basic="open"]
- Selecting an element by using XML attributes as a condition:
//watcher[@duration-subscribed<500]/*/watcher[@event="rejected"]
- Selecting an element by using two XML elements as a condition:
//tuple[status/basic="open" and type="device"]
- Selecting an attribute:
//watcher/@duration-subscribed
Sometimes, because of how the XML schema is designed, an XPATH-like expression ends up matching more than one element with the same name (the expression might not have pinned down one unique element at every step) 💀 In those cases, every element that gets identified is selected. No picking favourites 👑
When you evaluate XPATH location steps, namespace expansion follows the XPATH 1.0 [9] rules, which means that if a QName has no prefix, the namespace URI in the expanded name is null. For non-default namespaces, the expansion is done using the given <ns-bindings> definitions. If a default namespace is used in the document, the <ns-binding> element SHOULD be used to define an equal URI with some prefix, so that the location steps evaluate properly in XPATH 🌈
6. Examples
The XML Schema for the XML document examples is specified in Section 7. 🧚
6.1. Filter Criteria Using <what> Element
Picture this: a user wants to know when his friend is free and which messaging options (SMS, IM, and MMS) are open, so he can tell whether the friend can get a message right now, which address to use, and what kind of message to send 📱💖
This example shows how to define a content filter. The <basic> element and all of its parent elements are selected based on a condition written as a logical expression. That condition is <class> elements whose value is "MMS", "SMS", or "IM" 🎀
The <class> element is defined in [14] as an extension to PIDF [13].
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="pidf" urn="urn:ietf:params:xml:ns:pidf"/>
<ns-binding prefix="rpid"
urn="urn:ietf:params:xml:ns:pidf:rpid"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<what>
<include type="xpath">
/pidf:presence/pidf:tuple[rpid:class="IM" or rpid:class="SMS"
or rpid:class="MMS"]/pidf:status/pidf:basic
</include>
</what>
</filter>
</filter-set>6.2. Filter Criteria Using <trigger> Element
A user needs to hear about it the moment his colleague becomes available by some communication means 🔥 He gets the full presence state of the colleague when a certain PIDF [13] tuple <basic> status changes from "closed" to "open" ✨
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="pidf" urn="urn:ietf:params:xml:ns:pidf"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<trigger>
<changed from="CLOSED" to="OPEN">
/pidf:presence/pidf:tuple/pidf:status/pidf:basic
</changed>
</trigger>
</filter>
</filter-set>6.3. Filter Criteria Using <what> and <trigger> Elements
This user wants to see who is pending and waiting for subscriptions, so she can decide who gets to see her presence info 👀🦋
The filter picks watcher information notifications [16] to be sent when a subscription status changes to "pending" or "waiting". In the notification, only the watchers whose status is "pending" or "waiting" are included 💜
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="wi"
urn="urn:ietf:params:xml:ns:watcherinfo"/>
</ns-bindings>
<filter id="123" uri="sip:presentity@example.com">
<what>
<include>
/wi:watcherinfo/wi:watcher-list/wi:watcher[@status="pending"
or @status="waiting"]
</include>
</what>
<trigger>
<changed to="pending">
/wi:watcherinfo/wi:watcher-list/wi:watcher/@status
</changed>
</trigger>
<trigger>
<changed to="waiting">
/wi:watcherinfo/wi:watcher-list/wi:watcher/@status
</changed>
</trigger>
</filter>
</filter-set>6.4. Content Filter Using Namespaces
She turns her terminal on, and it automatically grabs general presence status and communication means from a set of pre-defined buddies 🌸
The filter is set up to select XML elements that belong to the PIDF namespace 🧚
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<filter id="123" uri="sip:buddylist@example.com">
<what>
<include type="namespace">
urn:ietf:params:xml:ns:pidf
</include>
</what>
</filter>
</filter-set>6.5. Content Filter Using Only <include> Elements
This one is for gamers 🎮 A user wants to know whether a group of his friends is available for gaming. He orders notifications about the current status and about future changes to the game-specific presence information 🔥
This filter selects the game-specific tuple to be delivered 👑
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter" >
<ns-bindings>
<ns-binding prefix="game-ext"
urn="urn:ietf:params:xml:ns:game-ext"/>
</ns-bindings>
<filter id="123">
<what>
<include>
/pidf:presence/pidf:tuple/
pidf:status[game-ext:label="game-X"]
</include>
</what>
</filter>
</filter-set>6.6. Two Content Filters as Filter Criteria
This user is very into staying up to date on her friends' communication means and contact addresses 💅 She also wants more info (like location) about one friend in particular, named Bob 🫶 The PIDF <note> element is filtered out, meaning it's excluded. The list was predefined as buddies@example.com 🌈
<?xml version="1.0" encoding="UTF-8"?>
<filter-set xmlns="urn:ietf:params:xml:ns:simple-filter">
<ns-bindings>
<ns-binding prefix="pidf" urn="urn:ietf:params:xml:ns:pidf"/>
<ns-binding prefix="rpid"
urn="urn:ietf:params:xml:ns:pidf:rpid"/>
</ns-bindings>
<filter id="8439" uri="sip:buddies@example.com">
<what>
<include>
/pidf:presence/pidf:tuple[rpid:class="service"]/pidf:status/
pidf:basic
</include>
</what>
</filter>
<filter id="999" uri="sip:bob@example.com">
<what>
<include type="namespace">
urn:ietf:params:xml:ns:pidf
</include>
<exclude>
/pidf:presence/pidf:tuple/pidf:note
</exclude>
</what>
</filter>
</filter-set>7. XML Schema for Filter Criteria ✨
okay so this is the actual schema, and it's the official source of truth for what a filter is allowed to look like, so no notes from me in the middle, bestie 💅 (it's marked Normative, which means implementers have to follow it)
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:simple-filter"
xmlns="urn:ietf:params:xml:ns:simple-filter"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<xs:annotation>
<xs:documentation xml:lang="en">
XML Schema Definition for Filter Criteria.
</xs:documentation>
</xs:annotation>
<xs:element name="filter-set" type="FilterSetType"/>
<xs:complexType name="FilterSetType">
<xs:sequence>
<xs:element name="ns-bindings" type="NSBindings"
minOccurs="0" maxOccurs="1"/>
<xs:element name="filter" type="FilterType"
minOccurs="1"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="package" type="xs:string" use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:complexType>
<xs:complexType name="NSBindings">
<xs:sequence>
<xs:element name="ns-binding" type="NSBinding"
minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="NSBinding">
<xs:attribute name="prefix" type="xs:string" use="required"/>
<xs:attribute name="urn" type="xs:anyURI" use="required"/>
</xs:complexType>
<xs:complexType name="FilterType">
<xs:sequence>
<xs:element name="what" type="WhatType"
minOccurs="0" maxOccurs="1"/>
<xs:element name="trigger" type="TriggerType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="uri" type="xs:anyURI" use="optional"/>
<xs:attribute name="domain" type="xs:string" use="optional"/>
<xs:attribute name="remove" type="xs:boolean" use="optional"
default="false"/>
<xs:attribute name="enabled" type="xs:boolean" use="optional"
default="true"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:complexType>
<xs:complexType name="WhatType">
<xs:sequence>
<xs:element name="include" type="InclType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="exclude" type="ExclType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="InclType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="TypeType"
default="xpath" use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="ExclType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="TypeType"
default="xpath" use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name="TypeType">
<xs:restriction base="xs:string">
<xs:enumeration value="xpath"/>
<xs:enumeration value="namespace"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="TriggerType">
<xs:sequence>
<xs:element name="changed" type="ChangedType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="added" type="xs:string"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="removed" type="xs:string"
minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ChangedType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="from" type="xs:anySimpleType"
use="optional"/>
<xs:attribute name="to" type="xs:anySimpleType"
use="optional"/>
<xs:attribute name="by" type="xs:decimal"
use="optional"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>8. Security Considerations 🔥
okay this section is SERIOUS, bestie 😭 the filters in the body of a SIP message have a huge effect on how the request gets handled at a server. so it's especially important that messages with this extension get authenticated and authorised. authentication can be done with the Digest Authentication mechanism described in [12]. and the authorisation decision is based on the permissions that the resource (notifier) has given to the watcher. an example of an authorisation policy is in [18].
requests can reveal sensitive info about a UA's capabilities 👀 if that info is sensitive, it SHOULD be encrypted using SIP S/MIME capabilities [11].
all filtering-related security measures discussed in [2] MUST be followed, along with package-specific security. no skipping, periodt 🚨
9. IANA Considerations 🌸
this document registers a new MIME type, "application/simple-filter+xml", and it also registers a new XML namespace. it follows the guidelines of RFC3023 [7] 💖
9.1. application/simple-filter+xml MIME TYPE
MIME media type: application
MIME subtype name: simple-filter+xml
Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml, as specified in RFC 3023 [7].
Encoding considerations: Same as encoding considerations of application/xml, as specified in RFC 3023 [7].
Security considerations: See section 10 of RFC 3023 [7] and section Section 8 of this document.
Interoperability considerations: none.
Published specification: This document.
Applications that use this media type: This document type has been used to support the SIP-based Event notification framework and its packages.
Additional information:
Magic number: None
File extension: .cl or .xml
Macintosh file type code: "TEXT"
Personal and email address for further information: Hisham Khartabil (hisham.khartabil@telio.no)
Intended Usage: COMMON
Author/change controller: The IETF
9.2. URN Sub-Namespace Registration for urn:ietf:params:xml:ns:simple-filter
this section registers a new XML namespace, per the guidelines in the IETF XML Registry [4] ✨
URI: The URI for this namespace is urn:ietf:params:xml:ns:simple-filter.
Registrant Contact: IETF, SIMPLE working group, Hisham Khartabil (hisham.khartabil@telio.no)
9.3. Schema Registration
this section registers a new XML schema per the procedures in [4] 🎀
URI: urn:ietf:params:xml:ns:simple-filter
Registrant Contact: IETF, SIMPLE working group, Hisham Khartabil (hisham.khartabil@telio.no).
the XML for this schema is the sole content of Section 7 🧚
10. Acknowledgements 💜
the authors wanna thank Jonathan Rosenberg, Henning Schulzrinne, Tim Moran, Jari Urpalainen, Sreenivas Addagatla, Miguel-Angel Garcia Martin, Mary Barnes, Paul Kyzivat, Robert Sparks, and Elwyn Davies for their valuable input and comments 🫶
11. References 📚
11.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[2] Roach, A. B., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002.
[3] Khartabil, H., Leppanen, E., Lonnfors, M., and J. Costa-Requena, "Functional Description of Event Notification Filtering", RFC 4660, September 2006.
[4] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
[5] Moats, R., "URN Syntax", RFC 2141, May 1997.
[6] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, August 1999.
[7] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", RFC 3023, January 2001.
[8] Bray, T., "Exensible Markup Language (XML) 1.0 (Second Edition)", W3C CR CR-xml11-20011006, October 2000.
[9] Clark, J., "XML Path Language (XPath) Version 1.0", W3C REC REC-xpath-19991116, November 1999.
[10] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005.
[11] Ramsdell, B., "Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.1 Message Specification", RFC 3851, July 2004.
11.2. Informative References
[12] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002.
[13] Sugano, H., Fujimoto, S., Klyne, G., Bateman, A., Carr, W., and J. Peterson, "Presence Information Data Format (PIDF)", RFC 3863, August 2004.
[14] Schulzrinne, H., Gurbani, V., Kyzivat, P., and J. Rosenberg, "RPID -- Rich Presence Extensions to the Presence Information Data Format (PIDF)", RFC 4480, July 2006.
[15] Rosenberg, J., "A Presence Event Package for the Session Initiation Protocol (SIP)", RFC 3856, August 2004.
[16] Rosenberg, J., "An Extensible Markup Language (XML) Based Format for Watcher Information", RFC 3858, August 2004.
[17] Roach, A. B., Campbell, B., and J. Rosenberg, "A Session Initiation Protocol (SIP) Event Notification Extension for Resource Lists", RFC 4663, September 2006.
[18] Rosenberg, J., "Presence Authorization Rules", Work in Progress, June 2006.
Authors' Addresses 🦋
Hisham Khartabil Telio P.O. Box 1203 Vika Oslo Norway
Phone: +47 2167 3544 EMail: hisham.khartabil@telio.no
Eva Leppanen Nokia P.O BOX 785 Tampere Finland
Phone: +358 7180 77066 EMail: eva-maria.leppanen@nokia.com
Mikko Lonnfors Nokia P.O BOX 321 Helsinki Finland
Phone: + 358 71800 8000 EMail: mikko.lonnfors@nokia.com
Jose Costa-Requena Nokia P.O. Box 321 FIN-00045 NOKIA GROUP FINLAND
Phone: +358 71800 8000 EMail: jose.costa-requena@nokia.com
Full Copyright Statement 🌈
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property ⚖️
okay bestie, let's talk about who owns what 💅 The IETF takes no position on whether any Intellectual Property Rights or other rights that someone might claim over the tech in this doc are valid or how far they reach 🙈 It also doesn't say whether any license under those rights might or might not be available, and it hasn't gone out and checked for any such rights either 🔍 If you want the procedures for rights in RFC documents, go read BCP 78 and BCP 79 📚
Copies of IPR disclosures sent to the IETF Secretariat, any assurances of licenses that will be made available, or the outcome of an attempt to get a general license or permission for implementers or users of this spec to use those proprietary rights, can all be found in the IETF online IPR repository at http://www.ietf.org/ipr ✨
The IETF invites anyone who's interested to flag any copyrights, patents, patent applications, or other proprietary rights that might cover tech which may be required to implement this standard 🦋 Send that info to the IETF at ietf-ipr@ietf.org 💌
Acknowledgement 🫶
Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA) 💖 It's giving teamwork, and we love to see it 🌈
📦 where this page comes from
- ietf: rfc4661 2006-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms