This document specifies that each disallowed character shall be escaped as \hexhex — where "hexhex" is the hexadecimal value of the Unicode code point in question, ignoring the leading "00" in the code point (e.g., 27 for the apostrophe character, resulting in an escaping of \27).

If the & character had not been in the list of disallowed characters, then normal XML escaping conventions (as specified in &w3xml;) could have been used, with the result that D'Artagnan (for example) could have been rendered as D'artagnan [sic].

It might have been desirable to use percent-encoding (e.g., %27 for the apostrophe character) as specified in Section 2.1 of &rfc3986;. However, that approach was rejected since the % character is an often-used character in existing JIDs (e.g., to replace the @ character in gateway addresses) and the resulting ambiguity would have caused misdelivered or undeliverable messages.

To avoid the problems associated with using & or % as the escaping character, this document specifies a new escaping mechanism that uses the backslash character ("\") followed by "hexhex" (the hexadecimal value of the Unicode code point in question). This escaping method is quite similar to that used for disallowed characters in LDAP distinguished names (see &rfc2253;) but is used only for the characters that are disallowed in XMPP localparts (as well as the escaping character itself in certain special situations).

Here is an example of an escaped JID (this would be displayed but never natively transported as "d'artagnan@musketeers.lit"):

This document describes full escaping and unescaping transformations for all disallowed characters. In addition, escaping and unescaping transformations are shown for the \ character in case it also needs to be escaped when it occurs in a JID or non-XMPP address as part of a character sequence that corresponds to one of the escaped characters.

Note: All transformations are exactly as specified below. CASE IS SIGNIFICANT. Lowercase was selected since the Case-Mapping Rule of the UsernameCaseMapped profile will case fold to lowercase.

The escaping transformations are defined in the following table, whereas the rules that define when to apply these transformations are specified in the Business Rules section of this specification. Typically, escaping is performed only by a client that is processing information provided by a human user in unescaped form, or by a gateway to some external system (e.g., email or LDAP) that needs to generate a JID.

* Note: The character sequence \20 MUST NOT be the first or last character of an escaped localpart. For a similar restriction, see Section 2.4 of RFC 2253.

In the following example, Porthos starts a chat with D'Artagnan, typing into his client the string "d'artagnan@musketeers.lit" (which is escaped by his client to "d\27artagnan@musketeers.lit").

The unescaping transformations are defined in the following table, whereas the rules that define when to apply these transformations are specified in the Business Rules section of this specification. Typically, unescaping is performed only by a client that wants to display JIDs containing escaped characters to a human user, or by a gateway to some external system (e.g., email or LDAP) that needs to generate identifiers for foreign systems.

In the following example, D'Artagnan the elder sends a message through an SMTP mail gateway (the JID is "treville\40musketeers.lit@smtp.gascon.fr" and the destination email address is "treville@musketeers.lit").

The following processing rules apply to native XMPP implementations:

1. A compliant client MUST render an escaped character as its unescaped equivalent when presenting it to a human user (e.g., present \27 as the apostrophe character), but MAY provide a way for the user to view the escaped JID in its wire format (e.g., to compare two JIDs).

2. A server or gateway MAY unescape an escaped character for communication with external systems (e.g. LDAP), but only after the UsernameCaseMapped profile of PRECIS has been applied.

3. An entity MUST unescape only the specified sequences and MUST NOT unescape sequences that do not match the specified sequences.

4. An entity MUST NOT include the unescaped version of a disallowed character over the wire in any XML stanzas sent to another entity.

5. An entity MUST NOT use the unescaped version of a disallowed character when comparing two JIDs.

6. The character sequence \20 MUST NOT be the first or last character of an escaped localpart.

7. If there are any instances of character sequences that correspond to escapings of the disallowed characters (e.g., the character sequence "\27") or the escaping character (i.e., the character sequence "\5c") in the unescaped address, the leading backslash character MUST be escaped to the character sequence "\5c" (e.g., resulting in the character sequences "\5c27" or "\5c5c"). It is possible that some existing JIDs already contain character sequences matching "\5chexhex" (where "hexhex" is the hexadecimal value of the Unicode code point for a disallowed character or the backslash character), which may result in confusion between escaped JIDs and their presentation in a client; however, a survey of one large XMPP deployment yielded no instances of such sequences or even of the character sequence "\5c".

When transforming a non-XMPP ("source") address into an escaped JID, an implementation MUST adhere to the following process:

1. If the source address is a URI, it MUST first be properly decoded according to the rules in RFC 3986 before it is transformed into a JID.

2. If the source address is a URI, the URI scheme component MUST be removed.

3. If there are any instances of character sequences that correspond to escapings of the disallowed characters (e.g., the character sequence "\27") or the escaping character (i.e., the character sequence "\5c") in the source address, the leading backslash character MUST be escaped to the character sequence "\5c" (e.g., resulting in the character sequences "\5c27" or "\5c5c").

4. All disallowed characters in the source address MUST be properly escaped in the resulting JID (as described above).

While the fourth step should be clear from the foregoing text and the second step is necessary since XMPP addresses are not URIs, the meaning of the first and third steps may not be obvious.

Regarding step one, many non-XMPP messaging systems use URIs to identify addresses (examples include the mailto:, sip:, sips:, im:, pres:, and wv: URI schemes) or follow some other encoding rules for an identifier (e.g., an LDAP distinguished name). Before transforming a non-XMPP address or identifier into a JID, the address or identifier MUST first be decoded according the rules specified for that type of address or identifier in order to ensure that the proper characters are transformed.

Regarding step three, it is possible for some non-XMPP addresses to contain character sequences that correspond to JID-escaped characters (e.g., "\27"). Consider a Wireless Village address of <wv:\3and\2is\5cool@example.com> — if that address were directly converted into a JID, the resulting XMPP address would be \3and\2is\5cool@example.com, which could be construed as :nd\2is\ool@example.com if JID escaping logic is applied. Therefore the leading \ character and the \ character before the character sequence 5c MUST be converted to the character sequence "\5c" during the transformation, leading to a JID of \5c3and\2is\5c5cool@example.com (which would be presented to a human user as \3and\2is\5cool@example.com).

In order to maintain as much backward compatibility as possible, partial escape sequences and escape sequences corresponding to characters not on the list of disallowed characters MUST be ignored (with the exception of the escaping character '\' itself in the rare case when the source address includes the sequence '\5c').

However, \5c would be escaped if found in the source address (e.g., a source address of "c:\5commas@example.com" would be escaped to "c\3a\5c5commas@example.com") and unescaped if contained in the JID-on-the-wire (e.g., a JID-on-the-wire of "c\3a\5c5commas@example.com" would be unescaped back to "c:\5commas@example.com").

When a client attempts to communicate with another entity through a gateway, it needs to know which escaping mechanism to use. A client MUST assume that the gateway does not support the JID escaping mechanism unless it explicitly discovers support for the jid\20escaping [sic] feature as described under Determining Support. If there are any errors in the service discovery exchange or if support for JID escaping is not discovered, the client SHOULD proceed as follows:

1. If the gateway supports the 'jabber:iq:gateway' protocol (as specified in &xep0100;), use that protocol.
2. If the gateway does not support the 'jabber:iq:gateway' protocol, use customary escaping mechanisms (such as transformation of the @ character to the % character).

The following table shows user input, the escaped JID for sending over the wire, and client display (same as user input) for the localpart that might possibly be used in native JIDs. The examples are numbered for easy reference. Naturally, a client that does not perform JID escaping would display the JIDs in their escaped form (e.g., "space\20cadet" instead of "space cadet").

The address format for an Internet mailbox is specified in RFC 5322. The identifier of interest in this context is the "addr-spec" address and more particularly the "dot-atom-text" rule specified in Section 3.2.3, i.e., the email address shorn of angle brackets, display names, comments, quoted strings, and the like. Because some deployments of XMPP messaging systems may want to re-use existing email addresses as JIDs, it is helpful to define how to transform an email address into a JID.

In general, it is straightforward to transform an email address (i.e., a "dot-atom-text") into a JID, since traditional email addresses allow US-ASCII characters only rather than the nearly full range of Unicode code points allowed in a JID. This specification does not cover recent efforts to define internationalized email addresses. However, there are three characters allowed in the localpart of an email address that are not allowed in the localpart portion of a JID: namely, the characters & ' / as described in Sections 3.2.3 and 3.2.4 of RFC 5322. In order to transform these characters, a compliant implementation MUST use the methods specified herein.

(Note: Because the backslash character is forbidden in the "dot-atom-text" construction, an email address should not contain a character sequence that corresponds to one of the escaped characters specified in the Transformations section of this document; therefore, no such examples are shown.)

An email address may also exist in the form of a mailto: URI as specified in &rfc2368;. Before transforming a mailto: URI into a JID, it MUST be URL-decoded and all headers MUST be removed, leaving a mailbox identifier, as shown in the following example.

The foregoing examples showed how to transform an email address or mailto: URI into a JID. However, it also may be necessary to convert a JID into an email address or mailto: URI, as shown in the following example.

As specified in &rfc3261;, a SIP address (i.e., a sip: or sips: URI) can be quite complex if URI parameters or headers are included. However, a basic SIP address (the combination of the optional "userinfo" and required "hostport" constructions) is essentially similar to an email address (e.g., the same characters & ' / allowed in an email address but disallowed in an XMPP localpart are also allowed in a basic SIP address).

The foregoing example showed how to transform a sip: or sips: URI into a JID. However, it also may be necessary to convert a JID into a sip: or sips: URI, as shown in the following example.

The im: and pres: URI schemes are specified in &rfc3860; and &rfc3859; respectively. With the exception of headers, an im: or pres: URI is simply a mailbox (as specified in RFC 5322) prepended with the im: or pres: scheme. Thus a basic IM or PRES address (not including optional headers) is essentially similar to an email address (e.g., the same characters & ' / allowed in an email address but disallowed in an XMPP localpart are also allowed in a basic IM or PRES address).

The foregoing example showed how to transform an im: or pres: URI into a JID. However, it also may be necessary to convert a JID into an im: or pres: URI, as shown in the following example.

The Instant Messaging and Presence Service (IMPS) protocol was originally defined by the Wireless Village consortium and is now maintained by the &OMA;. An IMPS address is formatted as a wv: URI, as specified in &wv-csp;. A basic address (not including a private resource) is of the form <wv:user-id@domain> and an address with a private resource is of the form <wv:user-id/resource@domain>.

The "User-ID" construction is either a mobile phone number (beginning with "+1" for international numbers and a digit for national numbers) or an "Internet-Identity". An "Internet-Identity" may contain any US-ASCII character other than / @ + SP TAB and thus may include the following characters that are disallowed in the localpart of a JID: " & ' / : < > (which characters MUST be escaped when transforming an IMPS address into a JID). However, some of those characters are also reserved in URI syntax (namely the & ' / characters) so those characters will be found in escaped form within a wv: URI.

Unlike the foregoing address types, IMPS addresses are allowed to contain backslashes. This implies that it is possible for an IMPS address to contain a character sequence that corresponds to one of the escaped character representations for code points that are disallowed in XMPP localparts. An example would be the IMPS address <wv:\3and\2is\5cool@example.com>, where the character sequence "\3a" could be interpreted as the : character (and the character sequence "\5c" as "\") if that IMPS address is directly converted into a JID. Therefore, the leading \ character MUST be transformed to "\5c" (and the source character sequence "\5c" to "\5c5c") in order to avoid possible ambiguity. Thus the transformed JID would be <\5c3and\2is\5c5cool@example.com>, which would be presented to a user as <\3and\2is\5cool@example.com>.

If an IMPS address contains a private resource, a gateway between XMPP and IMPS should process the resource and append it to the end of the JID; however, such gateway behavior is out of scope for this document.

The foregoing example showed how to transform a wv: URI into a JID. However, it also may be necessary to convert a JID into a wv: URI, as shown in the following example.

Within the Lightweight Directory Access Protocol (see &rfc2251;), a "distinguished name" (DN) is a hierarchically-organized string representation that uniquely identifies a user, system, or organization. It is possible that some messaging systems use LDAP distinguished names to identify entities that can communicate using the system (e.g., this is reputed to be the case for certain releases of the Lotus Sametime system sold by IBM), and in any case it may be helpful to transform an LDAP distinguished name into an XMPP address for identification or addressing purposes.

As previously mentioned, a UTF-8 string representation of LDAP distinguished names is specified in RFC 2253. This representation specifies that the characters , + " \ < > ; are to be escaped with the backslash character (e.g., the character sequence "\," would be used to escape the , character) and that any other non-US-ASCII characters are to be escaped using a character sequence of the form "\xx".

The following example shows a distinguished name (and transformations thereof) for a person whose common name is "D'Artagnan Saint-André" and who is associated with an organization called "Example & Company, Inc." whose domain name is "example.com":

This example assumes that the specified user is identified with a gateway running at st.example.com (note that the backslash escaping the , character in the organization name is removed during the transformation).

Naturally, a more intelligent gateway could use the Domain Components to construct a more readable JID, such as <D\27Artagnan\20Saint-André@example.com>; however, such gateway behavior is out of scope for this document.

The foregoing example showed how to transform an LDAP distinguished name into a JID. However, it also may be necessary to convert a JID into an LDAP distinguished name, as shown in the following example.

&rfc2812; defines the address format for Internet Relay Chat (IRC) entities, which can be servers, channels, or users. The "user" portion of an IRC address may contain any octet except NUL, CR, LF, SP, and "@"; this includes the characters " & ' / : < > \ (which are disallowed in XMPP localparts and therefore MUST be escaped when transforming an IRC address into a JID).

Like IMPS addresses, IRC addresses are allowed to contain backslashes. This implies that it is possible for an IMPS address to contain a character sequence that corresponds to one of the escaped character representations for code points that are disallowed in XMPP localparts. An example is shown above.

The ®ISTRAR; includes the jid\20escaping [sic] feature in its registry of service discovery features.