JEP-0134: Protocol Design Guidelines

2.1 XMPP is Sacred

Background

When the Jabber Software Foundation (JSF) [4] submitted the XMPP Core and XMPP IM specifications to the Internet Engineering Task Force (IETF) [5], it ceded change control over the core XML streaming technology developed by the Jabber community. However, the JSF has reserved the right to define extensions to XMPP; furthermore, that right is not exclusive to the JSF, since anyone can define their own public or private extensions to XMPP. These extensions are usually in the form of structured XML data that is qualified by a unique namespace other than those currently reserved by the IETF or the JSF.

Meaning

When we say that "XMPP is Sacred", we mean that good protocol design must work within the context of XMPP and not require changes to the core protocols. For one thing, any such changes would need to be pursued within the IETF. Further, the core semantics most likely provide everything that a protocol designer needs. If you think that you need to define a new kind of top-level stanza (other than <message/>, <presence/>, and <iq/>) or a new value of the 'type' attribute for any stanza kind, then you probably need to think again. Use XMPP as a set of building blocks and don't modify the foundation when you are working on higher-level structures; instead, treat XMPP as a transport layer and build extensions on top of that layer. A further implication of respecting XMPP is using structured data formats (e.g., applications of XML 1.0 [6] rather than binary or plaintext formats) whenever possible.

Examples

A good example of honoring the XMPP specifications is Invisibility [7]; while the Jabber community had informally defined <presence type='invisible'/> at one point, that protocol was abandoned in favor of an XMPP-compliant approach. Another example is XHTML-IM [8], which re-uses XHTML 1.0 [9] (a structured format that shares with XMPP a common root in XML) rather than Rich Text Format (RTF) [10] (an unstructured format that does not derive from XML).

2.2 Keep Clients Simple

Background

Almost all Jabber technologies are implemented in a client-server architecture. While that's not necessary (and there do exist some peer-to-peer applications of XMPP), it usually makes good sense. Among other things, a client-server architecture has enabled the Jabber community to force most of the complexity onto servers and components, thus keeping clients relatively simple. This principle has served the Jabber community well since the very beginning, and forms an important basis for further innovation.

Meaning

The principle of "keep clients simple" has many implications, among them:

• Don't multiply protocols beyond necessity (the more protocols you define, the harder it is to write a client).
• Degrade gracefully so that simpler or older clients can still participate in the network.
• If intensive processing is required, make a server or component do it.
• Don't force additional requirements (such as XSLT processors) onto clients unless absolutely necessary.

Examples

One good example of keeping clients simple is the presence stanza: the client has only to send <presence/> and the server takes care of presence probes, broadcasts, and appropriate routing decisions. Another example is Multi-User Chat [11]: although the protocol involves some complexity, it was written so that older clients can join and participate in MUC rooms even if they don't understand the more advanced MUC extensions.

2.3 Re-Use Existing Protocols

Background

The Jabber community has been developing wire protocols for XML streaming, presence, and instant messaging since 1999. In that time, members of the community have defined a number of building blocks that can be used as the basis for further development. Furthermore, many smart people have created open protocols within other standards development organizations, including the IETF, the World Wide Web Consortium (W3C) [12], OASIS [13], the International Telecommunication Union (ITU) [14], and the Dublin Core Metadata Initiative (DCMI) [15].

Meaning

Good protocol designers "stand on the shoulders of giants" by re-using protocols that have been defined within the JSF and within other standards development organizations. That does not mean we don't define new protocols, because sometimes that is necessary. However, we are aware of work completed by others and we make use of it, especially when that work is outside the Jabber community's core competence areas (e.g., security or multimedia data formats rather than XML streaming, presence, and real-time messaging). Furthermore, the JSF prefers to re-use open protocols wherever possible.

Examples

Examples of re-using existing Jabber protocols include Stream Initiation [16] (which re-uses Feature Negotiation [17]) and JEP-0126: Invisibility (which re-uses the privacy lists protocol defined in XMPP IM). Examples of re-using non-Jabber protocols include SOCKS5 Bytestreams [18] (which makes use of RFC 1928 [19]) and Common Alerting Protocol (CAP) over XMPP [20] (which defines a way to send Common Alerting Protocol [21] data via Jabber). Here again JEP-0071 provides an example: it re-uses XHTML 1.0 (an open protocol developed by a recognized standards development organization) rather than RTF (a closed protocol maintained by Microsoft).

2.4 Modular is Better

Background

