XEP-xxxx: JID Mention

Abstract:This specification provides a way for an entity to mention a jid
Author:Jérôme Poisson
Copyright:© 1999 - 2016 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:ProtoXEP
Type:Standards Track
Version:0.1
Last Updated:2016-01-16

WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Table of Contents


1. Introduction
2. Requirements
3. Glossary
4. Mentioning an entity
    4.1. Basic syntax
    4.2. Context parents
    4.3. Context hint
    4.4. Mention author
    4.5. Mentioned part
5. Configuration
6. Discovering Support
    6.1. Announce
    6.2. Configuration
7. Business Rules
8. Security Considerations
9. IANA Considerations
10. XMPP Registrar Considerations
    10.1. Protocol Namespaces
    10.2. Protocol Versioning
11. XML Schema
12. Acknowledgements

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History


1. Introduction

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.

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.

2. Requirements

JID mention must:

3. Glossary

4. Mentioning an entity

4.1 Basic syntax

The syntax used by the software willing to mention a jid is up to the implemention. Nickname followed by ":" is commonly used in group chats like MUC or Internet Relay Chat (IRC) while "@" 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.

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 'urn:xmpp:mention:0' 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.

Example 1. basic mention of Juliet

<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>

4.2 Context parents

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.

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.

Example 2. mention of Juliet in microblog comments

<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>

4.3 Context hint

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.

Example 3. mention with context hint

<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>

4.4 Mention author

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.

The author of the mention MAY be specified in <author/> element. If present, it MUST contain one or more of the following elements:

Example 4. mention with its author

 <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>
			  

4.5 Mentioned part

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.

If the mentioned URI refers to an XMPP context (e.g. a MUC room), a stanza id can be specified. To do so, the Unique and Stable Stanza IDs (XEP-0359) [4] semantic is used: mentioning entity MAY add a <stanza-id/> element to the <part/> element as specified in XEP-0359.

Example 5. mention with context hint

<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>

5. Configuration

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 Ad-Hoc Commands (XEP-0050) [5] is used on the well-defined command node 'urn:xmpp:mention:0#configure'.

6. Discovering Support

6.1 Announce

If a entity supports the JID mention protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:mention:0" in response to a Service Discovery (XEP-0030) [6] information request:

Example 6. service discovery information request

<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 7. service discovery information response

<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>
        

6.2 Configuration

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 configuration section, it MUST announce this fact by including a service discovery feature of "urn:xmpp:mention:0#configure".

7. Business Rules

  1. 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).
  2. 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.

8. Security Considerations

  1. 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 configuration section 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.
  2. 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.
  3. When an author is specified as explained in mention author section, 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.

9. IANA Considerations

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

10. XMPP Registrar Considerations

10.1 Protocol Namespaces

The XMPP Registrar [8] includes 'urn:xmpp:mention:0' in its registry of protocol namespaces (see <http://xmpp.org/registrar/namespaces.html>).

10.2 Protocol Versioning

If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.

11. XML Schema

<?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>
    

12. Acknowledgements

Thanks to Adrien Cossa for his review/corrections.


Appendices


Appendix A: Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Standards Track
Version: 0.1
Last Updated: 2016-01-16
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
This document in other formats: XML  PDF


Appendix B: Author Information

Jérôme Poisson

Email: goffi@goffi.org
JabberID: goffi@jabber.fr


Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2014 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

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

1. XEP-0060: Publish-Subscribe <http://xmpp.org/extensions/xep-0060.html>.

2. XEP-0045: Multi-User Chat <http://xmpp.org/extensions/xep-0045.html>.

3. XEP-0369: Mediated Information eXchange (MIX) <http://xmpp.org/extensions/xep-0369.html>.

4. XEP-0359: Unique and Stable Stanza IDs <http://xmpp.org/extensions/xep-0359.html>.

5. XEP-0050: Ad-Hoc Commands <http://xmpp.org/extensions/xep-0050.html>.

6. XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

7. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

8. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.


Appendix H: Revision History

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

Version 0.1 (2016-01-16)

First draft.

(jp)

END