This JEP provides information intended to assist authors of Jabber Enhancement Proposals.
NOTICE: This Procedural JEP proposes that the process or activity defined herein shall be followed by the Jabber Software Foundation (JSF). However, this process or activity has not yet been approved by the Jabber Council and/or the JSF Board of Directors and is therefore not currently in force.
Status: Experimental
Type: Procedural
Number: 0143
Version: 0.2
Last Updated: 2004-09-16
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: JEP-0001
Supersedes: None
Superseded By: None
Short Name: N/A
Email: stpeter@jabber.org
JID: stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Jabber Software Foundation (JSF) [1] receives a significant number of proposals for extending the core Jabber protocols. However, it is not always clear to authors how to best structure a proposal in order for it to be accepted as a Jabber Enhancement Proposal and advance through the JSF's standards process. Therefore, this JEP provides guidelines that are intended to help authors write better JEPs.
These guidelines assume that the reader is familiar with the JEP series of documents and the processes for handling them within the JSF, as defined in Jabber Enhancement Proposals [2].
Before submitting a proposal for consideration as a JEP, the prospective author is strongly encouraged to complete some research in order to determine:
After completing this research, the prospective author may conclude that a new protocol extension is needed. If so, the author is advised to review the Protocol Design Guidelines [5], to understand the Submission Process, to become familiar with both the JEP XML Format and the JEP Styleguide, and to write the content required in order to complete the various Sections of a JEP.
The process for submitting a JEP is straightforward:
The JEP XML format is substantially similar to a reduced set of XHTML. This is intentional: it makes authoring JEPs easier. In fact, if you use the JEP template file with its associated XSLT stylesheet, you should be able to view your proposal in most modern web browsers (see below). The following subsections explain how to get started with JEP authoring and describe the XML format used for JEPs.
The best way to start working on your proposal is to retrieve all of the existing JEPs and associated stylesheets from source control. These files are stored using the CVS system, in a CVS module labelled 'jeps' at the jabberstudio.org CVS repository. Instructions for accessing these files is 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 these in order to author a JEP. In addition, a handy template file is included under the "templates/" directory in the "jeps" module, providing an easy starting point for JEP authoring.
To create your proposal, do a CVS checkout of the 'jeps' module, create a new directory (e.g., 'tmp/') for your JEP within the existing 'jeps/' directory, and copy one of the template files from the 'template/' directory to your new directory. You should be able to view your JEP in most modern web browsers as an XML file as long as you have jep.xsl and jep.dtd in the 'jeps/' directory (i.e., the parent of the directory for your specific JEP). 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 HTML.
If your XML file doesn't render at all (i.e., it's just one big text blob), you are using the wrong browser. If you see only the bare outline generated by jep.xsl but none of your text, you have an error in your XML. You can check your XML syntax at xml.com [8].
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 JEP Editor will do the final rendering of XML into HTML as well as posting of your HTML file to the website, so you do not need to generate HTML files for submission to the JEP Editor (in fact, the JEP Editor requires that you submit your proposal in the JEP XML format, not HTML).
Finally, the jep.ent file contains helpful "external entities" that provide shortcuts for including references to JEPs, 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 JEP 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 JEP Editor to add them for you.
This section describes the metadata elements contained in the <header/> element of a JEP file (see below for the file contents).
The XML character data of the <title/> element is the title of your JEP. Choose a descriptive title that is less than five words long. The JEP 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 JEP defines a protocol that..."). The JEP 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 Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy (http://jabber.org/jsf/ipr-policy.php). This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).
Your JEP number will be assigned by the JEP Editor; thus you can just make the XML character data of the <number/> element "xxxx".
The XML character data of the <status/> element should be "Experimental" since all JEPs start out as Experimental.
The XML character data of the <type/> element should be either "Standards Track" or "Informational" (there are also Historical and Procedural JEPs, but these are uncommon and usually written by the JEP Editor). A Standards Track JEP is basically any JEP that defines a protocol to be used in the Jabber community. An Informational JEP defines best practices or a usage profile related to an existing protocol (e.g., Invisibility [9]).
The XML character data of the <approver/> element should be "Council".
The <dependencies/> element is used to specify JEPs, RFCs, and other specifications on which your proposal depends in a normative fashion (i.e., specifications that must or should be implemented in order to implement your proposed protocol). Each specification must be identified by a distinct <spec/> child element (see existing JEPs for clues regarding document identifiersk, or consult with the JEP Editor).
The <supersedes/>, <supersededby/>, <shortname/>, and <schemaloc/> elements are for use by the JEP Editor; however, if your JEP supersedes an existing JEP, feel free to include a <spec/> child element specifying the document identifier (e.g., JEP-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 mandatory per JEP-0001.
Include one <revision/> element for each revision of your JEP. The XML character data of the <version/> element must be "0.1" for your initial submission to the JEP 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 JEP <header/> element (see above), a JEP 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 may also include an 'anchor' element so that you can link to page fragments from within your JEP. The allowable elements within a section element probably look familiar: <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 includes a 'caption' attribute so that you can provide a description of 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.
The <p/> and <li/> elements can also contain more markup that is familiar from HTML, 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 can also include tables (these are helpful for listing error codes and such). The <table/> element also can possess a 'caption' attribute so that you can provide a description of the table's contents. Standard HTML 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.
Most JEPs will have most of the following sections, usually in something like the order shown. Other sections may be appropriate (e.g., XHTML-IM [10] has a section for W3C Considerations). Use your best judgement regarding the sections you need to make your argument, or consult with the JEP Editor regarding your needs.
The introduction to a JEP is quite important since it provides the rationale for considering the proposal. In particular, the introduction should include information such as the following:
If your JEP uses terms that may not be familiar to the reader, please define them in a glossary.
Every JEP should include a section describing the requirements being addressed by the JEP. This information is critically important, because it clearly defines the scope of the proposal as well as any relevant constraints on the protocol design.
It is recommended that JEP authors structure their proposals according to the use cases that the proposal will address [11]. We have found that use cases force JEP 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 Multi-User Chat [12], for example. Include one subsection for each use case.
When writing use cases and the associated protocols, make sure to:
We just said so, but we will repeat ourselves: include lots of protocol examples. The help not only implementors but also those who will review your proposal. You get extra credit with the JEP Editor if you follow Jabber tradition by using characters and situations from the plays of Shakespeare:
Example 1. An Example from Shakespeare
<message
from='juliet@capulet.com/balcony'
to='romeo@montague.net/garden'
type='chat'>
<body>Wherefore art thou, Romeo?</body>
</message>
If your proposal defines a number of error and status codes (as is done in JEP-0045), it is a good idea to include a table of all the codes defined in your document.
As with implementation notes, 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, 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 RFC 3552 [13].
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 JEP requires no interaction with the Internet Assigned Numbers Authority (IANA)." If your proposal requires interaction with the IANA, discuss the matter with the JEP Editor. Do not contact the IANA on your own!
This section is REQUIRED. The Jabber 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 Jabber Registrar, the text of this section should read "No namespaces or parameters need to be registered with the Jabber Registrar as a result of this JEP." Refer to Draft or Final JEPs for appropriate text in other cases, or consult with the JEP Editor.
An XML Schema is required in order for a JEP to be approved by the Jabber Council. The JEP Editor can assist you in defining an XML Schema for the protocol you are proposing.
Some JEPs end with a section thanking non-authors who have made strong contributions to the specification; if that is true of your JEP, feel free to include this section.
JEPs are written in English. It is not expected that you will be a fine prose writer, but try to write in a clear, easily-understood fashion. The JEP Editor will correct any errors of grammar, spelling [14], punctuation, and usage he may find in your proposal, but may not do so until your proposal is farther along in the JEP process; in addition, the JEP Editor reserves the right to improve phrases that are unclear or infelicitous, move sections around, modify examples to use Shakespearean characters, and otherwise improve the argument and logical flow of your proposal (naturally, without changing the meaning of your proposal).
The following styleguide is provided to supplement the standard English styleguides, such as The Elements of Style and the Chicago Manual of Style; please refer to those resources for information about basic English usage and to this styleguide for JEP-specific guidelines.
When talking about an attribute by name, refer to it in single quotes. Example: the 'to' attribute.
When talking about an attribute value, 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 by four spaces or so that the attributes 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. Adjust your example layouts accordingly (line widths should be no more than 110 characters or so).
Example:
<iq from='darkcave@macbeth.shakespeare.lit'
id='config1'
to='crone1@shakespeare.lit/desktop'
type='result'>
<query xmlns='http://jabber.org/protocol/muc#owner'>
<x xmlns='jabber:x:data' type='form'>
<title>Configuration for "darkcave" Room</title>
<instructions>
Please coomplete this form to make changes to the configuration
of your room; to add room owners and administrators, use the
appropriate room commands rather than this form.
</instructions>
<field
type='hidden'
var='FORM_TYPE'>
<value>http://jabber.org/protocol/muc#owner</value>
</field>
</query>
</iq>
Conformance terms (e.g,, "MUST" and "SHOULD") are specified in RFC 2119. Use them.
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 XMPP Core [15]); 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".
When talking about an error condition, use the XML element names defined in XMPP Core rather than the old HTTP-style code numbers. Example: the <feature-not-implemented/> error.
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 a text that includes the punctuation. Example: the port used for Jabber client communications is "5222".
For further information about the JEP process, please familiarize yourself with JEP-0001. For examples of formatting, refer to existing JEPs. For an understanding of current issues of interest to the Jabber community and to follow discussions about Jabber protocols, subscribe to the mailing list of the Standards JIG [16].
If you have any questions or have difficulties writing your JEP, feel free to contact the JEP Editor via email at editor@jabber.org, or via Jabber for a faster response.
1. The Jabber Software Foundation (JSF) is an independent, non-profit organization that develops open application protocols on top of the IETF's Extensible Messaging and Presence Protocol (XMPP). For further information, see <http://www.jabber.org/jsf/>.
2. JEP-0001: Jabber Enhancement Proposals <http://www.jabber.org/jeps/jep-0001.html>.
3. The Internet Engineering Task Force is the principal body engaged in the development of new Internet standard specifications, best known for its work on standards such as HTTP and SMTP. For further information, see <http://www.ietf.org/>.
4. The World Wide Web Consortium defines data formats and markup languages (such as HTML and XML) for use over the Internet. For further information, see <http://www.w3.org/>.
5. JEP-0134: Protocol Design Guidelines <http://www.jabber.org/jeps/jep-0134.html>.
6. The JEP Editor is the individual appointed by the JSF Board of Directors to handle protocol submissions and provide day-to-day management of the JSF's standards process. For further information, see <http://www.jabber.org/jeps/editor.php>.
7. The JSF IPR Policy defines the Jabber Software Foundation's official policy regarding intellectual property rights (IPR) as they pertain to Jabber Enhancement Proposals (JEPs). For further information, see <http://www.jabber.org/jsf/ipr-policy.php>.
8. <http://www.xml.com/pub/a/tools/ruwf/check.html>
9. JEP-0126: Invisibility <http://www.jabber.org/jeps/jep-0126.html>.
10. JEP-0071: XHTML-IM <http://www.jabber.org/jeps/jep-0071.html>.
11. A good introduction to use cases may be found at <http://www.pols.co.uk/usecasezone/>.
12. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.
13. RFC 3552: Guidelines for Writing RFC Text on Security Considerations <http://www.ietf.org/rfc/rfc3552.txt>.
14. With all due respect to authors in other parts of the world, JEPs follow American spelling conventions; thus "authorise" will be changed to "authorize" and such.
15. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
16. The Standards JIG is a standing Jabber Interest Group devoted to discussion of Jabber Enhancement Proposals. The discussion list of the Standards JIG is the primary venue for discussion of Jabber protocol development, as well as for announcements by the JEP Editor and Jabber Registrar. To subscribe to the list or view the list archives, visit <http://mail.jabber.org/mailman/listinfo/standards-jig/>.
END