xep-0499.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Pubsub Extended Discovery</title>
  <abstract>This specification extends the discovery requests used with the XMPP PubSub protocol by introducing mechanisms to discover linked nodes, descendants, or metadata.</abstract>
  &LEGALNOTICE;
  <number>0499</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0001</spec>
    <spec>XEP-0060</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>pubsub-ext-disco</shortname>
  <author>
    <firstname>Jérôme</firstname>
    <surname>Poisson</surname>
    <email>goffi@goffi.org</email>
    <jid>goffi@jabber.fr</jid>
  </author>
  <revision>
    <version>0.1.0</version>
    <date>2024-11-20</date>
    <initials>XEP Editor: dg</initials>
    <remark>
      <p>Promoted to Experimental</p>
    </remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2024-10-17</date>
    <initials>jp</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
<p>With the introduction of XEP-xxxx: Pubsub Node Relationships, it becomes necessary to discover child or linked nodes, enabling an entity to discover a tree-like structure and other related nodes. This specification extends the node discovery functionality in &xep0060; by allowing entities to discover linked nodes and descendants when performing a disco#items request. It also allows filtering to specify what the requestor is interested in, and adds metadata to identify the relationships between discovered nodes.</p>
</section1>

<section1 topic='Requirements' anchor='reqs'>
  <p>The design goals of this XEP are:</p>
  <ul>
    <li>To ensure backward compatibility with existing implementations.</li>
    <li>To provide a mechanism for discovering linked nodes and descendants during a disco#items request.</li>
    <li>To allow control over the depth of descendant discovery.</li>
    <li>To provide metadata about the relationships between nodes in the discovery results.</li>
  </ul>
</section1>

<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Discovering Linked Nodes and Descendants' anchor='discover'>
    <p>An entity can request to discover linked nodes and descendants by including a data form in the disco#items request. The form uses the namespace "urn:xmpp:pubsub-ext-disco:0" and MAY include the following fields:</p>
    <ul>
      <li><strong>type</strong>: A "list-multi" field that indicates what kind of items should be returned. The values for this field MUST be either "items" or "nodes", and it defaults both "items" and "nodes". If "items" is selected, pubusb node items are returned; if "nodes" is selected, pubsub nodes are returned. Pubsub items MUST NOT be returned if "items" is not selected, and pubsub nodes MUST NOT be returned if "nodes" is not selected.</li>
      <li><strong>linked_nodes</strong>: A boolean field that, when set to "true", indicates that linked nodes and/or their items should be included in the discovery results. The default value of this field MUST be "false".</li>
       <li><strong>full_metadata</strong>: A boolean field that, when set to 'true', indicates that the full node metadata form (as specified in <link url="https://xmpp.org/extensions/xep-0060.html#entity-metadata">XEP-0060 §5.4 Discover Node Metadata</link>) MUST be included with each discovered node. If this field is set to 'false', the Pubsub/PEP service MUST return only the necessary relationship fields ('{urn:xmpp:pubsub-relationships:0}parent' and/or '{urn:xmpp:pubsub-relationships:0}link'). The default value of this field MUST be 'false'.</li>
      <li><strong>depth</strong>: A "text-single" field that specifies the number of layers of descendants to include. The value must be castable to an integer and defaults to 0. If the "linked_nodes" field is set to "false", descendant linked nodes (i.e., descendant nodes with a set "{urn:xmpp:pubsub-relationships:0}link" field) MUST NOT be included.</li>
    </ul>

    <p>If the "urn:xmpp:pubsub-ext-disco:0" data form is present in the disco#items request, the rules differ from those specified in &xep0060;: contrary to what is outlined in <link url="https://xmpp.org/extensions/xep-0060.html#entity-discoveritems">§5.5 Discover Items for a Node</link>, the "node" attribute MUST be specified for all items as it is necessary to know to which pubsub node a pubsub item is attached.</p>
    <p>If a disco item is actually a pubsub node, a metadata form (as specified in <link url="https://xmpp.org/extensions/xep-0060.html#entity-metadata">XEP-0060 §5.4 Discover Node Metadata</link>) MUST be included as a child of the disco &lt;item&gt; element.</p>
    <p>If the 'full_metadata' field in the request's data form is set to "true", the full node metadata form MUST be included with each discovered node. If this field is set to "false", only the necessary relationship fields ("{urn:xmpp:pubsub-relationships:0}parent" and/or "{urn:xmpp:pubsub-relationships:0}link") MUST be returned.</p>
    <p>If the item is a child node, its "{urn:xmpp:pubsub-relationships:0}parent" field MUST be present, and if it is a linked node, its "{urn:xmpp:pubsub-relationships:0}link" field MUST be present. This data form is necessary to identify the item as a pubsub node and to see its relationships, allowing the requestor to build the hierarchy.</p>

    <example caption="Entity Requests Discovery of Linked Nodes and Descendants"><![CDATA[
<iq type='get'
  from='romeo@example.net/orchard'
  to='juliet@example.org'
  id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#items' node='urn:xmpp:microblog:0'>
  <x xmlns='jabber:x:data' type='submit'>
    <field var='FORM_TYPE' type='hidden'>
      <value>urn:xmpp:pubsub-ext-disco:0</value>
    </field>
    <field var='type'>
      <value>nodes</value>
    </field>
    <field var='linked_nodes'>
      <value>true</value>
    </field>
    <field var='depth'>
      <value>1</value>
    </field>
  </x>
</query>
</iq>
    ]]></example>

  <example caption="PEP Service Returns Discovery Results With Linked Nodes and First Level Descendants"><![CDATA[
<iq type='result'
  from='juliet@example.org'
  to='romeo@example.net/orchard'
  id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#items' node='urn:xmpp:microblog:0'>
  <item jid='juliet@example.org' node='urn:xmpp:microblog:0:comments/balcony-restoration-afd1'>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/pubsub#meta-data</value>
      </field>
      <field var='{urn:xmpp:pubsub-relationships:0}parent'>
        <value>urn:xmpp:microblog:0</value>
      </field>
    </x>
  </item>
  <item jid='juliet@example.org' node='urn:xmpp:pubsub-attachments:1/xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=balcony-restoration-afd1'>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/pubsub#meta-data</value>
      </field>
      <field var='{urn:xmpp:pubsub-relationships:0}link'>
        <value>urn:xmpp:microblog:0</value>
      </field>
    </x>
  </item>
</query>
</iq>
  ]]></example>
  </section2>
