Mercurial > sat_docs
view xmpp/xep-proto-jid-mention.xml @ 119:5d2eb2f61dc8
docker (base): Twisted and Wokkel are now installed with pip instead of apt, as Jessie version is too old for SàT
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Tue, 08 Mar 2016 18:36:14 +0100 |
| parents | 16ce0419a0e9 |
| children |
line wrap: on
line source
<?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>JID Mention</title> <abstract>This specification provides a way for an entity to mention a jid</abstract> &LEGALNOTICE; <number>xxxx</number> <status>ProtoXEP</status> <type>Standards Track</type> <sig>Standards</sig> <approver>Council</approver> <dependencies> <spec>XMPP Core</spec> </dependencies> <supersedes/> <supersededby/> <shortname>NOT_YET_ASSIGNED</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</version> <date>2016-01-16</date> <initials>jp</initials> <remark><p>First draft.</p></remark> </revision> </header> <section1 topic='Introduction' anchor='intro'> <p>Mentioning somebody is usually done in the context of a multi-user chat: a notification is triggered when somebody's nickname is written, and it often only works when a client is online and monitoring the conversation.</p> <p>But it is more and more common to mention people in other contexts (e.g. microblogging), and it is desirable that this works even when an entity is offline or not aware of the context. This XEP offers a simple solution to mention people in any context, online or offline and even outside of XMPP.</p> </section1> <section1 topic='Requirements' anchor='reqs'> <p>JID mention must:</p> <ul> <li>work online and offline</li> <li>work if the entity is not aware of the context</li> <li>work outside of XMPP context (e.g. in a website)</li> <li>not be tied to a particular syntax</li> <li>(desirable) be easy to implement</li> </ul> </section1> <section1 topic='Glossary' anchor='glossary'> <ul> <li><strong>Mentioning entity</strong> — the entity which wants to mention somebody.</li> <li><strong>Mentioned entity</strong> — the entity actually mentioned.</li> <li><strong>Mentioned URI</strong> — URI where the entity is mentioned.</li> <li><strong>PubSub</strong> — &xep0060;.</li> <li><strong>MUC</strong> — &xep0045;.</li> <li><strong>MIX</strong> — &xep0369;.</li> </ul> </section1> <section1 topic='Mentioning an entity' anchor='mention'> <section2 topic='Basic syntax' anchor='base'> <p>The syntax used by the software willing to mention a jid is up to the implemention. Nickname followed by "<strong>:</strong>" is commonly used in group chats like MUC or Internet Relay Chat (IRC) while "<strong>@</strong>" followed by nickname is often used with microblogging. Note that if it is not possible to associate a nickname with a jid without ambiguity, a bare jid SHOULD be used instead of a nickname.</p> <p>To mention an entity, a &MESSAGE; stanza must be sent to the bare jid of the entity with a <mention/> elements which MUST have the <strong>'urn:xmpp:mention:0'</strong> namespace. The <mention/> element MUST have a 'uri' attribute which links to the context where the entity has been mentioned. This URI can be the URI of a MUC room, a PubSub node, a Jingle file (e.g. a photo where mentioned entity appears), a website, or anything which makes sense. A <body/> element MUST be present with a human readable text indicating the mentioned URI (e.g. “You have been mentioned on xmpp:xsf@muc.xmpp.org?join”). No other elements or attributes are mandatory.</p> <example caption='basic mention of Juliet'><![CDATA[ <message from='romeo@montage.net' to='juliet@capulet.lit' id='123'> <mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join' /> <body> You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join </body> </message> ]]></example> </section2> <section2 topic='Context parents' anchor='parents'> <p>Sometime the 'uri' refers to an element which is a child of other one(s). For instance, a mentioned URI may refer to a website comment with a direct link, which is a part of a more general conversation, or PubSub URI refers to a microblog comment which is a child of another comment, itself a child of the main item.</p> <p>In this case, it is desirable for the mentioned entity to know where is the main item, so it can understand the whole context. To deal with this, the mentioning entity MAY declare the path to the uri by adding a <parents/> element which MUST contain one or more <parent/> elements. Each <parent/> element MUST contain an 'uri' attribute with the URI of the parent. If more than one parents are specified, they MUST be put in order, from the more distant one to the last child just before the one specified in the main <mention/> element.</p> <example caption='mention of Juliet in microblog comments'><![CDATA[ <message from='romeo@montage.net' to='juliet@capulet.lit' id='123'> <mention xmlns='urn:xmpp:mention:0' uri='xmpp:pubsub.montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0%3Acomments%2Fdd88c9bc58886fce0049ed050df0c5f2'> <parents> <parent uri='xmpp:romeo%40montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=2ze57d9c-1c46-21df-830c-002143d3d2qgf' /> </parents> </mention> <body> You have been mentioned on xmpp:pubsub.montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0%3Acomments%2Fdd88c9bc58886fce0049ed050df0c5f2 </body> </message> ]]></example> </section2> <section2 topic='Context hint' anchor='context'> <p>To help the mentioned entity understand the context, the mentioning entity MAY add a <context> element which include human readable text. What is inside is at the discretion of the mentioning entity, it MAY be the paragraph where the entity is mentioned, or anything useful.</p> <example caption='mention with context hint'><![CDATA[ <message from='juliet@capulet.lit' to='romeo@montage.net' id='123'> <mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join'> <context> O Romeo, Romeo! wherefore art thou Romeo? Deny thy father and refuse thy name! Or, if thou wilt not, be but sworn my love, And I'll no longer be a Capulet. </context> </mention> <body> You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join </body> </message> ]]></example> </section2> <section2 topic='Mention author' anchor='author'> <p>If the mention is done outside of XMPP context (e.g.: on a website), the 'from' attribute of the message may be the jid of a server component or a bot. In this case, the mentioning entity can give information on the real author of the mention.</p> <p>The author of the mention MAY be specified in <author/> element. If present, it MUST contain one or more of the following elements:</p> <ul> <li><em>JID</em> — the user jid, in a <jid/> element</li> <li><em>email</em> — the user email address, in a <email/> element</li> <li><em>Full Name</em> — the user full name, in a <name/> element</li> <li><em>Nickname</em> — the user nickname, in a <nick/> element</li> </ul> <example caption='mention with its author'><![CDATA[ <message from='xmpp_bot.shakespeare.example.net' to='juliet@capulet.lit' id='123'> <mention xmlns='urn:xmpp:mention:0' uri='https://www.ball.shakespeare.example.net'> <author> <name>Lord Capulet</name> <jid>capulet@capulet.lit</jid> </author> </mention> <body> You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join </body> </message> ]]></example> </section2> <section2 topic='Mentioned part' anchor='part'> <p>In some contexts, an URI may not be sufficient to locate the exact place of the mention. For instance, it may be useful to know the exact message of a MUC room where the mention did take place. If a mentioning entity wants to specify the exact part of the location where the mention happened, it MAY use a <part/> element. This element contains information dependent on the mentioned URI. For now, only stanza-id is used, but later versions of this specification, or other XEPs can add new elements.</p> <p>If the mentioned URI refers to an XMPP context (e.g. a MUC room), a stanza id can be specified. To do so, the &xep0359; semantic is used: mentioning entity MAY add a <stanza-id/> element to the <part/> element as specified in XEP-0359.</p> <example caption='mention with context hint'><![CDATA[ <message from='juliet@capulet.lit' to='romeo@montage.net' id='123'> <mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join'> <context> O Romeo, Romeo! wherefore art thou Romeo? Deny thy father and refuse thy name! Or, if thou wilt not, be but sworn my love, And I'll no longer be a Capulet. </context> <part> <stanza-id xmlns='urn:xmpp:sid:0' id='4b3ec1b6-10ca-498a-af20-378ffaaafddd' by='balcony@chat.shakespeare.lit'/> </part> </mention> <body> You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join </body> </message> ]]></example> </section2> </section1> <section1 topic='Configuration' anchor='configuration'> <p>A server MAY provide a way for clients to configure their notifications (e.g. send by email instead of XMPP, accept mentions only from entities in the roster). To do so, the &xep0050; is used on the well-defined command node <strong>'urn:xmpp:mention:0#configure'</strong>.</p> </section1> <section1 topic='Discovering Support' anchor='disco'> <section2 topic='Announce' anchor='disco_announce'> <p>If a entity supports the JID mention protocol, it MUST report that fact by including a service discovery feature of "<em>urn:xmpp:mention:0</em>" in response to a &xep0030; information request:</p> <example caption="service discovery information request"><![CDATA[ <iq from='kingclaudius@shakespeare.lit/castle' id='disco1' to='laertes@shakespeare.lit/castle' type='get'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq> ]]></example> <example caption="service discovery information response"><![CDATA[ <iq from='laertes@shakespeare.lit/castle' id='disco1' to='kingclaudius@shakespeare.lit/castle' type='result'> <query xmlns='http://jabber.org/protocol/disco#info'> ... <feature var='urn:xmpp:mention:0'/> ... </query> </iq> ]]></example> </section2> <section2 topic='Configuration' anchor='disco_config'> <p>A server doesn't have to announce JID mention namespace as it is a client feature, but if it offers a configuration node as specified in the <link url='#configuration'>configuration section</link>, it MUST announce this fact by including a service discovery feature of "<em>urn:xmpp:mention:0#configure</em>".</p> </section2> </section1> <section1 topic='Business Rules' anchor='rules'> <ol> <li>In the case of group chat like MUC or MIX, most of clients already monitor conversations and notify the user if he is mentioned. To avoid to deal with double notifications, the mentioning entity SHOULD NOT mention an other entity using this XEP if the mentioned entity is online and following the conversation (i.e. it joined the MUC room or it subscribed to the MIX conversation).</li> <li>On the other hand, if the mentioned entity is not following the conversation (i.e. it didn't joined the MUC room, or it didn't subscribed to the MIX conversation), the mentioning entity SHOULD use this XEP for the mention.</li> </ol> </section1> <section1 topic='Security Considerations' anchor='security'> <ol> <li>To avoid spamming (e.g. a mention of an entity redirecting to an advertisement), a server SHOULD allow a mentioned entity to black list mentioning entities, or to accept mentions only from some entities (e.g. entities in roster). See the <link url='#configuration'>configuration section</link> to see how to set it up. A client MAY offer the same kind of feature, but filtering is preferably done on server side to avoid useless traffic.</li> <li>As a mention can link to malicious content, or a user may not want to join a context (and show its presence at the same time), a client SHOULD NOT open automatically the mentioned URI. Instead it SHOULD show a notification to the user, with context hint when available, and propose to join the context or not.</li> <li>When an author is specified as explained in <link url='#author'>mention author section</link>, the elements, notably the <jid> element, are not checked. A malicious mentioning entity could use fake author information to fool mentioned entity. To avoid this, the mentioned entity's client SHOULD display a warning, like an icon or a message, to indicate that the author can't be checked.</li> </ol> </section1> <section1 topic='IANA Considerations' anchor='iana'> <p>This document requires no interaction with &IANA;.</p> </section1> <section1 topic='XMPP Registrar Considerations' anchor='registrar'> <section2 topic='Protocol Namespaces' anchor='ns'> <p>The ®ISTRAR; includes 'urn:xmpp:mention:0' in its registry of protocol namespaces (see &NAMESPACES;).</p> <ul> <li>urn:xmpp:mention:0</li> </ul> </section2> <section2 topic='Protocol Versioning' anchor='registrar-versioning'> &NSVER; </section2> </section1> <section1 topic='XML Schema' anchor='schema'> <code><![CDATA[ <?xml version='1.0' encoding='UTF-8'?> <xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema' targetNamespace='urn:xmpp:mention:0' xmlns='urn:xmpp:mention:0' elementFormDefault='qualified'> <xs:import namespace='urn:xmpp:sid:1' schemaLocation='http://xmpp.org/schemas/sid.xsd'/> <xs:element name='mention'> <xs:complexType> <xs:attribute name='uri' use='required' type='xs:string'/> <xs:element name='parents' minOccurs='0' maxOccurs='1'> <xs:element name='parent' minOccurs='1' maxOccurs='unbounded'> <xs:attribute name='uri' use='required' type='xs:string'/> </xs:element> </xs:element> <xs:element name='context' minOccurs='0' maxOccurs='1'> <xs:complexType> <xs:simpleContent> <xs:extension base='xs:string' /> </xs:simpleContent> </xs:complexType> </xs:element> <xs:element name='author' minOccurs='0' maxOccurs='1'> <xs:complexType> <xs:sequence> <xs:choice minOccurs='1' maxOccurs='unbounded'> <xs:element ref='jid'/> <xs:element ref='email'/> <xs:element ref='name'/> <xs:element ref='nick'/> </xs:choice> </xs:sequence> </xs:complexType> </xs:element> <xs:element name='part' minOccurs='0' maxOccurs='1'> <xs:complexType> <xs:sequence> <xs:choice minOccurs='1' maxOccurs='unbounded'> <xs:element ref='urn:xmpp:sid:1' /> </xs:choice> </xs:sequence> </xs:complexType> </xs:element> </xs:complexType> </xs:element> </xs:schema> ]]></code> </section1> <section1 topic='Acknowledgements' anchor='acks'> <p>Thanks to Adrien Cossa for his review/corrections.</p> </section1> </xep>