xep-0372.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'?>
<?xml-stylesheet type="text/css" href="xmpp.css"?>
<xep>
<header>
  <title>References</title>
  <abstract>This document defines a method for one XMPP stanza to provide references to another entity, such as mentioning users, HTTP resources, or other XMPP resources.</abstract>
  &LEGALNOTICE;
  <number>0372</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0030</spec>
    <spec>XEP-0115</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>Refs</shortname>
  &ksmithisode;
  <revision>
    <version>0.5.0</version>
    <date>2020-12-09</date>
    <initials>kis</initials>
    <remark>Specify counting should be of code points.</remark>
  </revision>
  <revision>
    <version>0.4.0</version>
    <date>2020-12-08</date>
    <initials>gh/jcbrand</initials>
    <remark>Specify that begin is inclusive, starts counting at zero, and that end is exclusive (Dijkstra-based convention).</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2019-09-04</date>
    <initials>(mb)</initials>
    <remark>Make Pubsub URIs in sections 3.3 and 3.4 conform to XEP-0147.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2017-09-11</date>
    <initials>XEP Editor (jwi)</initials>
    <remark>Defer due to lack of activity.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2016-03-22</date>
    <initials>XEP Editor (asw)</initials>
    <remark><p>Initial published version approved by the XMPP Council.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2016-01-29</date>
    <initials>kis</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>
    It's often desirable to encode a reference to another entity within a chat message and to mark up the reference. Examples of this include HTTP URLs, 'mentions' (referring to another user), references to previous messages and references to &xep0346; (FDP) forms. This document provides a mechanism for marking up a section of a message body with information about the target of the reference.
  </p>
</section1>

<!--<section1 topic='Requirements' anchor='reqs'>
  <ul>
    <li></li>
 </ul>
</section1>-->



<section1 topic='Discovery' anchor='discovery'>
  <p>If a client implements references, it MUST specify the 'urn:xmpp:reference:0' feature in its service discovery information features as specified in &xep0030; and the Entity Capabilities profile specified in &xep0115;.</p>
  <example caption='Client queries for contact&apos;s features'><![CDATA[
<iq type='get'
    id='disco1'
    from='romeo@montegue.lit/30d3d8'
    to='juliet@capulet.lit/sabo239'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>

<example caption='Contact&apos;s client responds with features'><![CDATA[
<iq type='result'
    id='disco1'
    from='juliet@capulet.lit/sabo239'
    to='romeo@montegue.lit/30d3d8'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:reference:0'/>
    ...
  </query>
</iq>
]]></example>
<p>TODO: Individual discovery of reference types - FDP, Mentions, ...</p>
</section1>

<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Generics' anchor='usecase_generics'>
    <p>References are provided in a 'reference' element of a message, with a namespace of 'urn:xmpp:reference:0'. The element MUST contain a 'type' attribute denoting the type of the reference and a 'uri' attribute of the thing that is referenced. It MAY contain 'begin', 'end' and 'anchor' elements.</p>
    <p>The 'begin' and 'end' attributes are indexes denoting the beginning and end of the referenced substring in the message body. The Dijkstra convention of ranges<note>Dijkstra convention of ranges &lt;<link url='https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html'>https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html</link>&gt;</note> is used, which means that 'begin' is inclusive and 'end' is exclusive. In other words, the 'begin' attribute is the index of the first unicode code point in the referenced substring, with 0 being the index of the first code point in the body, and the 'end' attribute is one higher than the index of the last code point in the substring.
       This convention has three main advantages. It matches subsequence indexing in various programming languages, 'end' minus 'begin' equals the length of the substring, and when two substrings are adjacent, the 'end' attribute of the first one matches the 'begin' attribute of the second one.
       Where the reference is not a substring of the message body in the referring stanza, 'begin' and 'end' are not used.</p>
    <p>An 'anchor' attribute is used when the referring message is not the one containing the reference element, and points to the previous message containing the reference (the referring message).</p>
    <p>Note that the URIs of the reference and anchor do not need to refer to the same mechanism as that in which the reference was received. E.g., a service could listen for mentions in a MIX channels of users outside that channel, and send them messages containing a reference to let them know that they've been mentioned.</p>
  </section2>
  <section2 topic='Mentions' anchor='usecase_mention'>
    <p>Mentions are a reference to a user's bare JID, and have a type of 'mention'.</p>
    <example caption='Romeo sends a message mentioning Juliet'><![CDATA[
<message type='groupchat'
         id='sotehu-bthbtp32h3'
         to='balcony@channels.shakespeare.lit'>
  <body>But, soft! what light through yonder window breaks? It is the east, and Juliet is the sun.</body>
  <reference xmlns='urn:xmpp:reference:0'
             begin='72'
             end='78'
             type='mention'
             uri='xmpp:juliet@capulet.lit'/>
</message>
]]></example>
  </section2>
  <section2 topic='Data' anchor='usecase_data'>
    <p>Data references are a generic reference without additional information. The URI points to an 'item' that is able to be fetched. This is useful for, for example, fetching an item from pubsub, as in the example below. TODO: check URI syntax for refering to a pubsub item.</p>
    <example caption='A MIX Channel sends a message that a new FDP form has been submitted elsewhere'><![CDATA[
<message type='groupchat'
         id='sotehu-bthbtp32h4'
         from='balcony@channels.shakespeare.lit'
         to='romeo@montegue.lit/30d3d8'>
  <body>Form received</body>
  <reference xmlns='urn:xmpp:reference:0'
             type='data'
             uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.isode.net/accidentreport;item=ndina872be'/>
</message>
]]></example>
  </section2>
  <section2 topic='Previous messages' anchor='usecase_previous'>
    <p>Sometimes it's desirable to annotate a reference in a previous message. An example of this might be where a MIX channel asynchronously adds information about references made in previous messages by users. In this case the message MUST NOT contain a body. Here the anchor attribute is used to provide a URI to the previous message. TODO: URI scheme for messages.</p>
    <example caption='A MIX Channel annotates a previous user message'><![CDATA[
<message type='groupchat'
         id='sotehu-bthbtp32h5'
         from='balcony@channels.shakespeare.lit'
         to='romeo@montegue.lit/30d3d8'>
  <reference xmlns='urn:xmpp:reference:0'
             type='data'
             anchor='xmpp:balcony@channels.shakespeare.lit?;node=messages;item=bnhob'
             begin='72'
             end='78'
             uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.isode.net/accidentreport;item=ndina872be'/>
</message>
]]></example>
  </section2>

</section1>


<!--<section1 topic='Business Rules' anchor='rules'>
  <ul>
    <li>.</li>
  </ul>
</section1>-->
<!--<section1 topic='Implementation Notes' anchor='impl'>
  <p>OPTIONAL.</p>
</section1>
<section1 topic='Accessibility Considerations' anchor='access'>
  <p>OPTIONAL.</p>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
  <p>OPTIONAL.</p>
</section1>-->
<section1 topic='Security Considerations' anchor='security'>
  <p>TODO.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>None.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>Needs a namespace.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <p>When advanced.</p>
</section1>
</xep>