An Extensible Markup Language (XML) Based Format for Watcher Information
Extracted elements (22)
Authorization controls the set of watchers visible in a given watcherinfo document: a non-owner subscriber (e.g., user A watching user B) sees only their own watcher entry, while the resource owner (user B) sees all watchers, and an administrator may see watchers across all resources.
The document uses partial vs. full state to minimize bandwidth: NOTIFYs typically carry only changed watcher state, and the subscriber reconstructs the full view by merging updates into a local table keyed by watcher ID. A version number enables detection of missed notifications and triggers refresh.
The watcher URI is specified as an address-of-record rather than a device address because it represents the authenticated identity assigned by the server, providing a stable, consistent identifier across devices for the same user.
Elements or attributes from namespaces other than 'urn:ietf:params:xml:ns:watcherinfo' MAY be present for extensibility; implementations MUST ignore unknown namespace elements and attributes to remain forward-compatible.
A watcher information XML document MUST be well-formed and SHOULD be valid. It MUST be based on XML 1.0 and MUST be encoded using UTF-8.
Each 'watcher-list' element MUST have both the 'resource' (URI) and 'package' (event package token) attributes present.
If the version in a received document is less than the local version number, the document MUST be discarded without processing.
The URI value of the 'watcher' element SHOULD be the authenticated identity of the watcher as determined by the server, typically an address-of-record rather than a device address.
The 'version' attribute on the 'watcherinfo' element MUST be representable using a 32-bit integer and does not wrap. Versions start at 0 and increment by one for each new document sent to a watcherinfo subscriber.
The 'watcher' element MUST have three attributes present: 'id', 'status', and 'event'. The 'id' MUST be unique across all other watchers reported for a particular watcherinfo subscription and MUST conform to the RFC 3261 token grammar.
The 'watcherinfo' element MUST carry both the 'version' and 'state' attributes; their absence is a schema violation. Elements or attributes from unknown namespaces MUST be ignored to allow extensibility.
When a watcherinfo subscriber receives a document whose version is more than one higher than the local version, the subscriber SHOULD generate a refresh request to trigger a full state notification.
The root element 'watcherinfo' carries a mandatory 'version' (non-negative integer, 32-bit max) and a mandatory 'state' attribute (enumerated: 'full' or 'partial'). It contains zero or more 'watcher-list' child elements.
The 'state' attribute on 'watcherinfo' distinguishes full state documents (the subscriber should flush and repopulate all tables) from partial state documents (only changed watchers are included and existing table rows are updated).
The 'version' attribute allows ordering of watcherinfo documents within a subscription scope. Versions start at 0, increment by 1 per document, and are scoped to a single watcherinfo subscription; they do not wrap even though stored as a 32-bit integer.
The 'watcher' element describes a single watcher subscription. Its text content is the watcher's URI. Mandatory attributes: 'id' (token), 'status' (pending|active|waiting|terminated), 'event' (subscribe|approved|deactivated|probation|rejected|timeout|giveup|noresource). Optional attributes: 'display-name', 'expiration' (seconds), 'duration-subscribed' (seconds), 'xml:lang'.
The 'watcher-list' element groups watchers for a single resource. Mandatory attributes are 'resource' (xs:anyURI) identifying the watched resource, and 'package' (xs:string) identifying the event package.
RFC 3858 registers the MIME media type 'application/watcherinfo+xml' with IANA. Optional parameters follow application/xml (RFC 3023); file extensions are .wif or .xml.
RFC 3858 registers the XML namespace URN 'urn:ietf:params:xml:ns:watcherinfo' in the IETF XML Registry per RFC 3688. The registrant contact is the IETF SIMPLE working group.
Watcher information is sensitive because it reveals who is monitoring a resource. The distribution protocol SHOULD ensure privacy, message integrity, and authentication, and SHOULD implement access controls restricting which subscribers can see watcher information for a given resource.
A watcher's subscription has four states: 'pending' (authorization not yet granted), 'active' (subscription approved and active), 'waiting' (subscription terminated but resource is willing to send notification if authorization granted later), and 'terminated' (subscription ended). Transitions are triggered by events: subscribe, approved, deactivated, probation, rejected, timeout, giveup, noresource.
Watcher information is encoded as an XML document in the namespace 'urn:ietf:params:xml:ns:watcherinfo', carried with MIME type 'application/watcherinfo+xml'. Encoding follows application/xml rules from RFC 3023 (UTF-8 mandatory per Section 3).