</section1>

<section1 topic='Business Rules' anchor='rules'>
  <ul>
    <li>The result described in this specification MUST NOT be used if the "urn:xmpp:pubsub-ext-disco:0" is missing from the disco#items requests. This is to ensure backward compatibility.</li>
    <li>The service MUST respect the access model of each node when returning discovery results. If an entity does not have permission to access a node, it MUST NOT be included in the results.</li>
    <li>As the result could include a lot of disco &lt;items&gt;, &xep0059; SHOULD be used by the PEP/Pubsub service to handle a large number of discovered items.</li>
  </ul>
</section1>

<section1 topic="Discovering Support" anchor="disco">
  <p>If a pubsub/PEP service supports the protocol specified in this XEP, it MUST advertise it by including the "urn:xmpp:pubsub-ext-disco:0" discovery feature in response to a <span class="ref"><link url="https://xmpp.org/extensions/xep-0030.html">Service Discovery (XEP-0030)</link></span> <note>XEP-0030: Service Discovery &lt;<link url="https://xmpp.org/extensions/xep-0030.html">https://xmpp.org/extensions/xep-0030.html</link>&gt;.</note> information request.</p>

  <example caption="Service Discovery Information Request"><![CDATA[
<iq type='get'
    from='juliet@example.org/balcony'
    to='pubsub.example.org'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
  <example caption="Service Discovery Information Response"><![CDATA[
<iq type='result'
    from='pubsub.example.org'
    to='juliet@example.org/balcony'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:pubsub-ext-disco'/>
    ...
  </query>
</iq>]]></example>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>This extension does not introduce any new security considerations beyond those already present in &xep0060;. However, implementers should be aware that including linked nodes and descendants in discovery results may expose more information about the node structure than a basic disco#items request. Services MUST ensure that they respect the access controls of all nodes when returning discovery results.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document does not require interaction with &IANA;.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>TODO</p>
</section1>

<section1 topic='Acknowledgements' anchor='acks'>
  <p>Thanks to NLNet foundation/NGI Zero Core for funding the work on this specification.</p>
</section1>

</xep>