Most Jabber implementations are built using modular architectures, wherein pieces of functionality are coded as separate components and then assembled into larger wholes, with core routing logic that integrates the system (examples include clients that enable the development of plugins and servers that enable the attachment of external components). We can view many Jabber protocols the same way: each one specifies a well-defined domain of functionality that is loosely connected to other domains and integrated by the core transport layer provided by XMPP.

Meaning

The best Jabber protocols are quite focused and provide limited but powerful functionality that can be applied in a specific domain or, sometimes, re-used by other Jabber protocols. Even if the domain is more complex, a protocol that addresses it needs to clearly define its scope, limit that scope as much as possible, and specify only the protocols necessary to meet the core requirements.

Examples

Service Discovery [22] and Data Forms [23] are good examples of focused, single-purpose protocols. By contrast, Multi-User Chat is more complex, but it limits itself to the domain of text conferencing in the context of virtual rooms (e.g., it does not address service-level administration) and consists of separate namespaces for end-user, moderator, and room owner functionality. A good example of a protocol that is focused on a smaller domain is Roster Item Exchange [24].

2.5 Know Your Strengths

Background

The core strength of Jabber technologies is the streaming of relatively small XML fragments between presence-aware network endpoints. As is usually the case, our greatest strength is also our greatest weakness. Thus XMPP is not optimized for binary data, large XML files, multimedia streaming, or other such applications.

Meaning

It's not a bad thing that we don't solve the problems of exchanging binary data, transferring large files, or streaming multimedia, because other protocols and technologies have addressed those domains. But it's important to recognize what we do well and what we don't. For example, the average size of an XMPP stanza is probably on the order of 200 bytes, and in general the largest effective size for stanzas is perhaps ten times that large; although stanzas can be much larger than that, normally it is not wise to consistently generate larger stanzas, and applications that might depend on large stanzas would do better to communicate their data outside of the Jabber band.

Examples

File Transfer [25] is a good example of respecting the strengths and weaknesses of XMPP, since it specifies that going out of band is the preferred mechanism for bandwidth-heavy data transfers.

2.6 Be Explicit

Background

In the beginning was the code (mainly jabberd [26]). Although code is explicit in its own way, not everyone reads code, and detailed specifications are necessary in order to make functionality reproducible in different codebases. The Jabber community has learned that lesson the hard way.

Meaning

Detailed, explicit specifications are good specifications. Define your terms. Use conformance terminology such as MUST and SHOULD rather than loose English words such as "does" and "will". Follow the Guidelines for JEP Authors [27]. Specify error conditions. Include lots of examples. Restrict the allowable XML via schemas and datatypes as specified in XML Schema Part 1 [28] and XML Schema Part 2 [29].

Examples

XMPP Core and XMPP IM are large documents that define the Extensible Messaging and Presence Protocol in excruciating detail. Although such specifications are not fun to write, they provide a model for good protocol design and documentation.

2.7 Stay Flexible

Background

The need for explicit definition must be balanced against the need for flexibility. A completely rigid protocol may break under stress or when conditions change, whereas a more flexible protocol may bend and adapt. Knowing when to be explicit and when to be flexible is a key to good protocol design.

Meaning

In general, a protocol needs to define the skeleton of functionality, but not necessarily specific parameters or values to be used within a certain domain. In order to allow for growth and changes, it often makes sense to specify that the Jabber Registrar [30] shall keep track of certain parameters and values, rather than to explicitly limit them in the protocol itself.

Examples

Whereas the old Agent Information [31] and Jabber Browsing [32] protocols defined certain hardcoded values for entity types and categories, Service Discovery has left that function up to the Jabber Registrar. Similarly, Stream Initiation [33] defines a registry for its profiles, Advanced Message Processing [34] defines registries for processing conditions and actions, and a number of JEPs register FORM_TYPE values as specified in Field Standardization for Data Forms [35].

2.8 Privacy and Security Matter

Background

Since the beginning, privacy and security have been important priorities within the Jabber community. That must not change.

Meaning

Good protocols respect the confidentiality of data generated or communicated by users and applications as well as the security of the system or network as a whole. Although privacy and security considerations have been dealt with at the core XMPP layer, application-level protocols must not compromise privacy and security. Attention to these matters, along with rigorous cross-area review and close scrutiny by protocol designers and reviewers, will help ensure that the protocols we develop will provide a strong foundation for communication over the Internet.

Examples

As is well-known, the presence subscription model developed by the Jabber community and specified in XMPP IM requires approval before a contact can view a user's presence. Similarly, Jabber has always included strong authentication methods, which have been further improved through the use of SASL (RFC 2222 [36]).

Version 0.2 (2004-08-31)

Version 0.1 (2004-04-28)