XEP-0230: Service Discovery Notifications

WARNING: This document has been automatically Deferred after 12 months of inactivity in its previous Experimental state. Implementation of the protocol described herein is not recommended for production systems. However, exploratory implementations are encouraged to resume the standards process.

Table of Contents

1. Introduction

Entity Capabilities (XEP-0115) [1] defines a way for entities to receive dynamically-updated information about Service Discovery (XEP-0030) [2] capabilities, rather than polling for updates by sending repeated disco#info requests. However, there is no comparable method for receiving updated disco#items information (this might be helpful when the number of associated entities is large or dynamic, e.g., at a multi-user chat service). This document specifies such a method by re-using semantics from Publish-Subscribe (XEP-0060) [3].

2. Protocol

Before a requesting entity asks for service discovery items with notifications, it SHOULD send directed presence to the responding entity so that the responding entity knows when to stop sending notifications.

Example 1. Requesting entity sends presence

<presence from='bill@shakespeare.lit/globe' to='chat.shakespeare.lit'/>

The requesting entity then sends a disco#items request to the responding entity, including a <subscribe/> element qualified by the 'http://jabber.org/protocol/pubsub' namespace, which in turn specifies a node of 'http://jabber.org/protocol/disco#items'.

Example 2. Requesting all items

<iq type='get'
    from='bill@shakespeare.lit/globe'
    to='chat.shakespeare.lit'
    id='items1'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <subscribe xmlns='http://jabber.org/protocol/pubsub'
               node='http://jabber.org/protocol/disco#items'/>
  </query>
</iq>

If the responding entity does not recognize inclusion of the <subscribe/> element as a child of the <query/> element, it MUST return the service discovery items but MUST NOT send subsequent notifications to the requesting entity.

If the requesting entity did not share presence with the responding entity, the responding entity MUST return the service discovery items but SHOULD NOT send subsequent notifications to the requesting entity.

If the responding entity recognizes inclusion of the <subscribe/> element as a child of the <query/> element and the requesting entity is allowed to receive notifications, the responding entity MUST return the service discovery items (including a <subscription/> element) and SHOULD send subsequent notifications to the requesting entity.

Example 3. Result-set for all items

<iq type='result'
    from='chat.shakespeare.lit'
    to='bill@shakespeare.lit/globe'
    id='items1'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='alls-well-that-ends-well@chat.shakespeare.lit'/>
    <item jid='as-you-like-it@chat.shakespeare.lit'/>
    <item jid='cleopatra@chat.shakespeare.lit'/>
    <item jid='comedy-of-errors@chat.shakespeare.lit'/>
    <item jid='coriolanus@chat.shakespeare.lit'/>
    <item jid='cymbeline@chat.shakespeare.lit'/>
    <item jid='hamlet@chat.shakespeare.lit'/>
    <item jid='henry-the-fourth-one@chat.shakespeare.lit'/>
    <item jid='henry-the-fourth-two@chat.shakespeare.lit'/>
    <item jid='henry-the-fifth@chat.shakespeare.lit'/>
    <subscription
        xmlns='http://jabber.org/protocol/pubsub'
        jid='bill@shakespeare.lit'
        subid='some-long-sub-id'
        subscription='subscribed'/>
  </query>
</iq>

The responding entity then SHOULD send subsequent notifications to the requesting entity when associated items are added to or deleted from the potential result set.

Example 4. A notification (new item)

<message from='chat.shakespeare.lit' to='bill@shakespeare.lit' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/disco#items'>
      <item id='ae890ac52d0df67ed7cfdf51b644e901'>
        <item xmlns='http://jabber.org/protocol/disco#items'
              jid='henry-the-fifth@chat.shakespeare.lit'/>
      </item>
    </items>
  </event>
</message>

Example 5. A notification (deleted item)

<message from='chat.shakespeare.lit' to='bill@shakespeare.lit' id='bar'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/disco#items'/>
      <retract id='fa890ca52d0df67de7fcfd51b644c701'>
        <item xmlns='http://jabber.org/protocol/disco#items'
              jid='cardenio@chat.shakespeare.lit'/>
      </retract>
    </items>
  </event>
</message>

When the requesting entity goes offline, the responding entity will receive unavailable presence.

Example 6. Responding entity receives unavailable presence

<presence from='bill@shakespeare.lit/globe'
          to='chat.shakespeare.lit'
          type='unavailable'/>

The responding entity then MUST NOT send further notifications.

3. Security Considerations

This document introduces no new security considerations above and beyond those already defined for service discovery and publish-subscribe.

4. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [4].

5. XMPP Registrar Considerations

This document requires no interaction with the XMPP Registrar [5].

Appendices

Appendix A: Document Information

Series: XEP
Number: 0230
Publisher: XMPP Standards Foundation
Status: Deferred
Type: Standards Track
Version: 0.1.2
Last Updated: 2018-09-08
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0030, XEP-0060
Supersedes: None
Superseded By: None
Short Name: NOT YET ASSIGNED
Source Control: HTML
This document in other formats: XML  PDF

Appendix B: Author Information

Appendix C: Legal Notices

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

END