The motivation for such a protocol comes from the desire to expand Jabber technologies outside the domain of instant messaging. Similar to web applications, these "Jabber applications" are systems in which, via a compliant Jabber client, a user (or automated process) can interact with the application. The client need not be specially-written in order to take advantage of this Jabber application.

This mechanism allows for a larger base of Jabber entities to participate as part of larger application architectures. Although specialized clients would be preferred in many environments, this protocol allows for applications to have a wider audience (i.e., any compliant Jabber client).

The namespace governing this protocol is "http://jabber.org/protocol/commands" (hereafter referred to as x-commands). This namespace relies on the &IQ; element for execution, and can use the &MESSAGE; element for announcing command lists. This protocol depends on &xep0030; for reporting and announcing command lists. This namespace is intended to complement &xep0004; (jabber:x:data), but is not necessarily dependent upon it.

Support of x-commands implies support for "jabber:x:data" (although this requirement may be replaced and/or amended with a requirement to support &xep0020; by performing the appropriate negotations before executing commands). x-commands provides a bootstrap for performing ad-hoc "jabber:x:data" processes, while the data itself is conveyed using "jabber:x:data".

The x-commands namespace is not designed to replace machine-to-machine oriented RPC systems such as &xep0009;, where the two entities fully understand the command's purpose and behavior prior to execution. x-commands is oriented more for human interaction, where the user agent (such as a compliant Jabber client) most likely has no prior knowledge of the command's purpose and behavior.

To determine if an entity supports x-commands, the requester uses Service Discovery. The requester makes an "#info" query to the responder. If supported, the responder includes a <feature/> with the "var" of "http://jabber.org/protocol/commands".

To find what commands an entity provides, the requester uses Service Discovery. Each command is a node of the responder, under the fixed node "http://jabber.org/protocol/commands" (for which the service discovery identity category is "automation" and type is "command-list"). Use of a fixed node for all commands of an entity allows for immediate retrieval of commands.

Each command is a disco item. The node attribute of <item/> identifies the command, and the name attribute is the label for the command.

The requester retrieves the list of commands by querying for the responder's items for the node "http://jabber.org/protocol/commands":

The result can then be used by the client to populate a menu, a dialog of buttons, or whatever is appropriate to the current user interface. The responder is not required to send the same list of commands to all requesters.

If additional information about a command is desired, the requester queries for disco information on the command node:

A responder MUST at least provide <identity category='automation' type='command-node'/> and <feature var='http://jabber.org/protocol/commands'/>, and SHOULD include <feature var='jabber:x:data'/>. It is not required to support additional information about a command. If the command is not available to the requester, the responder SHOULD respond with a 403 "Forbidden" error.

In some cases, a responder entity may find it appropriate to automatically push this information (e.g. a subscribed entity becomes available). In this case, the entity sends a &MESSAGE; containing the proper disco#items &QUERY;:

The only portion required is <query xmlns='http://jabber.org/protocol/disco#items'/>. Any other information (such as the <subject/> in the foregoing example) is OPTIONAL.

The above example shows the command execution resulting in a "jabber:x:data" form. It is also possible that one or more URLs (specified via &xep0066;) could be returned.

All commands used in the above examples are for illustrative purposes only. There are no predefined or required commands.

Each command is identified by its 'node' attribute. This matches the 'node' attribute from the service discovery <item/> element. Service Discovery requires that all 'node' values be unique within a given JID. This document requires that the 'node' value used in <command/> exactly match the value used in the <item/> element. It is the responsibility of the responder implementation to ensure each command's node is unique for their JID.

The execution of a command exists within the concept of a session. Each session is identified by the 'sessionid' attribute, and SHOULD be valid only between one requester/responder pair. The responder is responsible for determining the session lifetime, with some help from the requester.

The requester starts a new session for a command by simply sending a <command/> with the 'node' attribute (and optionally the 'status' attribute with a value of "execute"). Once the 'sessionid' attribute is given to the requester, it is the requester's responsibility to maintain it for the session's lifetime. A session ends when the responder sends a <command status='completed'/> or the requester sends a <command action='cancel'/> with the provided 'sessionid' value.

Once a session has ended, its 'sessionid' value SHOULD NOT be used again. It is the responder's responsibility to ensure that each 'sessionid' value is unique.

It may be possible for a requester to be executing more than one session of the same command with a given responder. If the responder does not allow more than one session of the same command with the same requester, the responder MUST return a ¬allowed; error (see &xep0086;).

The result for each stage (other than the last) of a command's execution SHOULD include an <actions/> element. The user-agent can use this information to present a more-intelligent user interface, such as a "druid" or "wizard".

For a user-agent, a typical interpretation of the <actions/> information (or lack thereof) would be the following:

1. The action "cancel" is always allowed.
2. If there is no <actions/> element, the user-agent can use a single-stage dialog or view.
   • The action "execute" is equivalent to the action "complete".
3. If there is an <actions/> element, the user-agent usually uses a multi-stage dialog or view, such as a wizard.
   • The action "execute" is equivalent to the action specified in the "execute" attribute. If the "execute" attribute is absent, it defaults to "next". A form which has an <actions/> element and an "execute" attribute which evaluates (taking the default into account if absent) to an action which is not allowed is therefore invalid.
   • The "prev" action is typically the "back" or "previous" button or option in a wizard. If <prev/> is not contained by the <actions/>, it is disabled.
   • The "next" action is typically the "next" button or option in a wizard. If <next/> is not contained by the <actions/>, it is disabled.
   • The "complete" action is typically the "finish" or "done" button or option in a wizard. If <complete/> is not contained by the <actions/>, it is disabled.
   • If the <actions/> possesses the "execute" attribute, that value is the default button or option. If the <actions/> does not possess the "execute" attribute, there is no default button or option.
   • As the "execute" command is equivalent to another command ("next" in the absence of an "execute" attribute), it is not suggested that a user-agent shows both the "execute" and the command that "execute" is an alias of in their interface.

