RFC 3858
An Extensible Markup Language (XML) Based Format for Watcher Information
RFC 3858: An Extensible Markup Language (XML) Based Format for Watcher Information 🎀
Okay bestie, this one's from the Network Working Group ✨. J. Rosenberg wrote it while at dynamicsoft, and it's a Standards Track doc dated August 2004 💅. It doesn't obsolete or update any other RFCs (no "Obsoletes" or "Updates" line in the header). It's basically about how to package up who is watching you in XML 🦋
Status of This Memo 💖
Okay so this one's a real Internet standards track protocol spec for the whole Internet community, and they're literally asking for your feedback and ideas 🫶 For the official standardization state of this protocol, you check the "Internet Official Protocol Standards" (STD 1) doc. And distribution of this memo is unlimited, so share it with everyone 🌈
Copyright Notice 🌸
Copyright (C) The Internet Society (2004). Simple as that 💜
Abstract 🦋
So a watcher is basically any entity that subscribes to info about a resource 👀 The state for all those subscriptions to one resource is called the watcher information, and it's constantly changing as people join and leave ✨ Because it's so dynamic, you can actually subscribe to watcher information too, which is iconic 💅 To make that work, you need a format that describes the watchers' state, and this spec defines an XML document format for exactly that 🧚
Table of Contents 🍓
1. Introduction ................................................ 2
2. Terminology ............................................... 2
3. Structure of Watcher Information ........................... 2
4. Computing Watcher Lists from the Document .................. 5
5. Example .................................................... 6
6. XML Schema ................................................. 6
7. Security Considerations .................................... 8
8. IANA Considerations ........................................ 9
8.1. application/watcherinfo+xml MIME Registration ......... 9
8.2. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:watcherinfo .................... 10
9. Normative References ....................................... 10
10. Informative References ..................................... 11
11. Acknowledgements ........................................... 11
12. Contributors ............................................... 12
13. Author's Address ........................................... 13
14. Full Copyright Statement ................................... 141. Introduction ✨
Okay so watchers are entities that subscribe to info about a resource, and they do it using the SIP event framework from RFC 3265 [1] 💖 Their subscriptions come with pretty complicated state, like who the subscriber is, what the subscription's status is, and more 🤯 All that state for every subscription to one resource is the watcher information for that resource, and it's always changing as subscribers come and go 🦋 So it's totally possible (and genuinely useful!) to subscribe to watcher information. The big reason this matters is that a user can find out who's subscribed to their presentity [11] and then make an authorization decision about each subscription 👑
To make all this work you need two pieces. The first is a SIP event template-package for watcher information, and the second is a data format for representing watcher information. The template-package lives in [2], and the data format is what this doc is all about 🎀
2. Terminology 🌈
Here's the key vocab 💅 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 BCP 14, RFC 2119 [3], and they tell you the requirement levels for compliant implementations 🔥
This doc also uses the terms subscriber, watcher, subscription, notification, watcherinfo subscription, watcherinfo subscriber, and watcherinfo notification, all with the meanings given in [2] ✨
3. Structure of Watcher Information 🧚
Okay this is the main event 🫶 Watcher information is an XML document [4] that MUST be well-formed and SHOULD be valid. Watcher information documents MUST be based on XML 1.0 and MUST be encoded using UTF-8 💜 This spec uses XML namespaces to identify watcherinfo documents and document fragments. The namespace URI for elements defined here is a URN [5], using the namespace identifier 'ietf' defined by [6] and extended by [7]. The URN is:
urn:ietf:params:xml:ns:watcherinfoA watcher information document starts with the root element tag watcherinfo 👑 It holds any number of watcher-list sub-elements, and each one is a list of watchers for a particular resource 🍓 Elements from other namespaces MAY be present for extensibility, but elements or attributes from unknown namespaces MUST be ignored 🙈 There are two attributes on the watcherinfo element, and both of which MUST be present:
version: This lets the recipient of watcherinfo documents put them in the right order 📚 Versions start at 0 and go up by one for each new document sent to a watcherinfo subscriber. They're scoped within a watcherinfo subscription, and they MUST be representable using a 32 bit integer. Versions do not wrap, so no restarting at zero 💀state: This tells you whether the document has the full watcherinfo state, or only the watchers that changed since the previous document (partial) ✨
Each watcher-list element holds a list of watcher elements, and each one describes a watcher on a particular resource 🦋 Again, elements from other namespaces MAY be present for extensibility, and elements or attributes from unknown namespaces MUST be ignored. There are two attributes on watcher-list, and both of which MUST be present:
resource: A URI for the resource that this list of watchers is watching. It's mandatory 🎀package: A token that names the event package the watcher info for that resource is being provided under. It's mandatory too 🌸
The watcher element describes one watcher in the list 💖 Its value is a URI for the watcher, and this URI SHOULD be the authenticated identity of the watcher as the server processing the subscription determined it. Because of that, the URI is usually an address-of-record (like sip:joe@example.com) and not a device address (like sip:joe@192.0.2.3) 🫶 There are three mandatory attributes which MUST be present:
id: A unique identifier for the subscription described by the watcher element. The id MUST be representable using the grammar for token from RFC 3261 [8]. It MUST be unique across all other watchers reported in documents sent in notifications for a particular watcherinfo subscription 🔑status: The status of the subscription. What each status means is defined in the watcher information event package [2] 🍓event: The event that caused the transition to the current status. The events are defined in the watcher information event package [2] 🔥
There are also some optional, informative attributes on the watcher element 🌈 They are:
display-name: A text version of the subscriber's name 💅expiration: How many seconds from the current time until the subscription expires ⏳duration-subscribed: How many seconds passed between when the SUBSCRIBE that created the subscription was received and the current time 🧚
The xml:lang attribute MAY be used with the watcher element to say what language the display-name is in 🌍
How many watchers show up for each resource, and which resources are listed at all, depends on what kind of data is being provided and who it's being provided to 👀
Okay here are some examples, because they help a lot 💕 In the first one, a user named A subscribes to the presence of another user, B. A wants to know how their own subscription is doing, so A subscribes to the watcher information for B's presence. But A isn't authorized to see every watcher of B's presence, so the watcher information sent to A has only one watcher in it: A themself 🥺
In the second one, a user named B wants to know who has subscribed to B's presence. So B subscribes to the watcher information for B's presence. B is authorized to see all the watchers, so the watcher information sent to B has every single watcher of B's presence in it 👑
And in the case where an administrator wants to see the current status of the whole system, the watcher information could include all the watchers for all the resources 🌟
Part 1 is done, bestie, and there's more coming 💖
4. Computing Watcher Lists from the Document ✨
okay so, a watcherinfo NOTIFY usually only includes the watchers whose state just changed 🦋 which means if you want the full picture of everyone watching, you have to stitch the NOTIFYs together over time. the watcherinfo subscriber keeps a table for each watcher list it hears about. each list is identified by the URI in the resource attribute of the watcher-list element. inside each table there's one row per watcher, and each row is keyed by that watcher's unique ID, which lives in the id attribute of the watcher element. the row holds that watcher's state exactly as the watcher element describes it 💅
every table also has a version number, and this is where it gets really satisfying 😭 the version number MUST be set to the version attribute from the watcherinfo element of the very first document received. every time a new document comes in, the local version number and the new document's version attribute get compared:
- if the new value is exactly one higher than the local number, bump the local number by one and process the document ✨
- if the new value is more than one higher, set the local number to the new document's value, process the document, and the watcherinfo subscriber SHOULD generate a refresh request to trigger a full state notification 🔥
- if the new value is lower than the local version, toss the document without processing it 🗑️
the processing itself depends on whether the document has full or partial state 🌈 when the state attribute of the watcherinfo element says full, you flush every table tied to this watcherinfo subscription, then rebuild them from the document. a new table gets created for each watcher-list element, and a new row gets created for each watcher element 🎀
when the document says partial, it's a more surgical update. for each watcher-list element, the subscriber checks whether a table already exists for that list by comparing the URI in the resource attribute with the URI linked to the table. if there's no table yet, one gets made. then, for each watcher element in that list, the subscriber checks for an existing row by comparing the id attribute with the ID tied to the row. no row? add one and set its state from that watcher element. row already there? update its state to match that watcher element 🧚
one last detail, and it's a fun one: if a row gets updated or created so that its state is now terminated, that entry MAY be removed from the table at any time 🍓
5. Example
here's a little example of watcher information for a presentity who happens to be a professor 🎓 there are two watchers in it, userA and userB 👀
<?xml version="1.0"?>
<watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"
version="0" state="full">
<watcher-list resource="sip:professor@example.net" package="presence">
<watcher status="active"
id="8ajksjda7s"
duration-subscribed="509"
event="approved" >sip:userA@example.net</watcher>
<watcher status="pending"
id="hh8juja87s997-ass7"
display-name="Mr. Subscriber"
event="subscribe">sip:userB@example.org</watcher>
</watcher-list>
</watcherinfo>6. XML Schema
this is the schema definition for the watcherinfo document format, the official blueprint that tells every parser what's allowed 📐🎀
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="urn:ietf:params:xml:ns:watcherinfo"
xmlns:tns="urn:ietf:params:xml:ns:watcherinfo" >
<!-- This import brings in the XML language attribute xml:lang-->
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/03/xml.xsd" />
<xs:element name="watcherinfo">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:watcher-list" minOccurs="0"
maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="version" type="xs:nonNegativeInteger"
use="required"/>
<xs:attribute name="state" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="full"/>
<xs:enumeration value="partial"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="watcher-list">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:watcher" minOccurs="0" maxOccurs=
"unbounded"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="resource" type="xs:anyURI" use="required"/>
<xs:attribute name="package" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="watcher">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:anyURI">
<xs:attribute name="display-name" type="xs:string"/>
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="pending"/>
<xs:enumeration value="active"/>
<xs:enumeration value="waiting"/>
<xs:enumeration value="terminated"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="event" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="subscribe"/>
<xs:enumeration value="approved"/>
<xs:enumeration value="deactivated"/>
<xs:enumeration value="probation"/>
<xs:enumeration value="rejected"/>
<xs:enumeration value="timeout"/>
<xs:enumeration value="giveup"/>
<xs:enumeration value="noresource"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="expiration" type="xs:unsignedLong"/>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="duration-subscribed"
type="xs:unsignedLong"/>
<xs:attribute ref="xml:lang"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>7. Security Considerations
okay this one is SERIOUS bestie 😭🔐 watcher information is sensitive information, full stop. the protocol that distributes it SHOULD ensure privacy, message integrity, and authentication 🛡️ and furthermore, the protocol should provide access controls that restrict who can see whose watcher information. nobody's stalker-ex gets to peek at your followers list 💀🙅♀️
8. IANA Considerations
this document registers a new MIME type, application/watcherinfo+xml, and it also registers a new XML namespace 🎀
8.1. application/watcherinfo+xml MIME Registration
here's the full registration template, copied exactly as the spec has it 📋
MIME media type name: application
MIME subtype name: watcherinfo+xml
Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml
as specified in RFC 3023 [9].
Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023 [9].
Security considerations: See Section 10 of RFC 3023 [9] and
Section 7 of this specification.
Interoperability considerations: none.
Published specification: This document.
Applications which use this media type: This document type has
been used to support subscriber authorization functions for
SIP-based presence [10] [2].
Additional Information:
Magic Number: None
File Extension: .wif or .xml
Macintosh file type code: "TEXT"
Personal and email address for further information: Jonathan
Rosenberg, <jdrosen@jdrosen.net>
Intended usage: COMMON
Author/Change controller: The IETF.8.2. URN Sub-Namespace Registration for urn:ietf:params:xml:ns:watcherinfo
this section registers the new XML namespace, following the guidelines in [7] 🦋
the URI for this namespace is urn:ietf:params:xml:ns:watcherinfo. the registrant contacts are IETF, SIP working group SIMPLE, <simple@ietf.org>, and Jonathan Rosenberg <jdrosen@jdrosen.net> 📬
and here's the XML registration page, verbatim:
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Watcher Information Namespace</title>
</head>
<body>
<h1>Namespace for Watcher Information</h1>
<h2>urn:ietf:params:xml:ns:watcherinfo</h2>
<p>See <a href="ftp://ftp.rfc-editor.org/in-notes/rfc3858.txt">
RFC3858</a>.</p>
</body>
</html>
END9. Normative References
these are the references the spec leans on hardest, so here they all are in full 📚✨
[1] Roach, A. B., "Session Initiation Protocol (SIP)-Specific Event
Notification", RFC 3265, June 2002.
[2] Rosenberg, J., "A Watcher Information Event Template-Package for
the Session Initiation Protocol (SIP)", RFC 3857, August 2004.
[3] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[4] T. Bray, J. Paoli, and C. M. Sperberg-McQueen, "Extensible
Markup language (XML) 1.0 (second edition)," W3C Recommendation
REC-xml-20001006, World Wide Web Consortium (W3C), Oct. 2000.
Available at http://www.w3.org/XML/.
[5] Moats, R., "URN Syntax", RFC 2141, May 1997.
[6] Moats, R., "A URN Namespace for IETF Documents", RFC 2648,
August 1999.
[7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January
2004.
[8] 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.
[9] Murata, M., Laurent, S., and D. Kohn, "XML Media Types", RFC
3023, January 2001.
[10] Rosenberg, J., "A Presence Event Package for the Session
Initiation Protocol (SIP)", RFC 3856, August 2004.10. Informative References
and this one's just for context, not required reading 🧠
[11] Day, M., Rosenberg, J., and H. Sugano, "A Model for Presence and
Instant Messaging", RFC 2778, February 2000.11. Acknowledgements
huge thank-yous to Sean Olson, Steve Donovan, and Cullen Jennings 🫶 the authors say they appreciated their detailed comments and help with the XML schema, and honestly same, that schema is a whole vibe 💜
12. Contributors 🎀
Okay bestie, this is the squad list 🫶 These are the people who were on the original design team and built the very first version of this spec. Look at the Plano crew 😭
Dean Willis
dynamicsoft
5100 Tennyson Parkway, Suite 1200
Plano, Texas 75024
EMail: dwillis@dynamicsoft.comRobert Sparks
dynamicsoft
5100 Tennyson Parkway, Suite 1200
Plano, Texas 75024
EMail: rsparks@dynamicsoft.comBen Campbell
EMail: ben@nostrum.comHenning Schulzrinne
Columbia University
M/S 0401
1214 Amsterdam Ave.
New York, NY 10027-7003
EMail: schulzrinne@cs.columbia.eduJonathan Lennox
Columbia University
M/S 0401
1214 Amsterdam Ave.
New York, NY 10027-7003
EMail: lennox@cs.columbia.eduChristian Huitema
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
EMail: huitema@microsoft.comBernard Aboba
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
EMail: bernarda@microsoft.comDavid Gurle
Reuters Corporation
EMail: David.Gurle@reuters.comJonathan Lennox also wrote the text for the DTD and how it gets used, which showed up in earlier versions of this spec. Main character energy, fr 👑
13. Author's Address 💌
This is the author you'd reach out to, Jonathan Rosenberg 🦋
Jonathan Rosenberg
dynamicsoft
600 Lanidex Plaza
Parsippany, NJ 07054
EMail: jdrosen@dynamicsoft.com14. Full Copyright Statement 📜
Now the legal bits, which are lowkey important even if they're kinda boring 🙈 The copyright is held by The Internet Society, and the year is 2004. Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions in BCP 78, and except for what's set out there, the authors keep all their rights 💅
Also, this doc and everything in it is provided on an "AS IS" basis, and the contributor, the organization they represent or are sponsored by (if any), the Internet Society, and the Internet Engineering Task Force all say, very clearly:
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.
Translation: no guarantees, no promises, nothing. Use it at your own risk 💀
Intellectual Property 🧚
The IETF doesn't take a side on whether any IP rights claimed around the tech in this doc are valid or how far they reach. It also doesn't say whether licenses for those rights are available, and it hasn't done any independent digging to find out what's out there 🤷♀️ If you want to know how rights work for RFC docs, check BCP 78 and BCP 79.
Copies of IPR disclosures sent to the IETF Secretariat, any assurances that licenses will be available, and the results of any attempt to get a general license or permission to use proprietary rights for implementers or users of this spec can all be found on the IETF's online IPR repository at http://www.ietf.org/ipr.
The IETF also invites anyone who knows about copyrights, patents, patent applications, or other proprietary rights that might cover tech needed to implement this standard to let them know. Send that info to the IETF at ietf-ipr@ietf.org 📬
Acknowledgement 🌈
Funding for the RFC Editor function is currently provided by the Internet Society. Thank you, Internet Society, you're the real MVP 💜
📦 where this page comes from
- ietf: rfc3858 2004-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms