Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft: XEP-0372: urn:xmpp:reference:1 #1281

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Draft: XEP-0372: urn:xmpp:reference:1 #1281

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 79 additions & 41 deletions xep-0372.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,21 @@
<supersededby/>
<shortname>Refs</shortname>
&ksmithisode;
<revision>
<version>0.6.0</version>
<date>2023-04-03</date>
<initials>tj</initials>
<remark>
<ul>
<li>Redefine types</li>
<li>Make uri parameter non mandatory</li>
<li>Remove the mentions chapter (defined in another XEP)</li>
<li>Add reference to &xep0426;</li>
<li>Add hreflang attribute</li>
<li>Bump the namespace</li>
</ul>
</remark>
</revision>
<revision>
<version>0.5.0</version>
<date>2020-12-09</date>
Expand Down Expand Up @@ -77,71 +92,58 @@


<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='[email protected]/30d3d8'
to='[email protected]/sabo239'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<p>If an entity implements references, it MUST specify the 'urn:xmpp:reference:1' feature in its service discovery information features as specified in &xep0030; and the Entity Capabilities profile specified in &xep0115;.</p>

<p>If the entity is also implementing specific references profiles, it MUST expose the specific feature defined in the related type.</p>

<example caption='Contact&apos;s client responds with features'><![CDATA[
<example caption='Contact&apos;s client responds with specific features profiles'><![CDATA[
<iq type='result'
id='disco1'
from='[email protected]/sabo239'
to='[email protected]/30d3d8'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:reference:0'/>
<feature var='urn:xmpp:reference:1'/>
<feature var='urn:xmpp:reference:data:1'/>
...
</query>
</iq>
]]></example>
<p>TODO: Individual discovery of reference types - FDP, Mentions, ...</p>
]]></example>
</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='[email protected]'>
<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:[email protected]'/>
</message>
]]></example>
<p>References are provided in a 'reference' element of a message, with a namespace of 'urn:xmpp:reference:1'. The element MUST contain a 'type' attribute denoting the type of the reference. Other profile specific attributes MAY be specified. It also MAY contain 'begin', 'end', 'hreflang' and 'anchor' elements.</p>

<section3 topic="Begin and end attributes" anchor="begin_end">
<p>The character counting is done as specified in &xep0426;. Implementations SHOULD NOT send multiple references with overlapping ranges.</p>
</section3>

<section3 topic="Anchor attribute" anchor="anchor">
<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). Its value is an URI pointing to the reffering 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>
</section3>

<section3 topic="Hreflang attribute" anchor="href_lang">
<p>An implementation MAY use the 'hreflang' attribute to target a message with the corresponding 'xml:lang' attribute, when 'begin' and 'end' attributes are specified.</p>
</section3>
</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>
<p>Data references are a generic reference without additional information. The reference element MUST contain a 'uri' attribute that points to an 'item' that is able to be fetched. This is useful for, for example, fetching an item from Pubsub as defined in <span class='ref'><link url='https://xmpp.org/extensions/xep-0060.html#impl-uri'>Publish-Subscribe (XEP-0060) - Pubsub URIs</link></span>.</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='[email protected]'
to='[email protected]/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'/>
<reference xmlns='urn:xmpp:reference:1'
type='urn:xmpp:reference:data:1'
uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.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>
<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.</p>
<example caption='A MIX Channel annotates a previous user message'><![CDATA[
<message type='groupchat'
id='sotehu-bthbtp32h5'
Expand All @@ -152,7 +154,7 @@
anchor='xmpp:[email protected]?;node=messages;item=bnhob'
begin='72'
end='78'
uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.isode.net/accidentreport;item=ndina872be'/>
uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.net/accidentreport;item=ndina872be'/>
</message>
]]></example>
</section2>
Expand Down Expand Up @@ -184,6 +186,42 @@
<p>Needs a namespace.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>When advanced.</p>
<section2 topic='Reference base schema' anchor='schemas-reference'>
<p>The following schema defines the base reference element.</p>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
xmlns:xhtml='http://www.w3.org/1999/xhtml'
targetNamespace='urn:xmpp:reference:1'
xmlns='urn:xmpp:reference:1'
elementFormDefault='qualified'>

<xs:annotation>
<xs:documentation>
This schema defines the reference element specified in XEP-0372: Reference
</xs:documentation>
<xs:documentation source="http://www.xmpp.org/extensions/xep-0372.html"/>
</xs:annotation>

<xs:element name='reference'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='type' type='xs:string' use='required'/>
<xs:attribute name='begin' type='xs:unsignedInt' use='optional'/>
<xs:attribute name='end' type='xs:unsignedInt' use='optional'/>
<xs:attribute name='anchor' type='xs:string' use='optional'/>
<xs:attribute name='uri' type='xs:string' use='optional'/>
<xs:attribute name='hreflang' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>

</xs:schema>
]]></code>
</section2>
</section1>
</xep>