Responders SHOULD use the following guidelines when providing <actions/>:

• The "execute" attribute SHOULD NOT specify a value that does not match one of the allowed actions.
• As user-agents treat the absence of an "execute" attribute as equivalent to "next", when the <actions/> element is provided, it is invalid to return a command that has no "execute" attribute, an actions element, and no <next/> action

On its own, the <command/> has very little usefulness. It relies on its payload to give full meaning to its use. The payload can be elements in any namespace that makes sense and is understood (such as "jabber:x:data"), and/or one or more <note/> elements. Any namespaced elements can be used within a <command/>. The only limitations are that the elements not require certain parent elements (such as &IQ;), or specifically allow for <command/> qualified by the "http://jabber.org/protocol/commands" namespace as a possible parent element.

As a general rule, the payload is provided only by the responder. The primary exception to this rule is with the "jabber:x:data" extension (and other namespaces with similar semantics). In this case, if the responder provides a form to submit, the requester SHOULD respond with the submitted data (using the semantics from XEP-0004).

When the precedence of these payload elements becomes important (such as when both "jabber:x:data" and "jabber:x:oob" elements are present), the order of the elements SHOULD be used. Those elements that come earlier in the child list take precedence over those later in the child list. The requester SHOULD consider those elements qualified by the same namespace as having an equivalent precedence (such as if multiple "jabber:x:oob" elements are included).

The status of command execution signals only if the command is executing, has been completed, or been canceled. If completed, the "status" attribute does not specify if it completed successfully or not. If a command completes but fails, the responder MUST include at least one <note type='error'/> with the <command status='completed'/> it returns.

The requester SHOULD provide its locale information using the "xml:lang" attribute on either the &IQ; (RECOMMENDED) or <command/> element. Each execution session (identified by the "sessionid" attribute) SHOULD use only one language/locale, and requesters and responders SHOULD assume the first language/locale specified applies. The responder SHOULD specify the language/locale with the every command session's response.

Within the "http://jabber.org/protocol/commands" schema, the language/locale applies only to the human-readable character data for <info/> elements. It SHOULD also apply to all payload elements, appropriate to their respective specifications.

Responders MUST take this into consideration, and properly account for the language/locale settings within payloads. If the responder cannot accomodate the requested language/locale, it SHOULD respond with a <bad-request/> (<bad-locale/>) error condition.

Each <command/> contains attributes for a node, a "session id", an action type, a status type, and a language/locale specifier. A command MAY contain zero or more <note/> elements and MAY contain other namespaced elements as payload. Elements qualified by the "jabber:x:data" and "jabber:x:oob" namespaces are the typical payload.

The "node" attribute uniquely identifies the command. This attribute MUST be present.

The "sessionid" attribute helps to track a command execution across multiple stages. This attribute MUST be present for subsequent stages, and the responder SHOULD initialize (if not provided) or maintain this attribute. The value of this attribute MUST NOT be empty or null, but otherwise can be any string value. This value MUST be maintained by a requester while executing a command.

The "status" attribute describes the current status of this command. This value SHOULD be set only by the responder. If specified by the requester, the responder MUST ignore it. The value of "status" MUST be one of the following:

The "action" attribute specifies the action to undertake with the given command. This value SHOULD be set only by the requester. If specified by the responder, the requester MUST ignore it. The value of "action" MUST be one of the following:

The "xml:lang" attribute specifies the language/locale this <command/> is intended for. This attribute MAY be specified by the requester to request a specific language/locale, and SHOULD be included by the responder to indicate the language/locale in use.

The children of a <command/> element (other than <actions/> and <note/>) pertain to the command's execution. The order of these elements denote their precedence, so that those elements earlier in the list have higher precedence.

The allowed actions for a particular stage of execution are provided by the <actions/> element. This element SHOULD be provided by the responder if the command's execution is not complete, and SHOULD NOT ever be provided by the requester. It contains a single attribute to specify what the "execute" action equals. It contains child elements to specify what the allowed actions are.

The "execute" attribute specifies what the action "execute" is equivalent to. In user-agent interfaces, this represents the default behavior. This attribute MAY be specified by the responder, and MUST equal one of the "action" attribute values for <command/>. The value of this attribute SHOULD match the local name of one of the contained child elements.

The child elements contained by <action/> specify the allowed actions. The name of each child element MUST be one of the following:

• prev
• next
• complete

Notes about the current status of commands are provided by <note/> elements. This element contains information about current conditions in a command sequence. This element has an attribute that defines the type of note. The body of a <note/> should contain a user-readable text message.

The "type" attribute specifies the severity of the note. This attribute is OPTIONAL, and implies "info" if not present. The value of this attribute MUST be one of the following:

To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes This mapping is provided solely for the purpose of simplifying this discussion.:

Below are the possible errors that can occur during execution.

The ®ISTRAR; includes 'http://jabber.org/protocol/commands' in its registry of protocol namespaces.

The XMPP Registrar includes "automation" in its registry of Service Discovery categories for use for any entities and nodes that provide automated or programmed interaction. This category has the following types:

The registry submission is as follows:

The XMPP Registrar includes "http://jabber.org/protocol/commands" in its registry of well-known Service Discovery nodes.

As authorized by &xep0147;, the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).

The "command" querytype is defined herein for interaction with entities that support the ad-hoc command protocol, with keys of "action" and "node".

The following submission registers the "command" querytype.