The best way to start working on your proposal is to retrieve all of the existing XMPP Extension Protocol specifications and associated stylesheets from source control. These files are stored using the CVS system, in a CVS module labelled 'xmpp' and subdirectory labelled 'extensions' at the jabberstudio.org CVS repository. Instructions for accessing these files are provided at <http://www.jabberstudio.org/cvs.php>. The document structure is formally defined by both a DTD and an XML schema, but you do not need to understand the formal descriptions in order to author an XMPP Extension Protocol. In addition, a handy template file is included as the 'xep-template.xml' file in the 'extensions' directory, providing a quick starting point for XEP authoring.

To create your proposal, do a CVS checkout of the 'xmpp' module, change directories to the 'extensions/' directory, copy the template file (e.g., 'cp xep-template.xml xep-foo.xml'), and start editing the file using either a basic text editor or a specialized XML editing application such as XML Spy or XMLmind.

Even if you use a basic text editor, you should be able to view your document in most modern web browsers as an XML file as long as you have xep.xsl and xep.dtd in the 'extensions/' directory. Because of inconsistencies in browser XSLT implementations, certain formatting (e.g., table layouts and the numbering of tables, examples, and footnotes) may not be perfect. Don't panic; it will look fine in the HTML output produced by the XMPP Extensions Editor. If your XML file doesn't render at all (i.e., it's just one big text blob), you are using a bad browser. If you see only the bare outline generated by xep.xsl but none of your text, you have an error in your XML. You can check your XML syntax at xml.com <http://www.xml.com/pub/a/tools/ruwf/check.html>.

To programatically convert your XML file into HTML, we recommend using Daniel Veillard's xsltproc program, which will give you helpful error messages regarding XML syntax problems. However, the XMPP Extensions Editor will do the final rendering of XML into HTML as well as posting of your HTML file to www.xmpp.org, so you do not need to generate HTML files for submission to the XMPP Extensions Editor (in fact, the XMPP Extensions Editor requires that you submit your proposal in the XEP XML format, not HTML).

Finally, the jep.ent file contains convenient "external entities" that provide shortcuts for including references to XMPP Extension Protocols, RFCs, and other common strings. Unfortunately, most browsers do not correctly process external entities, so you cannot include entities from jep.ent if you need to view your XML source file in a browser. However, the XMPP Extensions Editor reserves the right to convert your markup to external entities, since it makes his life easier. Also, please do not add items to the jep.ent file; instead, ask the XMPP Extensions Editor to add them for you.

This section describes the metadata elements contained in the <header/> element of a XEP file (see below for the file contents).

The XML character data of the <title/> element is the title of your XEP. Choose a descriptive title that is less than five words long. The XMPP Extensions Editor may change this in consultation with the author.

The XML character data of the <abstract/> element SHOULD be one sentence that captures the essence of your proposal (usually beginning "This document defines a protocol that..."). The XMPP Extensions Editor has been known to modify the abstract so that it accurately describes the proposal.

The XML character data of the <legal/> element MUST be as follows:

This XMPP Extension Protocol is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy (<http://www.xmpp.org/extensions/ipr-policy.shtml>). This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

The XML character data of the <number/> element SHOULD be "xxxx"; this will be changed to the next sequential XEP number by the XMPP Extensions Editor if the XMPP Council accepts the proposal as an XMPP Extensions Protocol.

The XML character data of the <status/> element SHOULD be "ProtoXEP" since all proposals start out as "proto-XEPs"; this will be changed to "Experimental" if the XMPP Council accepts the proposal as an XMPP Extensions Protocol.

The XML character data of the <type/> element SHOULD be either "Standards Track" or "Informational" (there are also Historical, Humorous, and Procedural XEPs, but these are uncommon and usually written by the XMPP Extensions Editor). A Standards Track XEP defines a XMPP extension intended to be used as a common part of Jabber/XMPP technologies. An Informational XEP defines best practices or a usage profile related to XMPP or an XMPP Extension Protocol (e.g., &xep0175;).

The XML character data of the <approver/> element SHOULD be "Council".

The <dependencies/> element is used to specify RFCs, XMPP Extension Protocols, and other specifications on which your proposal depends in a normative fashion (i.e., specifications that MUST or SHOULD be understood in order to implement your proposed protocol). Each specification MUST be identified by a distinct <spec/> child element (see existing XEP specifications for clues regarding document identifiers, or consult with the XMPP Extensions Editor).

The <supersedes/>, <supersededby/>, <shortname/>, and <schemaloc/> elements are for use by the XMPP Extensions Editor; however, if your document supersedes an existing XMPP Extension Protocol, feel free to include a <spec/> child element specifying the document identifier (e.g., XEP-0093) for the protocol that is being superseded.

Include one <author/> element for each co-author. Note well that the <firstname/>, <surname/>, <email/>, and <jid/> elements are all REQUIRED per XEP-0001.

Include one <revision/> element for each revision of your document. The XML character data of the <version/> element SHOULD be "0.0.1" for your initial submission to the XMPP Extensions Editor, and the <remark/> SHOULD be "Initial version."; for each revision, you will include another <revision/> element (place it before the existing <revision/> elements) and iterate the <version/> element (e.g., "0.2" after "0.1"). The format for the <date/> element is yyyy-mm-dd. Please do not include the characters ' or " in your revision remarks.

Aside from the metadata in the <header/> element (see above), a XEP file is a series of sections, arranged in a hierarchy (<section1/> is a top-level section, within which you can nest <section2/> sections, and so on down to <section4/>). The title of a section is captured in the 'topic' attribute. You should also include an 'anchor' element so that you can link to page fragments from within your document. The allowable elements within a section element probably look familiar from XHTML: <p/> for paragraphs, <ol/> and <ul/> for ordered and unordered lists, and so on.

The <example/> and <code/> elements are used to show protocol snippets; the <example/> element SHOULD possess a 'caption' attribute that describes the example, whereas the <code/> element does not. Define an XML CDATA section within both of these elements so that you do not need to escape the '<' and '>' characters in your sample XML stanzas, since this makes life much easier for author and editor alike (see the markup in existing XEP specifications).

The <p/> and <li/> elements can also contain more markup that is familiar from XHTML, such as the <img/> element. Note that hyperlinks are of the form <link url='foo'>bar</link> rather than <a href='foo'>bar</a>; the reasons for this are lost in the mists of time and it is too late to change it now, so you'll just have to adjust. If needed, you can also use inline structural and presentational markup such as <em/>, <strong/>, <tt/>, <cite/>, and <span/> within the <p/> and <li/> elements.

You may also include tables (these are helpful for listing error codes and such). The <table/> element SHOULD possess a 'caption' attribute that describes the table's contents. Standard XHTML table structure applies (<tr/> defines a row, which contains <th/> elements for header rows and <td/> elements for data rows), and the 'colspan' and 'rowspan' attributes are also available if you need them. Table presentation (such as cellpadding and cellspacing) is handled by the XSLT and CSS stylesheets.

In fact, the jep.xsl file performs all sorts of magic in converting your XML file into HTML, including creation of the front matter, table of contents, section numbering, notes, and revision history. Feel free to submit patches for this file, but do not commit your modified version to CVS.

The introduction to a XEP document is quite important since it provides the rationale for considering the proposal. In particular, the introduction SHOULD include information such as the following:

1. Tasks that users currently cannot complete because we are lacking the protocol you propose. (Note: Users are not just IM users, but any person, system, or application that could gain value from interacting with other entities over Jabber/XMPP networks.)
2. Other projects or protocols and how Jabber/XMPP technologies could interface with them because of your proposed protocol (e.g., XML-RPC, SOAP).
3. A comparison between Jabber/XMPP technologies and "the competition" (e.g., other IM systems or messaging protocols) that describes holes in the Jabber/XMPP protocols that need to be filled in order to offer similar functionality.
4. The relevant history of thinking within the Jabber/XMPP community.
5. Real-world examples of problems the protocol can solve.

Every XEP document SHOULD include a section describing the requirements being addressed by the document. This information is critically important, because it clearly defines the scope of the proposal as well as any relevant constraints on the protocol design.

If your XEP document uses terms that may not be familiar to the reader, please define them in a glossary.

It is recommended that document authors structure their proposals according to the use cases that the proposal will address. A good introduction to use cases may be found at <http://www.pols.co.uk/usecasezone/>. We have found that use cases force authors to focus on functionality rather than "protocol for the sake of protocol". It is also helpful to sort use cases by actor, as is done in &xep0045;, for example. Include one subsection for each use case.

When writing use cases and the associated protocols, make sure to:

• Clearly define the success scenarios, alternate flows, and possible errors.
• Describe the expected behavior of Jabber/XMPP clients, servers, and components when using this protocol.
• Include lots of protocol examples.

We just said so, but we will repeat ourselves: include lots of protocol examples. Examples help not only implementors but also those who will review your proposal in the Standards JIG and XMPP Council. You get extra credit with the XMPP Extensions Editor if you follow Jabber tradition by using characters and situations from the plays of Shakespeare:

If your proposal defines a number of error and status codes (as is done in XEP-0045), it is a good idea to include a table of all the codes defined in your document.

You may want to include a section describing various business rules (essentially, a variety of MUSTs, SHOULDs, and MAYs regarding application behavior). This is not required but can be helpful to implementors.

You may want to include a section devoted to implementation notes. Again, this is not required but can be helpful to implementors.

If there are any internationalization or localization issues related to your proposal (e.g., whether to include the 'xml:lang' attribute), define them in this optional section.

Your proposal MUST include a section entitled "Security Considerations". Even if there are no security features or concerns related to your proposal, you MUST note that fact. For helpful guidelines, refer to &rfc3552;.

This section is REQUIRED. The IANA is the Internet Assigned Numbers Authority, the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. Most proposals do not require interaction with the IANA, in which case the text of this section SHOULD read "This document requires no interaction with the Internet Assigned Numbers Authority (IANA)." If your proposal requires interaction with the IANA, discuss the matter with the XMPP Extensions Editor. Do not contact the IANA on your own!

This section is REQUIRED. The XMPP Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. If your proposal does not require interaction with the XMPP Registrar, the text of this section SHOULD read "No namespaces or parameters need to be registered with the XMPP Registrar as a result of this document." Refer to Draft or Final XEPs for appropriate text in other cases, or consult with the XMPP Extensions Editor.

An XML Schema is required in order for protocols to be approved by the XMPP Council. The XMPP Extensions Editor can assist you in defining an XML Schema for the protocol you are proposing.

Some XEP documents end with a section thanking non-authors who have made significant contributions to the specification; if that is true of your document, feel free to include this section.

When talking about an attribute by name, refer to it in single quotes. Example: the 'to' attribute.

When talking about the value of an attribute, refer to it in double quotes. Example: the value of the 'subscription' attribute is "both".

Elements possess attributes and contain character data and/or child elements; do not confuse these terms.

In examples, use single quotes rather than double quotes; they are more readable.

To show the hierarchy of XML elements, indent two spaces for every level.

If an element possesses a large number of attributes, include a line break before each attribute and indent them so that they are vertically aligned for readability.

If the XML character data of an element is long, include line breaks and indent by two spaces.

Examples are the major source of right-scrolling in our HTML output files. Right-scrolling is evil. Therefore, adjust your example layouts accordingly (line widths should be no more than 110 characters or so).

Example:

Some examples (e.g., SASL examples) include strings that are encoded using Base64 (see &rfc3548;). An easy way to generate these is to place the source text in a file and use the OpenSSL "enc" command to generate the base64-encoded equivalent. For example, if the file "tmp.txt" contains the string "bard@shakespeare.lit" then the command 'openssl enc -base64 -in tmp.txt' will generate the base64-encoded string "YmFyZEBzaGFrZXNwZWFyZS5saXQK".

Some examples (e.g., avatar examples) include strings that are SHA-1 hashes (see &rfc3174;). An easy way to generate these is to place the source text in a file and use the OpenSSL "dgst" command to generate the SHA-1 hash. For example, if the file "tmp.txt" contains the string "bard@shakespeare.lit" then the command 'openssl dgst -sha1 tmp.txt' will generate the SHA-1 hash "e87f5008d779053ac53b29b335b7be8820d5c303".

Conformance terms (e.g,, "MUST" and "SHOULD") are specified in RFC 2119. Use them. When such terms are not in ALL CAPS, the special conformance sense does not apply (this should be obvious but may not be to all authors).

When talking about an element by name, refer to it as an empty XML element. Example: the <query/> element.

The top-level &MESSAGE;, &PRESENCE;, and &IQ; elements are actually XML stanzas (see RFC 3920); refer to them as such.

Elements possess attributes and contain character data and/or child elements; do not confuse these terms.

Do not use the term "tag" when you mean "element".

Do not add a possessive to the element itself. Negative example: the <body/>'s character data. Positive example: the <body/> element's character data.

Note: There are shortcuts for stanza names and some common element names in the jep.ent file.

When talking about an error condition, use the XML element names defined in RFC 3920 rather than the old HTTP-style code numbers. Example: the <feature-not-implemented/> error.

Note: There are shortcuts for the stanza errors in the jep.ent file.

When talking about a namespace by name, refer to it in single quotes. Example: the 'jabber:iq:roster' namespace.

An element or attribute is qualified by (rather than "scoped by" or "in") a particular namespace.

For precision, the JSF follows IETF usage by placing all punctuation outside the quotation marks unless one is quoting text that includes the punctuation. Example: the port used for client communications is "5222".