RFC 6120
Extensible Messaging and Presence Protocol (XMPP): Core
Pages: 211
Proposed Standard
→ Errata
Obsoletes: 3920
Updated by: 7590 8553
Proposed Standard
→ Errata
Obsoletes: 3920
Updated by: 7590 8553
Part 5 of 9 – Pages 99 to 128
8. XML Stanzas
After a client and a server (or two servers) have completed stream negotiation, either party can send XML stanzas. Three kinds of XML stanza are defined for the 'jabber:client' and 'jabber:server' namespaces: <message/>, <presence/>, and <iq/>. In addition, there are five common attributes for these stanza types. These common attributes, as well as the basic semantics of the three stanza types, are defined in this specification; more detailed information regarding the syntax of XML stanzas for instant messaging and presence applications is provided in [XMPP-IM], and for other applications in the relevant XMPP extension specifications. Support for the XML stanza syntax and semantics defined in this specification is REQUIRED in XMPP client and server implementations. Security Warning: A server MUST NOT process a partial stanza and MUST NOT attach meaning to the transmission timing of any part of a stanza (before receipt of the closing tag).
8.1. Common Attributes
The following five attributes are common to message, presence, and IQ stanzas.8.1.1. to
The 'to' attribute specifies the JID of the intended recipient for the stanza. <message to='romeo@example.net'> <body>Art thou not Romeo, and a Montague?</body> </message> For information about server processing of inbound and outbound XML stanzas based on the 'to' address, refer to Section 10.8.1.1.1. Client-to-Server Streams
The following rules apply to inclusion of the 'to' attribute in stanzas sent from a connected client to its server over an XML stream qualified by the 'jabber:client' namespace. 1. A stanza with a specific intended recipient (e.g., a conversation partner, a remote service, the server itself, even another resource associated with the user's bare JID) MUST possess a 'to' attribute whose value is an XMPP address. 2. A stanza sent from a client to a server for direct processing by the server (e.g., roster processing as described in [XMPP-IM] or presence sent to the server for broadcasting to other entities) MUST NOT possess a 'to' attribute. The following rules apply to inclusion of the 'to' attribute in stanzas sent from a server to a connected client over an XML stream qualified by the 'jabber:client' namespace. 1. If the server has received the stanza from another connected client or from a peer server, the server MUST NOT modify the 'to' address before delivering the stanza to the client. 2. If the server has itself generated the stanza (e.g., a response to an IQ stanza of type "get" or "set", even if the stanza did not include a 'to' address), the stanza MAY include a 'to' address, which MUST be the full JID of the client; however, if the stanza does not include a 'to' address then the client MUST treat it as if the 'to' address were included with a value of the client's full JID.
Implementation Note: It is the server's responsibility to deliver
only stanzas that are addressed to the client's full JID or the
user's bare JID; thus, there is no need for the client to check
the 'to' address of incoming stanzas. However, if the client does
check the 'to' address then it is suggested to check at most the
bare JID portion (not the full JID), since the 'to' address might
be the user's bare JID, the client's current full JID, or even a
full JID with a different resourcepart (e.g., in the case of so-
called "offline messages" as described in [XEP-0160]).
8.1.1.2. Server-to-Server Streams
The following rules apply to inclusion of the 'to' attribute in the
context of XML streams qualified by the 'jabber:server' namespace
(i.e., server-to-server streams).
1. A stanza MUST possess a 'to' attribute whose value is an XMPP
address; if a server receives a stanza that does not meet this
restriction, it MUST close the stream with an <improper-
addressing/> stream error (Section 4.9.3.7).
2. The domainpart of the JID contained in the stanza's 'to'
attribute MUST match the FQDN of the receiving server (or any
validated domain thereof) as communicated via SASL negotiation
(see Section 6), Server Dialback (see [XEP-0220]), or similar
means; if a server receives a stanza that does not meet this
restriction, it MUST close the stream with a <host-unknown/>
stream error (Section 4.9.3.6) or a <host-gone/> stream error
(Section 4.9.3.5).
8.1.2. from
The 'from' attribute specifies the JID of the sender.
<message from='juliet@im.example.com/balcony'
to='romeo@example.net'>
<body>Art thou not Romeo, and a Montague?</body>
</message>
8.1.2.1. Client-to-Server Streams
The following rules apply to the 'from' attribute in the context of
XML streams qualified by the 'jabber:client' namespace (i.e., client-
to-server streams).
1. When a server receives an XML stanza from a connected client, the
server MUST add a 'from' attribute to the stanza or override the
'from' attribute specified by the client, where the value of the
'from' attribute MUST be the full JID
(<localpart@domainpart/resource>) determined by the server for
the connected resource that generated the stanza (see
Section 4.3.6), or the bare JID (<localpart@domainpart>) in the
case of subscription-related presence stanzas (see [XMPP-IM]).
2. When the server generates a stanza on its own behalf for delivery
to the client from the server itself, the stanza MUST include a
'from' attribute whose value is the bare JID (i.e., <domainpart>)
of the server as agreed upon during stream negotiation (e.g.,
based on the 'to' attribute of the initial stream header).
3. When the server generates a stanza from the server for delivery
to the client on behalf of the account of the connected client
(e.g., in the context of data storage services provided by the
server on behalf of the client), the stanza MUST either (a) not
include a 'from' attribute or (b) include a 'from' attribute
whose value is the account's bare JID (<localpart@domainpart>).
4. A server MUST NOT send to the client a stanza without a 'from'
attribute if the stanza was not generated by the server on its
own behalf (e.g., if it was generated by another client or a peer
server and the server is merely delivering it to the client on
behalf of some other entity); therefore, when a client receives a
stanza that does not include a 'from' attribute, it MUST assume
that the stanza is from the user's account on the server.
8.1.2.2. Server-to-Server Streams
The following rules apply to the 'from' attribute in the context of
XML streams qualified by the 'jabber:server' namespace (i.e., server-
to-server streams).
1. A stanza MUST possess a 'from' attribute whose value is an XMPP
address; if a server receives a stanza that does not meet this
restriction, it MUST close the stream with an <improper-
addressing/> stream error (Section 4.9.3.7).
2. The domainpart of the JID contained in the stanza's 'from'
attribute MUST match the FQDN of the sending server (or any
validated domain thereof) as communicated via SASL negotiation
(see Section 6), Server Dialback (see [XEP-0220]), or similar
means; if a server receives a stanza that does not meet this
restriction, it MUST close the stream with an <invalid-from/>
stream error (Section 4.9.3.9).
Enforcement of these rules helps to prevent certain denial-of-service
attacks as described under Section 13.12.
8.1.3. id
The 'id' attribute is used by the originating entity to track any response or error stanza that it might receive in relation to the generated stanza from another entity (such as an intermediate server or the intended recipient). It is up to the originating entity whether the value of the 'id' attribute is unique only within its current stream or unique globally. For <message/> and <presence/> stanzas, it is RECOMMENDED for the originating entity to include an 'id' attribute; for <iq/> stanzas, it is REQUIRED. If the generated stanza includes an 'id' attribute then it is REQUIRED for the response or error stanza to also include an 'id' attribute, where the value of the 'id' attribute MUST match that of the generated stanza. The semantics of IQ stanzas impose additional restrictions as described under Section 8.2.3.8.1.4. type
The 'type' attribute specifies the purpose or context of the message, presence, or IQ stanza. The particular allowable values for the 'type' attribute vary depending on whether the stanza is a message, presence, or IQ stanza. The defined values for message and presence stanzas are specific to instant messaging and presence applications and therefore are defined in [XMPP-IM], whereas the values for IQ stanzas specify the part of the semantics for all structured request- response exchanges (no matter what the payload) and therefore are specified under Section 8.2.3. The only 'type' value common to all three kinds of stanzas is "error" as described under Section 8.3.8.1.5. xml:lang
A stanza SHOULD possess an 'xml:lang' attribute (as defined in Section 2.12 of [XML]) if the stanza contains XML character data that is intended to be presented to a human user (as explained in [CHARSETS], "internationalization is for humans"). The value of the 'xml:lang' attribute specifies the default language of any such human-readable XML character data.
<presence from='romeo@example.net/orchard' xml:lang='en'>
<show>dnd</show>
<status>Wooing Juliet</status>
</presence>
The value of the 'xml:lang' attribute MAY be overridden by the 'xml:
lang' attribute of a specific child element.
<presence from='romeo@example.net/orchard' xml:lang='en'>
<show>dnd</show>
<status>Wooing Juliet</status>
<status xml:lang='cs'>Dvořím se Julii</status>
</presence>
If an outbound stanza generated by a client does not possess an 'xml:
lang' attribute, the client's server SHOULD add an 'xml:lang'
attribute whose value is that specified for the client's output
stream as defined under Section 4.7.4.
C: <presence from='romeo@example.net/orchard'>
<show>dnd</show>
<status>Wooing Juliet</status>
</presence>
S: <presence from='romeo@example.net/orchard'
to='juliet@im.example.com'
xml:lang='en'>
<show>dnd</show>
<status>Wooing Juliet</status>
</presence>
If an inbound stanza received by a client or server does not possess
an 'xml:lang' attribute, an implementation MUST assume that the
default language is that specified for the entity's input stream as
defined under Section 4.7.4.
The value of the 'xml:lang' attribute MUST conform to the NMTOKEN
datatype (as defined in Section 2.3 of [XML]) and MUST conform to the
format defined in [LANGTAGS].
A server MUST NOT modify or delete 'xml:lang' attributes on stanzas
it receives from other entities.
8.2. Basic Semantics
8.2.1. Message Semantics
The <message/> stanza is a "push" mechanism whereby one entity pushes information to another entity, similar to the communications that occur in a system such as email. All message stanzas will possess a 'to' attribute that specifies the intended recipient of the message (see Section 8.1.1 and Section 10.3), unless the message is being sent to the bare JID of a connected client's account. Upon receiving a message stanza with a 'to' address, a server SHOULD attempt to route or deliver it to the intended recipient (see Section 10 for general routing and delivery rules related to XML stanzas).8.2.2. Presence Semantics
The <presence/> stanza is a specialized "broadcast" or "publish- subscribe" mechanism, whereby multiple entities receive information (in this case, network availability information) about an entity to which they have subscribed. In general, a publishing client SHOULD send a presence stanza with no 'to' attribute, in which case the server to which the client is connected will broadcast that stanza to all subscribed entities. However, a publishing client MAY also send a presence stanza with a 'to' attribute, in which case the server will route or deliver that stanza to the intended recipient. Although the <presence/> stanza is most often used by XMPP clients, it can also be used by servers, add-on services, and any other kind of XMPP entity. See Section 10 for general routing and delivery rules related to XML stanzas, and [XMPP-IM] for rules specific to presence applications.8.2.3. IQ Semantics
Info/Query, or IQ, is a "request-response" mechanism, similar in some ways to the Hypertext Transfer Protocol [HTTP]. The semantics of IQ enable an entity to make a request of, and receive a response from, another entity. The data content of the request and response is defined by the schema or other structural definition associated with the XML namespace that qualifies the direct child element of the IQ element (see Section 8.4), and the interaction is tracked by the requesting entity through use of the 'id' attribute. Thus, IQ interactions follow a common pattern of structured data exchange such as get/result or set/result (although an error can be returned in reply to a request if appropriate):
Requesting Responding Entity Entity ---------- ---------- | | | <iq id='1' type='get'> | | [ ... payload ... ] | | </iq> | | -------------------------> | | | | <iq id='1' type='result'> | | [ ... payload ... ] | | </iq> | | <------------------------- | | | | <iq id='2' type='set'> | | [ ... payload ... ] | | </iq> | | -------------------------> | | | | <iq id='2' type='error'> | | [ ... condition ... ] | | </iq> | | <------------------------- | | | Figure 5: Semantics of IQ Stanzas To enforce these semantics, the following rules apply: 1. The 'id' attribute is REQUIRED for IQ stanzas. 2. The 'type' attribute is REQUIRED for IQ stanzas. The value MUST be one of the following; if not, the recipient or an intermediate router MUST return a <bad-request/> stanza error (Section 8.3.3.1). * get -- The stanza requests information, inquires about what data is needed in order to complete further operations, etc. * set -- The stanza provides data that is needed for an operation to be completed, sets new values, replaces existing values, etc. * result -- The stanza is a response to a successful get or set request.
* error -- The stanza reports an error that has occurred
regarding processing or delivery of a get or set request (see
Section 8.3).
3. An entity that receives an IQ request of type "get" or "set" MUST
reply with an IQ response of type "result" or "error". The
response MUST preserve the 'id' attribute of the request (or be
empty if the generated stanza did not include an 'id' attribute).
4. An entity that receives a stanza of type "result" or "error" MUST
NOT respond to the stanza by sending a further IQ response of
type "result" or "error"; however, the requesting entity MAY send
another request (e.g., an IQ of type "set" to provide obligatory
information discovered through a get/result pair).
5. An IQ stanza of type "get" or "set" MUST contain exactly one
child element, which specifies the semantics of the particular
request.
6. An IQ stanza of type "result" MUST include zero or one child
elements.
7. An IQ stanza of type "error" MAY include the child element
contained in the associated "get" or "set" and MUST include an
<error/> child; for details, see Section 8.3.
8.3. Stanza Errors
Stanza-related errors are handled in a manner similar to stream
errors (Section 4.9). Unlike stream errors, stanza errors are
recoverable; therefore, they do not result in termination of the XML
stream and underlying TCP connection. Instead, the entity that
discovers the error condition returns an error stanza, which is a
stanza that:
o is of the same kind (message, presence, or IQ) as the generated
stanza that triggered the error
o has a 'type' attribute set to a value of "error"
o typically swaps the 'from' and 'to' addresses of the generated
stanza
o mirrors the 'id' attribute (if any) of the generated stanza that
triggered the error
o contains an <error/> child element that specifies the error
condition and therefore provides a hint regarding actions that the
sender might be able to take in an effort to remedy the error
(however, it is not always possible to remedy the error)
8.3.1. Rules
The following rules apply to stanza errors:
1. The receiving or processing entity that detects an error
condition in relation to a stanza SHOULD return an error stanza
(and MUST do so for IQ stanzas).
2. The error stanza SHOULD simply swap the 'from' and 'to' addresses
from the generated stanza, unless doing so would (1) result in an
information leak (see under Section 13.10) or other breach of
security, or (2) force the sender of the error stanza to include
a malformed JID in the 'from' or 'to' address of the error
stanza.
3. If the generated stanza was <message/> or <presence/> and
included an 'id' attribute then it is REQUIRED for the error
stanza to also include an 'id' attribute. If the generated
stanza was <iq/> then the error stanza MUST include an 'id'
attribute. In all cases, the value of the 'id' attribute MUST
match that of the generated stanza (or be empty if the generated
stanza did not include an 'id' attribute).
4. An error stanza MUST contain an <error/> child element.
5. The entity that returns an error stanza MAY pass along its JID to
the sender of the generated stanza (e.g., for diagnostic or
tracking purposes) through the addition of a 'by' attribute to
the <error/> child element.
6. The entity that returns an error stanza MAY include the original
XML sent so that the sender can inspect and, if necessary,
correct the XML before attempting to resend (however, this is a
courtesy only and the originating entity MUST NOT depend on
receiving the original payload). Naturally, the entity MUST NOT
include the original data if it not well-formed XML, violates the
XML restrictions of XMPP (see under Section 11.1), or is
otherwise harmful (e.g., exceeds a size limit).
7. An <error/> child MUST NOT be included if the 'type' attribute
has a value other than "error" (or if there is no 'type'
attribute).
8. An entity that receives an error stanza MUST NOT respond to the
stanza with a further error stanza; this helps to prevent
looping.
8.3.2. Syntax
The syntax for stanza-related errors is as follows, where XML data
shown within the square brackets '[' and ']' is OPTIONAL, 'intended-
recipient' is the JID of the entity to which the original stanza was
addressed, 'sender' is the JID of the originating entity, and 'error-
generator' is the entity that detects the fact that an error has
occurred and thus returns an error stanza.
<stanza-kind from='intended-recipient' to='sender' type='error'>
[OPTIONAL to include sender XML here]
<error [by='error-generator']
type='error-type'>
<defined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
[<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'
xml:lang='langcode'>
OPTIONAL descriptive text
</text>]
[OPTIONAL application-specific condition element]
</error>
</stanza-kind>
The "stanza-kind" MUST be one of message, presence, or iq.
The "error-type" MUST be one of the following:
o auth -- retry after providing credentials
o cancel -- do not retry (the error cannot be remedied)
o continue -- proceed (the condition was only a warning)
o modify -- retry after changing the data sent
o wait -- retry after waiting (the error is temporary)
The "defined-condition" MUST correspond to one of the stanza error
conditions defined under Section 8.3.3. However, because additional
error conditions might be defined in the future, if an entity
receives a stanza error condition that it does not understand then it
MUST treat the unknown condition as equivalent to <undefined-
condition/> (Section 8.3.3.21). If the designers of an XMPP protocol
extension or the developers of an XMPP implementation need to
communicate a stanza error condition that is not defined in this
specification, they can do so by defining an application-specific
error condition element qualified by an application-specific
namespace.
The <error/> element:
o MUST contain a defined condition element.
o MAY contain a <text/> child element containing XML character data
that describes the error in more detail; this element MUST be
qualified by the 'urn:ietf:params:xml:ns:xmpp-stanzas' namespace
and SHOULD possess an 'xml:lang' attribute specifying the natural
language of the XML character data.
o MAY contain a child element for an application-specific error
condition; this element MUST be qualified by an application-
specific namespace that defines the syntax and semantics of the
element.
The <text/> element is OPTIONAL. If included, it is to be used only
to provide descriptive or diagnostic information that supplements the
meaning of a defined condition or application-specific condition. It
MUST NOT be interpreted programmatically by an application. It
SHOULD NOT be used as the error message presented to a human user,
but MAY be shown in addition to the error message associated with the
defined condition element (and, optionally, the application-specific
condition element).
Interoperability Note: The syntax defined in [RFC3920] included a
legacy 'code' attribute, whose semantics have been replaced by the
defined condition elements; information about mapping defined
condition elements to values of the legacy 'code' attribute can be
found in [XEP-0086].
8.3.3. Defined Conditions
The following conditions are defined for use in stanza errors.
The error-type value that is RECOMMENDED for each defined condition
is the usual expected type; however, in some circumstances a
different type might be more appropriate.
8.3.3.1. bad-request
The sender has sent a stanza containing XML that does not conform to
the appropriate schema or that cannot be processed (e.g., an IQ
stanza that includes an unrecognized value of the 'type' attribute,
or an element that is qualified by a recognized namespace but that
violates the defined syntax for the element); the associated error
type SHOULD be "modify".
C: <iq from='juliet@im.example.com/balcony'
id='zj3v142b'
to='im.example.com'
type='subscribe'>
<ping xmlns='urn:xmpp:ping'/>
</iq>
S: <iq from='im.example.com'
id='zj3v142b'
to='juliet@im.example.com/balcony'
type='error'>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
8.3.3.2. conflict
Access cannot be granted because an existing resource exists with the
same name or address; the associated error type SHOULD be "cancel".
C: <iq id='wy2xa82b4' type='set'>
<bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
<resource>balcony</resource>
</bind>
</iq>
S: <iq id='wy2xa82b4' type='error'>
<error type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
8.3.3.3. feature-not-implemented
The feature represented in the XML stanza is not implemented by the
intended recipient or an intermediate server and therefore the stanza
cannot be processed (e.g., the entity understands the namespace but
does not recognize the element name); the associated error type
SHOULD be "cancel" or "modify".
C: <iq from='juliet@im.example.com/balcony'
id='9u2bax16'
to='pubsub.example.com'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscriptions/>
</pubsub>
</iq>
E: <iq from='pubsub.example.com'
id='9u2bax16'
to='juliet@im.example.com/balcony'
type='error'>
<error type='cancel'>
<feature-not-implemented
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<unsupported
xmlns='http://jabber.org/protocol/pubsub#errors'
feature='retrieve-subscriptions'/>
</error>
</iq>
8.3.3.4. forbidden
The requesting entity does not possess the necessary permissions to
perform an action that only certain authorized roles or individuals
are allowed to complete (i.e., it typically relates to authorization
rather than authentication); the associated error type SHOULD be
"auth".
C: <presence
from='juliet@im.example.com/balcony'
id='y2bs71v4'
to='characters@muc.example.com/JulieC'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
E: <presence
from='characters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'
type='error'>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
8.3.3.5. gone
The recipient or server can no longer be contacted at this address, typically on a permanent basis (as opposed to the <redirect/> error condition, which is used for temporary addressing failures); the associated error type SHOULD be "cancel" and the error stanza SHOULD include a new address (if available) as the XML character data of the <gone/> element (which MUST be a Uniform Resource Identifier [URI] or Internationalized Resource Identifier [IRI] at which the entity can be contacted, typically an XMPP IRI as specified in [XMPP-URI]). C: <message from='juliet@im.example.com/churchyard' id='sj2b371v' to='romeo@example.net' type='chat'> <body>Thy lips are warm.</body> </message> S: <message from='romeo@example.net' id='sj2b371v' to='juliet@im.example.com/churchyard' type='error'> <error by='example.net' type='cancel'> <gone xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'> xmpp:romeo@afterlife.example.net </gone> </error> </message>8.3.3.6. internal-server-error
The server has experienced a misconfiguration or other internal error that prevents it from processing the stanza; the associated error type SHOULD be "cancel". C: <presence from='juliet@im.example.com/balcony' id='y2bs71v4' to='characters@muc.example.com/JulieC'> <x xmlns='http://jabber.org/protocol/muc'/> </presence>
E: <presence
from='characters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'
type='error'>
<error type='cancel'>
<internal-server-error
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
8.3.3.7. item-not-found
The addressed JID or item requested cannot be found; the associated
error type SHOULD be "cancel".
C: <presence from='userfoo@example.com/bar'
id='pwb2n78i'
to='nosuchroom@conference.example.org/foo'/>
S: <presence from='nosuchroom@conference.example.org/foo'
id='pwb2n78i'
to='userfoo@example.com/bar'
type='error'>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
Security Warning: An application MUST NOT return this error if
doing so would provide information about the intended recipient's
network availability to an entity that is not authorized to know
such information (for a more detailed discussion of presence
authorization, refer to the discussion of presence subscriptions
in [XMPP-IM]); instead it MUST return a <service-unavailable/>
stanza error (Section 8.3.3.19).
8.3.3.8. jid-malformed
The sending entity has provided (e.g., during resource binding) or
communicated (e.g., in the 'to' address of a stanza) an XMPP address
or aspect thereof that violates the rules defined in [XMPP-ADDR]; the
associated error type SHOULD be "modify".
C: <presence
from='juliet@im.example.com/balcony'
id='y2bs71v4'
to='ch@r@cters@muc.example.com/JulieC'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
E: <presence
from='ch@r@cters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'
type='error'>
<error by='muc.example.com'
type='modify'>
<jid-malformed
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
Implementation Note: Enforcement of the format for XMPP localparts
is primarily the responsibility of the service at which the
associated account or entity is located (e.g., the example.com
service is responsible for returning <jid-malformed/> errors
related to all JIDs of the form <localpart@example.com>), whereas
enforcement of the format for XMPP domainparts is primarily the
responsibility of the service that seeks to route a stanza to the
service identified by that domainpart (e.g., the example.org
service is responsible for returning <jid-malformed/> errors
related to stanzas that users of that service have to tried send
to JIDs of the form <localpart@example.com>). However, any entity
that detects a malformed JID MAY return this error.
8.3.3.9. not-acceptable
The recipient or server understands the request but cannot process it
because the request does not meet criteria defined by the recipient
or server (e.g., a request to subscribe to information that does not
simultaneously include configuration parameters needed by the
recipient); the associated error type SHOULD be "modify".
C: <message to='juliet@im.example.com' id='yt2vs71m'>
<body>[ ... the-emacs-manual ... ]</body>
</message>
S: <message from='juliet@im.example.com' id='yt2vs71m'>
<error type='modify'>
<not-acceptable
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
8.3.3.10. not-allowed
The recipient or server does not allow any entity to perform the
action (e.g., sending to entities at a blacklisted domain); the
associated error type SHOULD be "cancel".
C: <presence
from='juliet@im.example.com/balcony'
id='y2bs71v4'
to='characters@muc.example.com/JulieC'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
E: <presence
from='characters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'
type='error'>
<error type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
8.3.3.11. not-authorized
The sender needs to provide credentials before being allowed to
perform the action, or has provided improper credentials (the name
"not-authorized", which was borrowed from the "401 Unauthorized"
error of [HTTP], might lead the reader to think that this condition
relates to authorization, but instead it is typically used in
relation to authentication); the associated error type SHOULD be
"auth".
C: <presence
from='juliet@im.example.com/balcony'
id='y2bs71v4'
to='characters@muc.example.com/JulieC'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
E: <presence
from='characters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'>
<error type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
8.3.3.12. policy-violation
The entity has violated some local service policy (e.g., a message
contains words that are prohibited by the service) and the server MAY
choose to specify the policy in the <text/> element or in an
application-specific condition element; the associated error type
SHOULD be "modify" or "wait" depending on the policy being violated.
(In the following example, the client sends an XMPP message
containing words that are forbidden according to the server's local
service policy.)
C: <message from='romeo@example.net/foo'
to='bill@im.example.com'
id='vq71f4nb'>
<body>%#&@^!!!</body>
</message>
S: <message from='bill@im.example.com'
id='vq71f4nb'
to='romeo@example.net/foo'>
<error by='example.net' type='modify'>
<policy-violation
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
8.3.3.13. recipient-unavailable
The intended recipient is temporarily unavailable, undergoing
maintenance, etc.; the associated error type SHOULD be "wait".
C: <presence
from='juliet@im.example.com/balcony'
id='y2bs71v4'
to='characters@muc.example.com/JulieC'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
E: <presence
from='characters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'>
<error type='wait'>
<recipient-unavailable
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
Security Warning: An application MUST NOT return this error if
doing so would provide information about the intended recipient's
network availability to an entity that is not authorized to know
such information (for a more detailed discussion of presence
authorization, refer to the discussion of presence subscriptions
in [XMPP-IM]); instead it MUST return a <service-unavailable/>
stanza error (Section 8.3.3.19).
8.3.3.14. redirect
The recipient or server is redirecting requests for this information
to another entity, typically in a temporary fashion (as opposed to
the <gone/> error condition, which is used for permanent addressing
failures); the associated error type SHOULD be "modify" and the error
stanza SHOULD contain the alternate address in the XML character data
of the <redirect/> element (which MUST be a URI or IRI with which the
sender can communicate, typically an XMPP IRI as specified in
[XMPP-URI]).
C: <presence
from='juliet@im.example.com/balcony'
id='y2bs71v4'
to='characters@muc.example.com/JulieC'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
E: <presence
from='characters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'
type='error'>
<error type='modify'>
<redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
xmpp:characters@conference.example.org
</redirect>
</error>
</presence>
Security Warning: An application receiving a stanza-level redirect
SHOULD warn a human user of the redirection attempt and request
approval before proceeding to communicate with the entity whose
address is contained in the XML character data of the <redirect/>
element, because that entity might have a different identity or
might enforce different security policies. The end-to-end
authentication or signing of XMPP stanzas could help to mitigate
this risk, since it would enable the sender to determine if the
entity to which it has been redirected has the same identity as
the entity it originally attempted to contact. An application MAY
have a policy of following redirects only if it has authenticated
the receiving entity. In addition, an application SHOULD abort
the communication attempt after a certain number of successive
redirects (e.g., at least 2 but no more than 5).
8.3.3.15. registration-required
The requesting entity is not authorized to access the requested
service because prior registration is necessary (examples of prior
registration include members-only rooms in XMPP multi-user chat
[XEP-0045] and gateways to non-XMPP instant messaging services, which
traditionally required registration in order to use the gateway
[XEP-0100]); the associated error type SHOULD be "auth".
C: <presence
from='juliet@im.example.com/balcony'
id='y2bs71v4'
to='characters@muc.example.com/JulieC'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
E: <presence
from='characters@muc.example.com/JulieC'
id='y2bs71v4'
to='juliet@im.example.com/balcony'>
<error type='auth'>
<registration-required
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</presence>
8.3.3.16. remote-server-not-found
A remote server or service specified as part or all of the JID of the
intended recipient does not exist or cannot be resolved (e.g., there
is no _xmpp-server._tcp DNS SRV record, the A or AAAA fallback
resolution fails, or A/AAAA lookups succeed but there is no response
on the IANA-registered port 5269); the associated error type SHOULD
be "cancel".
C: <message
from='romeo@example.net/home'
id='ud7n1f4h'
to='bar@example.org'
type='chat'>
<body>yt?</body>
</message>
E: <message
from='bar@example.org'
id='ud7n1f4h'
to='romeo@example.net/home'
type='error'>
<error type='cancel'>
<remote-server-not-found
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
8.3.3.17. remote-server-timeout
A remote server or service specified as part or all of the JID of the
intended recipient (or needed to fulfill a request) was resolved but
communications could not be established within a reasonable amount of
time (e.g., an XML stream cannot be established at the resolved IP
address and port, or an XML stream can be established but stream
negotiation fails because of problems with TLS, SASL, Server
Dialback, etc.); the associated error type SHOULD be "wait" (unless
the error is of a more permanent nature, e.g., the remote server is
found but it cannot be authenticated or it violates security
policies).
C: <message
from='romeo@example.net/home'
id='ud7n1f4h'
to='bar@example.org'
type='chat'>
<body>yt?</body>
</message>
E: <message
from='bar@example.org'
id='ud7n1f4h'
to='romeo@example.net/home'
type='error'>
<error type='wait'>
<remote-server-timeout
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
8.3.3.18. resource-constraint
The server or recipient is busy or lacks the system resources
necessary to service the request; the associated error type SHOULD be
"wait".
C: <iq from='romeo@example.net/foo'
id='kj4vz31m'
to='pubsub.example.com'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='my_musings'/>
</pubsub>
</iq>
E: <iq from='pubsub.example.com'
id='kj4vz31m'
to='romeo@example.net/foo'
type='error'>
<error type='wait'>
<resource-constraint
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
8.3.3.19. service-unavailable
The server or recipient does not currently provide the requested
service; the associated error type SHOULD be "cancel".
C: <message from='romeo@example.net/foo'
to='juliet@im.example.com'>
<body>Hello?</body>
</message>
S: <message from='juliet@im.example.com/foo'
to='romeo@example.net'>
<error type='cancel'>
<service-unavailable
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
Security Warning: An application MUST return a <service-
unavailable/> stanza error (Section 8.3.3.19) instead of <item-
not-found/> (Section 8.3.3.7) or <recipient-unavailable/>
(Section 8.3.3.13) if sending one of the latter errors would
provide information about the intended recipient's network
availability to an entity that is not authorized to know such
information (for a more detailed discussion of presence
authorization, refer to [XMPP-IM]).
8.3.3.20. subscription-required
The requesting entity is not authorized to access the requested
service because a prior subscription is necessary (examples of prior
subscription include authorization to receive presence information as
defined in [XMPP-IM] and opt-in data feeds for XMPP publish-subscribe
as defined in [XEP-0060]); the associated error type SHOULD be
"auth".
C: <message
from='romeo@example.net/orchard'
id='pa73b4n7'
to='playwright@shakespeare.example.com'
type='chat'>
<subject>ACT II, SCENE II</subject>
<body>help, I forgot my lines!</body>
</message>
E: <message
from='playwright@shakespeare.example.com'
id='pa73b4n7'
to='romeo@example.net/orchard'
type='error'>
<error type='auth'>
<subscription-required
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
8.3.3.21. undefined-condition
The error condition is not one of those defined by the other conditions in this list; any error type can be associated with this condition, and it SHOULD NOT be used except in conjunction with an application-specific condition. C: <message from='northumberland@shakespeare.example' id='richard2-4.1.247' to='kingrichard@royalty.england.example'> <body>My lord, dispatch; read o'er these articles.</body> <amp xmlns='http://jabber.org/protocol/amp'> <rule action='notify' condition='deliver' value='stored'/> </amp> </message> S: <message from='example.org' id='amp1' to='northumberland@example.net/field' type='error'> <amp xmlns='http://jabber.org/protocol/amp' from='kingrichard@example.org' status='error' to='northumberland@example.net/field'> <rule action='error' condition='deliver' value='stored'/> </amp> <error type='modify'> <undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <failed-rules xmlns='http://jabber.org/protocol/amp#errors'> <rule action='error' condition='deliver' value='stored'/> </failed-rules> </error> </message>8.3.3.22. unexpected-request
The recipient or server understood the request but was not expecting it at this time (e.g., the request was out of order); the associated error type SHOULD be "wait" or "modify".
C: <iq from='romeo@example.net/foo'
id='o6hsv25z'
to='pubsub.example.com'
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unsubscribe
node='my_musings'
jid='romeo@example.net'/>
</pubsub>
</iq>
E: <iq from='pubsub.example.com'
id='o6hsv25z'
to='romeo@example.net/foo'
type='error'>
<error type='modify'>
<unexpected-request
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<not-subscribed
xmlns='http://jabber.org/protocol/pubsub#errors'/>
</error>
</iq>
8.3.4. Application-Specific Conditions
As noted, an application MAY provide application-specific stanza
error information by including a properly namespaced child within the
error element. Typically, the application-specific element
supplements or further qualifies a defined element. Thus, the
<error/> element will contain two or three child elements.
<iq id='ixc3v1b9' type='error'>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<too-many-parameters xmlns='http://example.org/ns'/>
</error>
</iq>
<message type='error' id='7h3baci9'>
<error type='modify'>
<undefined-condition
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xml:lang='en'
xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
[ ... application-specific information ... ]
</text>
<too-many-parameters xmlns='http://example.org/ns'/>
</error>
</message>
An entity that receives an application-specific error condition it
does not understand MUST ignore that condition but appropriately
process the rest of the error stanza.
8.4. Extended Content
Although the message, presence, and IQ stanzas provide basic
semantics for messaging, availability, and request-response
interactions, XMPP uses XML namespaces (see [XML-NAMES]) to extend
the basic stanza syntax for the purpose of providing additional
functionality.
A message or presence stanza MAY contain one or more optional child
elements specifying content that extends the meaning of the message
(e.g., an XHTML-formatted version of the message body as described in
[XEP-0071]), and an IQ stanza of type "get" or "set" MUST contain one
such child element. Such a child element MAY have any name and MUST
possess a namespace declaration (other than "jabber:client", "jabber:
server", or "http://etherx.jabber.org/streams") that defines the data
contained within the child element. Such a child element is called
an "extension element". An extension element can be included either
at the direct child level of the stanza or in any mix of levels.
Similarly, "extension attributes" are allowed. That is: a stanza
itself (i.e., an <iq/>, <message/>, or <presence/> element qualified
by the "jabber:client" or "jabber:server" content namespace) or any
child element of such a stanza (whether an extension element or a
child element qualified by the content namespace) MAY also include
one or more attributes qualified by XML namespaces other than the
content namespace or the reserved
"http://www.w3.org/XML/1998/namespace" namespace (including the so-
called "empty namespace" if the attribute is not prefixed as
described under [XML-NAMES]).
Interoperability Note: For the sake of backward compatibility and
maximum interoperability, an entity that generates a stanza SHOULD
NOT include such attributes in the stanza itself or in child
elements of the stanza that are qualified by the content
namespaces "jabber:client" or "jabber:server" (e.g., the <body/>
child of the <message/> stanza).
An extension element or extension attribute is said to be "extended
content" and the qualifying namespace for such an element or
attribute is said to be an "extended namespace".
Informational Note: Although extended namespaces for XMPP are
commonly defined by the XMPP Standards Foundation (XSF) and by the
IETF, no specification or IETF standards action is necessary to
define extended namespaces, and any individual or organization is
free to define XMPP extensions.
To illustrate these concepts, several examples follow.
The following stanza contains one direct child element whose extended
namespace is 'jabber:iq:roster':
<iq from='juliet@capulet.com/balcony'
id='h83vxa4c'
type='get'>
<query xmlns='jabber:iq:roster'/>
</iq>
The following stanza contains two direct child elements with two
different extended namespaces.
<presence from='juliet@capulet.com/balcony'>
<c xmlns='http://jabber.org/protocol/caps'
hash='sha-1'
node='http://code.google.com/p/exodus'
ver='QgayPKawpkPSDYmwT/WM94uAlu0='/>
<x xmlns='vcard-temp:x:update'>
<photo>sha1-hash-of-image</photo>
</x>
</presence>
The following stanza contains two child elements, one of which is
qualified by the "jabber:client" or "jabber:server" content namespace
and one of which is qualified by an extended namespace; the extension
element in turn contains a child element that is qualified by a
different extended namespace.
<message to='juliet@capulet.com'>
<body>Hello?</body>
<html xmlns='http://jabber.org/protocol/xhtml-im'>
<body xmlns='http://www.w3.org/1999/xhtml'>
<p style='font-weight:bold'>Hello?</p>
</body>
</html>
</message>
It is conventional in the XMPP community for implementations to not
generate namespace prefixes for elements that are qualified by
extended namespaces (in the XML community, this convention is
sometimes called "prefix-free canonicalization"). However, if an
implementation generates such namespace prefixes then it MUST include
the namespace declaration in the stanza itself or a child element of
the stanza, not in the stream header (see Section 4.8.4).
Routing entities (typically servers) SHOULD try to maintain prefixes
when serializing XML stanzas for processing, but receiving entities
MUST NOT depend on the prefix strings to have any particular value
(the allowance for the 'stream' prefix, described under
Section 4.8.5, is an exception to this rule, albeit for streams
rather than stanzas).
Support for any given extended namespace is OPTIONAL on the part of
any implementation. If an entity does not understand such a
namespace, the entity's expected behavior depends on whether the
entity is (1) the recipient or (2) a server that is routing or
delivering the stanza to the recipient.
If a recipient receives a stanza that contains an element or
attribute it does not understand, it MUST NOT attempt to process that
XML data and instead MUST proceed as follows.
o If an intended recipient receives a message stanza whose only
child element is qualified by a namespace it does not understand,
then depending on the XMPP application it MUST either ignore the
entire stanza or return a stanza error, which SHOULD be <service-
unavailable/> (Section 8.3.3.19).
o If an intended recipient receives a presence stanza whose only
child element is qualified by a namespace it does not understand,
then it MUST ignore the child element by treating the presence
stanza as if it contained no child element.
o If an intended recipient receives a message or presence stanza
that contains XML data qualified by a namespace it does not
understand, then it MUST ignore the portion of the stanza
qualified by the unknown namespace.
o If an intended recipient receives an IQ stanza of type "get" or
"set" containing a child element qualified by a namespace it does
not understand, then the entity MUST return an IQ stanza of type
"error" with an error condition of <service-unavailable/>.
If a server handles a stanza that is intended for delivery to another
entity and that contains a child element it does not understand, it
MUST route the stanza unmodified to a remote server or deliver the
stanza unmodified to a connected client associated with a local
account.
(page 128 continued on part 6)