mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-13 21:05:09 -05:00
813 lines
44 KiB
XML
813 lines
44 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Data Forms</title>
|
|
<abstract>This specification defines an XMPP protocol extension for data forms that can be used in workflows such as service configuration as well as for application-specific data description and reporting. The protocol includes lightweight semantics for forms processing (such as request, response, submit, and cancel), defines several common field types (boolean, list options with single or multiple choice, text with single line or multiple lines, single or multiple JabberIDs, hidden fields, etc.), provides extensibility for future data types, and can be embedded in a wide range of applications. The protocol is not intended to provide complete forms-processing functionality as is provided in the W3C XForms technology, but instead provides a basic subset of such functionality for use by XMPP entities.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0004</number>
|
|
<status>Final</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>x-data</shortname>
|
|
<schemaloc>
|
|
<url>http://www.xmpp.org/schemas/x-data.xsd</url>
|
|
</schemaloc>
|
|
&reatmon;
|
|
&hildjj;
|
|
&jer;
|
|
&temas;
|
|
&stpeter;
|
|
<revision>
|
|
<version>2.13.1</version>
|
|
<date>2022-07-25</date>
|
|
<initials>ssw</initials>
|
|
<remark><p>Clarify elements allowed in multi-item data forms</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.13.0</version>
|
|
<date>2022-01-21</date>
|
|
<initials>melvo</initials>
|
|
<remark><p>Add incomplete submission form handling</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.12.1</version>
|
|
<date>2021-06-08</date>
|
|
<initials>ssw</initials>
|
|
<remark><p>Add missing "one" in a sentence (editorial).</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.12.0</version>
|
|
<date>2021-02-27</date>
|
|
<initials>fs, jsc</initials>
|
|
<remark>
|
|
<p>
|
|
Clarify that the 'reported' element must appear before any
|
|
'item' element.
|
|
</p>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.11.0</version>
|
|
<date>2020-09-29</date>
|
|
<initials>fs, jsc</initials>
|
|
<remark><p>Further clarify the presence requirements for the type attribute on fields.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.10.0</version>
|
|
<date>2020-05-05</date>
|
|
<initials>fs</initials>
|
|
<remark><p>Clarify that fields which are not required may be omitted on submission.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.9</version>
|
|
<date>2007-08-13</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified the definition and handling of the list-multi and list-single field types; specified that hidden field values should not be modified unless such behavior is defined for the using protocol; specified that a submission should include all fields provided in the empty form and may include additional fields, but that additional fields must be ignored if not understood by the form-processing entity.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.8</version>
|
|
<date>2007-05-21</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Removed mentions of presence stanzas; added section on discovering support; added section on substantive changes in Final state.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.7</version>
|
|
<date>2006-01-25</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Incorporated errata: (1) clarified rules regarding inclusion of option and value elements depending on field type; (2) clarified handling of default values; (3) added value elements to list-multi field in Example 2; (4) harmonized spelling of form-processing entity and form-submitting entity.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.6</version>
|
|
<date>2004-10-13</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Incorporated errata: (1) corrected syntax of <reported/> element (<field/> element should not contain a <value/> child); (2) corrected Example 8.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.5</version>
|
|
<date>2004-05-07</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified terminology regarding form-processing entities and form-submitting entities; corrected several small errors in the schema.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.4</version>
|
|
<date>2004-05-04</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Per discussion by the authors and Jabber Council, specified that the 'var' attribute is required for all field types except "fixed", for which the 'var' attribute is optional.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.3</version>
|
|
<date>2004-03-31</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Formalization and further editorial revisions.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.2</version>
|
|
<date>2004-01-22</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Editorial revisions.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.1</version>
|
|
<date>2003-02-16</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added schema.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.0</version>
|
|
<date>2002-12-09</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Per a vote of the Jabber Council, changed status to Final.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.1</version>
|
|
<date>2002-10-15</date>
|
|
<initials>rwe</initials>
|
|
<remark><p>Call for Experience changes (see <link url="#draft-changes">Changes in Draft State</link> section). This version voted to Final on 2002-12-09.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.0</version>
|
|
<date>2002-04-24</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Per a vote of the Jabber Council, changed status to Draft.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2002-03-15</date>
|
|
<initials>rwe</initials>
|
|
<remark><p>Protocol tweaks based on Standards list discussion.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.5</version>
|
|
<date>2002-02-06</date>
|
|
<initials>rwe</initials>
|
|
<remark><p>Protocol tweaks based on implementation and discussion.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2001-11-16</date>
|
|
<initials>rwe</initials>
|
|
<remark><p>Major redesign to attempt to clarify the scope of this document and limit what it is trying to solve.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2001-07-23</date>
|
|
<initials>rwe</initials>
|
|
<remark><p>Protocol update</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2001-06-29</date>
|
|
<initials>rwe</initials>
|
|
<remark><p>Protocol update and DocBook version</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2001-01-25</date>
|
|
<initials>rwe</initials>
|
|
<remark><p>Initial release</p></remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>Several existing Jabber/XMPP protocols involve the exchange of structured data between users and applications for common tasks such as registration (&xep0077;) and searching (&xep0055;). Unfortunately, these early protocols were "hard coded" and thus place significant restrictions on the range of information that can be exchanged. Furthermore, other protocols (e.g., &xep0045;) may need to exchange data for purposes such as configuration, but the configuration options may differ depending on the specific implementation or deployment. Finally, developers may want to extend other protocols (e.g., &xep0030;) in a flexible manner in order to provide information that is not defined in the base protocol. In all of these cases, it would be helpful to use a generic data description format that can be used for dynamic forms generation and data "modelling" in a variety of circumstances.</p>
|
|
<p>An example may be helpful. Let us imagine that when a user creates a multi-user chatroom on a text conferencing service, the service allows the user to configure the room in various ways. While most implementations will probably provide a somewhat common set of configurable features (discussion logging, maximum number of room occupants, etc.), there will be some divergence: perhaps one implementation will enable archiving of the room log in a variety of file types (XML, HTML, PDF, etc.) and for a variety of time periods (hourly, daily, weekly, etc.), whereas another implementation may present a boolean on/off choice of logging in only one format (e.g., daily logs saved in HTML). Obviously, the first implementation will have more configuration options than the second implementation. Rather than "hard-coding" every option via distinct XML elements (e.g., <room_logging_period/>), a better design would involve a more flexible format.</p>
|
|
<p>The 'jabber:x:data' protocol described herein defines such a flexible format for use by Jabber/XMPP entities, steering a middle course between the simplicity of "name-value" pairs and the complexity of &w3xforms; (on which development had just begun when this protocol was designed). In many ways, 'jabber:x:data' is similar to the Forms Module of &w3xhtml;; however, it provides several Jabber-specific data types, enables applications to require data fields, integrates more naturally into the "workflow" semantics of IQ stanzas, and can be included as an extension of existing Jabber/XMPP protocols in ways that the XHTML Forms Module could not when this protocol was developed (especially because &w3xhtmlmod; did not exist at that time).</p>
|
|
</section1>
|
|
<section1 topic='Requirements' anchor='reqs'>
|
|
<p>This document addresses the following requirements:</p>
|
|
<ol>
|
|
<li><strong>Data Gathering</strong> -- the protocol should enable a form-processing entity (commonly a server, service, or bot) to gather data from a form-submitting entity (commonly a client controlled by a human user); this should be done via distinct data fields (e.g., items in a questionnaire or configuration form), each of which can be a different data "type" and enable free-form input or a choice between multiple options (as is familiar from HTML forms).</li>
|
|
<li><strong>Data Reporting</strong> -- the protocol should enable a form-processing entity to report data (e.g., search results) to a form-submitting entity, again via distinct data fields.</li>
|
|
<li><strong>Portability</strong> -- the protocol should as much as possible define generic data formats and basic datatypes only; hints may be provided regarding the user interface, but they should be hints only and not hard-and-fast requirements.</li>
|
|
<li><strong>Simplicity</strong> -- the protocol should be simple for clients to implement, and most of the complexity (e.g., data validation and processing) should be the responsibility of servers and components rather than clients.</li>
|
|
<li><strong>Flexibility</strong> -- the protocol should be flexible and extensible rather than "hard-coded".</li>
|
|
<li><strong>Compatibility</strong> -- the protocol should define an extension to existing Jabber/XMPP protocols and not break existing implementations unless absolutely necessary.</li>
|
|
</ol>
|
|
</section1>
|
|
<section1 topic='Protocol' anchor='protocol'>
|
|
<p>The base syntax for the 'jabber:x:data' namespace is as follows (a formal description can be found in the <link url="#schema">XML Schema</link> section below):</p>
|
|
<code><![CDATA[
|
|
<x xmlns='jabber:x:data'
|
|
type='{form-type}'>
|
|
<title/>
|
|
<instructions/>
|
|
<field var='field-name'
|
|
type='{field-type}'
|
|
label='description'>
|
|
<desc/>
|
|
<required/>
|
|
<value>field-value</value>
|
|
<option label='option-label'><value>option-value</value></option>
|
|
<option label='option-label'><value>option-value</value></option>
|
|
</field>
|
|
</x>
|
|
]]></code>
|
|
<p>The &X; element qualified by the 'jabber:x:data' namespace SHOULD be included either directly as a first-level child of a &MESSAGE; stanza or as a second-level child of an &IQ; stanza (where the first-level child is an element qualified by a "wrapper" namespace); see also the restrictions enumerated below.</p>
|
|
<p>The OPTIONAL <title/> and <instructions/> elements enable the form-processing entity to label the form as a whole and specify natural-language instructions to be followed by the form-submitting entity. The XML character data for these elements SHOULD NOT contain newlines (the \n and \r characters), and any handling of newlines (e.g., presentation in a user interface) is unspecified herein; however, multiple instances of the <instructions/> element MAY be included.</p>
|
|
<section2 topic='Form Types' anchor='protocol-formtypes'>
|
|
<p>The data gathered or provided in a 'jabber:x:data' form can be situated in a number of different contexts. Examples include an empty form that needs to be filled out, a completed form, the results of a submission, a search result, or simply a set of data that is encapsulated using the 'jabber:x:data' namespace. The full context for the data is provided by three things:</p>
|
|
<ol>
|
|
<li>the "wrapper" protocol (i.e., the namespace whose root element is the direct child of the &IQ; stanza and the parent of the &X; element qualified by the 'jabber:x:data' namespace)</li>
|
|
<li>the place of the form within a transaction (e.g., an IQ "set" or "result") or structured conversation (e.g., a message <thread/>)</li>
|
|
<li>the 'type' attribute on the form's root &X; element</li>
|
|
</ol>
|
|
<p>The first two pieces of contextual information are provided by other protocols, whereas the form types are described in the following table.</p>
|
|
<table caption='Form Types'>
|
|
<tr>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>form</td>
|
|
<td>The form-processing entity is asking the form-submitting entity to complete a form.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>submit</td>
|
|
<td>The form-submitting entity is submitting data to the form-processing entity. The submission MAY include fields that were not provided in the empty form, but the form-processing entity MUST ignore any fields that it does not understand. Furthermore, the submission MAY omit fields not marked with <required/> by the form-processing entity.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>cancel</td>
|
|
<td>The form-submitting entity has cancelled submission of data to the form-processing entity.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>result</td>
|
|
<td>The form-processing entity is returning data (e.g., search results) to the form-submitting entity, or the data is a generic data set.</td>
|
|
</tr>
|
|
</table>
|
|
<p>In order to maintain the context of the data as captured in the form type, the following rules MUST be observed:</p>
|
|
<ul>
|
|
<li><p>For &IQ; stanzas, the root element qualified by the "wrapper" namespace in a form of type "form" or "submit" MUST be returned in a form of type "result". The &X; element qualified by the 'jabber:x:data' namespace MUST be a child of the "wrapper" namespace's root element. As defined in &xmppcore;, the 'id' attribute MUST be copied in the IQ result. For data forms of type "form" or "result", the &IQ; stanza SHOULD be of type "result". For data forms of type "submit" or "cancel", the &IQ; stanza SHOULD be of type "set".</p></li>
|
|
<li><p>For &MESSAGE; stanzas, the <thread/> SHOULD be copied in the reply if provided. The &X; element qualified by the 'jabber:x:data' namespace MUST be a child of the &MESSAGE; stanza.</p></li>
|
|
</ul>
|
|
</section2>
|
|
<section2 topic='The Field Element' anchor='protocol-field'>
|
|
<p>A data form of type "form", "submit", or "result" SHOULD contain at least one <field/> element; a data form of type "cancel" SHOULD NOT contain any <field/> elements.</p>
|
|
<p>The <field/> element MAY contain any of the following child elements:</p>
|
|
<dl>
|
|
<di><dt><desc/></dt><dd>The XML character data of this element provides a natural-language description of the field, intended for presentation in a user-agent (e.g., as a "tool-tip", help button, or explanatory text provided near the field). The <desc/> element SHOULD NOT contain newlines (the \n and \r characters), since layout is the responsibility of a user agent, and any handling of newlines (e.g., presentation in a user interface) is unspecified herein. (Note: To provide a description of a field, it is RECOMMENDED to use a <desc/> element rather than a separate <field/> element of type "fixed".)</dd></di>
|
|
<di><dt><required/></dt><dd>This element, which MUST be empty, flags the field as required in order for the form to be considered valid.</dd></di>
|
|
<di><dt><value/></dt><dd>The XML character data of this element defines the default value for the field (according to the form-processing entity) in a data form of type "form", the data provided by a form-submitting entity in a data form of type "submit", or a data result in a data form of type "result". In data forms of type "form", if the form-processing entity provides a default value via the <value/> element, then the form-submitting entity SHOULD NOT attempt to enforce a different default value (although it MAY do so to respect user preferences or anticipate expected user input). Fields of type list-multi, jid-multi, text-multi, and hidden MAY contain more than one <value/> element; all other field types MUST NOT contain more than one <value/> element.</dd></di>
|
|
<di><dt><option/></dt><dd>One of the options in a field of type "list-single" or "list-multi". The XML character of the <value/> child defines the option value, and the 'label' attribute defines a human-readable name for the option. The <option/> element MUST contain one and only one <value/> child. If the field is not of type "list-single" or "list-multi", it MUST NOT contain an <option/> element.</dd></di>
|
|
</dl>
|
|
<p>If the <field/> element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The <field/> element MAY possess a 'label' attribute that defines a human-readable name for the field.</p>
|
|
<p>The 'type' attribute defines the data "type" of the field data. The following rules apply for that attribute:</p>
|
|
<ul>
|
|
<li>For data forms of type "form", each <field/> element SHOULD possess a 'type' attribute. If the 'type' attribute is absent, the default of "text-single" is to be applied.</li>
|
|
<li>For data forms of type "submit", "result" or "error", the recieving entity can infer the 'type' attribute value from context. Nevertheless, the 'type' attribute MAY be present for clarity. Note that forms of type "error" SHOULD NOT have any <field/> elements.</li>
|
|
</ul>
|
|
<p>If fields are presented in a user interface (e.g., as items in a questionnaire or form result), the order of the field elements in the XML SHOULD determine the order of items presented to the user.</p>
|
|
</section2>
|
|
<section2 topic='Field Types' anchor='protocol-fieldtypes'>
|
|
<p>The following field types represent data "types" that are commonly exchanged between Jabber/XMPP entities. These field types are not intended to be as comprehensive as the datatypes defined in, for example, &w3xmlschema2;, nor do they define user interface elements.</p>
|
|
<table caption='Field Types'>
|
|
<tr>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>boolean</td>
|
|
<td>The field enables an entity to gather or provide an either-or choice between two options. The default value is "false". &BOOLEANNOTE;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>fixed</td>
|
|
<td>The field is intended for data description (e.g., human-readable text such as "section" headers) rather than data gathering or provision. The <value/> child SHOULD NOT contain newlines (the \n and \r characters); instead an application SHOULD generate multiple fixed fields, each with one <value/> child.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>hidden</td>
|
|
<td>The field is not shown to the form-submitting entity, but instead is returned with the form. The form-submitting entity SHOULD NOT modify the value of a hidden field, but MAY do so if such behavior is defined for the "using protocol".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>jid-multi</td>
|
|
<td>The field enables an entity to gather or provide multiple Jabber IDs. Each provided JID SHOULD be unique (as determined by comparison that includes application of the Nodeprep, Nameprep, and Resourceprep profiles of Stringprep as specified in <cite>XMPP Core</cite>), and duplicate JIDs MUST be ignored. *</td>
|
|
</tr>
|
|
<tr>
|
|
<td>jid-single</td>
|
|
<td>The field enables an entity to gather or provide a single Jabber ID. *</td>
|
|
</tr>
|
|
<tr>
|
|
<td>list-multi</td>
|
|
<td>The field enables an entity to gather or provide one or more options from among many. A form-submitting entity chooses one or more items from among the options presented by the form-processing entity and MUST NOT insert new options. The form-submitting entity MUST NOT modify the order of items as received from the form-processing entity, since the order of items MAY be significant.**</td>
|
|
</tr>
|
|
<tr>
|
|
<td>list-single</td>
|
|
<td>The field enables an entity to gather or provide one option from among many. A form-submitting entity chooses one item from among the options presented by the form-processing entity and MUST NOT insert new options. **</td>
|
|
</tr>
|
|
<tr>
|
|
<td>text-multi</td>
|
|
<td>The field enables an entity to gather or provide multiple lines of text. ***</td>
|
|
</tr>
|
|
<tr>
|
|
<td>text-private</td>
|
|
<td>The field enables an entity to gather or provide a single line or word of text, which shall be obscured in an interface (e.g., with multiple instances of the asterisk character).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>text-single</td>
|
|
<td>The field enables an entity to gather or provide a single line or word of text, which may be shown in an interface. This field type is the default and MUST be assumed if a form-submitting entity receives a field type it does not understand.</td>
|
|
</tr>
|
|
</table>
|
|
<p>* Note: Data provided for fields of type "jid-single" or "jid-multi" MUST contain one or more valid Jabber IDs, where validity is determined by the addressing rules defined in <cite>XMPP Core</cite> (see the <link url='#validation'>Data Validation</link> section below).</p>
|
|
<p>** Note: The <option/> elements in list-multi and list-single fields MUST be unique, where uniqueness is determined by the value of the 'label' attribute and the XML character data of the <value/> element (i.e., both must be unique).</p>
|
|
<p>*** Note: Data provided for fields of type "text-multi" SHOULD NOT contain any newlines (the \n and \r characters). Instead, the application SHOULD split the data into multiple strings (based on the newlines inserted by the platform), then specify each string as the XML character data of a distinct <value/> element. Similarly, an application that receives multiple <value/> elements for a field of type "text-multi" SHOULD merge the XML character data of the value elements into one text block for presentation to a user, with each string separated by a newline character as appropriate for that platform.</p>
|
|
</section2>
|
|
<section2 topic='Multiple Items in Form Results' anchor='protocol-results'>
|
|
<p>In some contexts (e.g., the results of a search request), it may be necessary to communicate multiple items. Therefore, a data form of type "result" MAY contain two child elements not described in the basic syntax above:</p>
|
|
<ol>
|
|
<li>One and only one <reported/> element, which can be understood as a "table header" describing the data to follow.</li>
|
|
<li>Zero or more <item/> elements, which can be understood as "table cells" containing data (if any) that matches the request.</li>
|
|
</ol>
|
|
<p>The <reported/> element MUST appear before any <item/> element inside the <x/> element. Forms of this type MUST NOT contain any top-level fields other than <reported/> and <item/>.</p>
|
|
<p class="box info">
|
|
Older revisions of this XEP (before 2.12.0) did not contain an explicit requirement for the ordering between <reported> and <item>. Implementations are therefore encouraged to be flexible when processing incoming data, as there might still be implementations which do not implement a strict ordering when generating reports.
|
|
Similarly, revisions of this XEP before 2.13.1 were ambiguous about whether <reported/> and <item/> elements could co-exist with other top level elements such as <field/> and <title/> and various implementations are known to have handled this in different ways.
|
|
</p>
|
|
<p>The syntax is as follows:</p>
|
|
<code><![CDATA[
|
|
<x xmlns='jabber:x:data'
|
|
type='result'>
|
|
<reported>
|
|
<field var='field-name' label='description' type='{field-type}'/>
|
|
</reported>
|
|
<item>
|
|
<field var='field-name'>
|
|
<value>field-value</value>
|
|
</field>
|
|
</item>
|
|
<item>
|
|
<field var='field-name'>
|
|
<value>field-value</value>
|
|
</field>
|
|
</item>
|
|
.
|
|
.
|
|
.
|
|
</x>
|
|
]]></code>
|
|
<p>Each of these <item/> elements and the <reported/> element MUST contain one or more <field/> children. The <reported/> element defines the data format for the result items by specifying the fields to be expected for each item; for this reason, its <field/> elements SHOULD possess a 'type' attribute and 'label' attribute in addition to the 'var' attribute, and SHOULD NOT contain a <value/> element. Each <item/> element defines one item in the result set, and MUST contain each field specified in the <reported/> element (although the XML character data of the <value/> element MAY be null).</p>
|
|
</section2>
|
|
<section2 topic='Incomplete Submission Form Handling' anchor='incomplete-submission-form-handling'>
|
|
<p>An incomplete submission form is a data form of the type "submit" that contains all required fields but some optional fields are omitted. The receiving entity of an incomplete submission form SHOULD only process (e.g., apply) the submitted fields. If applicable, the values of the omitted fields SHOULD keep their current value. The current value is often the value found in the corresponding form of the type "form".</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Data Validation' anchor='validation'>
|
|
<p>Data validation is the responsibility of the form-processing entity (commonly a server, service, or bot) rather than the form-submitting entity (commonly a client controlled by a human user). This helps to meet the requirement for keeping client implementations simple. If the form-processing entity determines that the data provided is not valid, it SHOULD return a "Not Acceptable" error, optionally providing a textual explanation in the XMPP <text/> element or an application-specific child element that identifies the problem (see &xep0086; for information about mappings and formats).</p>
|
|
</section1>
|
|
<section1 topic='Examples' anchor='examples'>
|
|
<p>For the sake of the following examples, let us suppose that there exists a bot hosting service on the Jabber network, located at <botster.shakespeare.lit>. This service enables registered users to create and configure new bots, find and interact with existing bots, and so on. We will assume that these interactions occur using the &xep0050; protocol, which is used as a "wrapper" protocol for data forms qualified by the 'jabber:x:data' namespace. The examples in the sections that follow show most of the features of the data forms protocol described above.</p>
|
|
<p>Note: Additional examples can be found in the specifications for various "using protocols", such as <cite>XEP-0045: Multi-User Chat</cite> and <cite>XEP-0055: Jabber Search</cite>.</p>
|
|
<section2 topic='Configuration' anchor='examples-config'>
|
|
<p>The first step is for a user to create a new bot on the hosting service. We will assume that this is done by sending a "create" command to the desired bot:</p>
|
|
<example caption="User Requests Bot Creation"><![CDATA[
|
|
<iq from='romeo@montague.net/home'
|
|
to='joogle@botster.shakespeare.lit'
|
|
type='get'
|
|
xml:lang='en'
|
|
id='create1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='create'
|
|
action='execute'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The hosting service then returns a data form to the user:</p>
|
|
<example caption="Service Returns Bot Creation Form"><![CDATA[
|
|
<iq from='joogle@botster.shakespeare.lit'
|
|
to='romeo@montague.net/home'
|
|
type='result'
|
|
xml:lang='en'
|
|
id='create1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='create'
|
|
sessionid='create:20040408T0128Z'
|
|
status='executing'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<title>Bot Configuration</title>
|
|
<instructions>Fill out this form to configure your new bot!</instructions>
|
|
<field type='hidden'
|
|
var='FORM_TYPE'>
|
|
<value>jabber:bot</value>
|
|
</field>
|
|
<field type='fixed'><value>Section 1: Bot Info</value></field>
|
|
<field type='text-single'
|
|
label='The name of your bot'
|
|
var='botname'/>
|
|
<field type='text-multi'
|
|
label='Helpful description of your bot'
|
|
var='description'/>
|
|
<field type='boolean'
|
|
label='Public bot?'
|
|
var='public'>
|
|
<required/>
|
|
</field>
|
|
<field type='text-private'
|
|
label='Password for special access'
|
|
var='password'/>
|
|
<field type='fixed'><value>Section 2: Features</value></field>
|
|
<field type='list-multi'
|
|
label='What features will the bot support?'
|
|
var='features'>
|
|
<option label='Contests'><value>contests</value></option>
|
|
<option label='News'><value>news</value></option>
|
|
<option label='Polls'><value>polls</value></option>
|
|
<option label='Reminders'><value>reminders</value></option>
|
|
<option label='Search'><value>search</value></option>
|
|
<value>news</value>
|
|
<value>search</value>
|
|
</field>
|
|
<field type='fixed'><value>Section 3: Subscriber List</value></field>
|
|
<field type='list-single'
|
|
label='Maximum number of subscribers'
|
|
var='maxsubs'>
|
|
<value>20</value>
|
|
<option label='10'><value>10</value></option>
|
|
<option label='20'><value>20</value></option>
|
|
<option label='30'><value>30</value></option>
|
|
<option label='50'><value>50</value></option>
|
|
<option label='100'><value>100</value></option>
|
|
<option label='None'><value>none</value></option>
|
|
</field>
|
|
<field type='fixed'><value>Section 4: Invitations</value></field>
|
|
<field type='jid-multi'
|
|
label='People to invite'
|
|
var='invitelist'>
|
|
<desc>Tell all your friends about your new bot!</desc>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<p>The user then submits the configuration form:</p>
|
|
<example caption="User Submits Bot Creation Form"><![CDATA[
|
|
<iq from='romeo@montague.net/home'
|
|
to='joogle@botster.shakespeare.lit'
|
|
type='set'
|
|
xml:lang='en'
|
|
id='create2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='create'
|
|
sessionid='create:20040408T0128Z'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field type='hidden' var='FORM_TYPE'>
|
|
<value>jabber:bot</value>
|
|
</field>
|
|
<field type='text-single' var='botname'>
|
|
<value>The Jabber Google Bot</value>
|
|
</field>
|
|
<field type='text-multi' var='description'>
|
|
<value>This bot enables you to send requests to</value>
|
|
<value>Google and receive the search results right</value>
|
|
<value>in your Jabber client. It' really cool!</value>
|
|
<value>It even supports Google News!</value>
|
|
</field>
|
|
<field type='boolean' var='public'>
|
|
<value>0</value>
|
|
</field>
|
|
<field type='text-private' var='password'>
|
|
<value>v3r0na</value>
|
|
</field>
|
|
<field type='list-multi' var='features'>
|
|
<value>news</value>
|
|
<value>search</value>
|
|
</field>
|
|
<field type='list-single' var='maxsubs'>
|
|
<value>50</value>
|
|
</field>
|
|
<field type='jid-multi' var='invitelist'>
|
|
<value>juliet@capulet.com</value>
|
|
<value>benvolio@montague.net</value>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<p>The service then returns the results to the user:</p>
|
|
<example caption="Service Returns Bot Creation Result"><![CDATA[
|
|
<iq from='joogle@botster.shakespeare.lit'
|
|
to='romeo@montague.net/home'
|
|
type='result'
|
|
xml:lang='en'
|
|
id='create2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='create'
|
|
sessionid='create:20040408T0128Z'
|
|
status='completed'>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<field type='hidden' var='FORM_TYPE'>
|
|
<value>jabber:bot</value>
|
|
</field>
|
|
<field type='text-single' var='botname'>
|
|
<value>The Jabber Google Bot</value>
|
|
</field>
|
|
<field type='boolean' var='public'>
|
|
<value>0</value>
|
|
</field>
|
|
<field type='text-private' var='password'>
|
|
<value>v3r0na</value>
|
|
</field>
|
|
<field type='list-multi' var='features'>
|
|
<value>news</value>
|
|
<value>search</value>
|
|
</field>
|
|
<field type='list-single' var='maxsubs'>
|
|
<value>50</value>
|
|
</field>
|
|
<field type='jid-multi' var='invitelist'>
|
|
<value>juliet@capulet.com</value>
|
|
<value>benvolio@montague.net</value>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Search' anchor='examples-search'>
|
|
<p>Now that the user has created this search bot, let us suppose that one of the friends he has invited decides to try it out by sending a search request:</p>
|
|
<example caption="User Requests Search Form"><![CDATA[
|
|
<iq from='juliet@capulet.com/chamber'
|
|
to='joogle@botster.shakespeare.lit'
|
|
type='get'
|
|
xml:lang='en'
|
|
id='search1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='search'
|
|
action='execute'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service Returns Search Form"><![CDATA[
|
|
<iq from='joogle@botster.shakespeare.lit'
|
|
to='juliet@capulet.com/chamber'
|
|
type='result'
|
|
xml:lang='en'
|
|
id='search1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='search'
|
|
status='executing'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<title>Joogle Search</title>
|
|
<instructions>Fill out this form to search for information!</instructions>
|
|
<field type='text-single'
|
|
var='search_request'>
|
|
<required/>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="User Submits Search Form"><![CDATA[
|
|
<iq from='juliet@capulet.com/chamber'
|
|
to='joogle@botster.shakespeare.lit'
|
|
type='get'
|
|
xml:lang='en'
|
|
id='search2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='search'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field type='text-single' var='search_request'>
|
|
<value>verona</value>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service Returns Search Results"><![CDATA[
|
|
<iq from='joogle@botster.shakespeare.lit'
|
|
to='juliet@capulet.com/chamber'
|
|
type='result'
|
|
xml:lang='en'
|
|
id='search2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='search'
|
|
status='completed'>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<title>Joogle Search: verona</title>
|
|
<reported>
|
|
<field var='name'/>
|
|
<field var='url'/>
|
|
</reported>
|
|
<item>
|
|
<field var='name'>
|
|
<value>Comune di Verona - Benvenuti nel sito ufficiale</value>
|
|
</field>
|
|
<field var='url'>
|
|
<value>http://www.comune.verona.it/</value>
|
|
</field>
|
|
</item>
|
|
<item>
|
|
<field var='name'>
|
|
<value>benvenuto!</value>
|
|
</field>
|
|
<field var='url'>
|
|
<value>http://www.hellasverona.it/</value>
|
|
</field>
|
|
</item>
|
|
<item>
|
|
<field var='name'>
|
|
<value>Universita degli Studi di Verona - Home Page</value>
|
|
</field>
|
|
<field var='url'>
|
|
<value>http://www.univr.it/</value>
|
|
</field>
|
|
</item>
|
|
<item>
|
|
<field var='name'>
|
|
<value>Aeroporti del Garda</value>
|
|
</field>
|
|
<field var='url'>
|
|
<value>http://www.aeroportoverona.it/</value>
|
|
</field>
|
|
</item>
|
|
<item>
|
|
<field var='name'>
|
|
<value>Veronafiere - fiera di Verona</value>
|
|
</field>
|
|
<field var='url'>
|
|
<value>http://www.veronafiere.it/</value>
|
|
</field>
|
|
</item>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Service Discovery' anchor='disco'>
|
|
<p>If an entity supports inclusion of the &X; element qualified by the 'jabber:x:data' namespace as a direct child of the &MESSAGE; stanza type, it MUST report support by including a service discovery feature of "jabber:x:data" &NSNOTE; in response to a Service Discovery information request:</p>
|
|
<example caption="Service Discovery information request"><![CDATA[
|
|
<iq type='get'
|
|
from='romeo@montague.net/orchard'
|
|
to='juliet@capulet.com/balcony'
|
|
id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service Discovery information response"><![CDATA[
|
|
<iq type='result'
|
|
from='juliet@capulet.com/balcony'
|
|
to='romeo@montague.net/orchard'
|
|
id='disco1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='jabber:x:data'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If an entity supports data forms indirectly through inclusion of data forms in a wrapper namespace (rather than directly within a &MESSAGE; stanza), it MUST NOT advertise support for the 'jabber:x:data' namespace, since support is implicit in support for the wrapper protocol.</p>
|
|
</section1>
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>There are no security concerns related to this specification above and beyond those described in the relevant section of <cite>XMPP Core</cite>.</p>
|
|
</section1>
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<section2 topic='Protocol Namespaces' anchor='registrar-namespaces'>
|
|
<p>The ®ISTRAR; includes the 'jabber:x:data' namespace in its registry of protocol namespaces.</p>
|
|
</section2>
|
|
<section2 topic='Parameter Values' anchor='registrar-parameters'>
|
|
<p>The XMPP Registrar maintains a registry of parameter values related to the 'jabber:x:data' namespace, specifically as defined in &xep0068;; the registry is located at &FORMTYPES;.</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='XML Schema' anchor='schema'>
|
|
<p>This schema is descriptive, not normative.</p>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='jabber:x:data'
|
|
xmlns='jabber:x:data'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
XEP-0004: http://www.xmpp.org/extensions/xep-0004.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name='x'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name='instructions'
|
|
minOccurs='0'
|
|
maxOccurs='unbounded'
|
|
type='xs:string'/>
|
|
<xs:element name='title' minOccurs='0' type='xs:string'/>
|
|
<xs:element ref='field' minOccurs='0' maxOccurs='unbounded'/>
|
|
<xs:element ref='reported' minOccurs='0' maxOccurs='1'/>
|
|
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='type' use='required'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='cancel'/>
|
|
<xs:enumeration value='form'/>
|
|
<xs:enumeration value='result'/>
|
|
<xs:enumeration value='submit'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='field'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name='desc' minOccurs='0' type='xs:string'/>
|
|
<xs:element name='required' minOccurs='0' type='empty'/>
|
|
<xs:element ref='value' minOccurs='0' maxOccurs='unbounded'/>
|
|
<xs:element ref='option' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='label' type='xs:string' use='optional'/>
|
|
<xs:attribute name='type' use='optional'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='boolean'/>
|
|
<xs:enumeration value='fixed'/>
|
|
<xs:enumeration value='hidden'/>
|
|
<xs:enumeration value='jid-multi'/>
|
|
<xs:enumeration value='jid-single'/>
|
|
<xs:enumeration value='list-multi'/>
|
|
<xs:enumeration value='list-single'/>
|
|
<xs:enumeration value='text-multi'/>
|
|
<xs:enumeration value='text-private'/>
|
|
<xs:enumeration value='text-single'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
<xs:attribute name='var' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='option'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='value'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='label' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='value' type='xs:string'/>
|
|
|
|
<xs:element name='reported'>
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
When contained in a "reported" element, the "field" element
|
|
SHOULD NOT contain a "value" child.
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='field' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='item'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='field' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section1>
|
|
<section1 topic='Changes in Final State' anchor='final-changes'>
|
|
<p>The following substantive protocol changes have been made while this specification has been in the Final state:</p>
|
|
<ul>
|
|
<li>Specified that the 'var' attribute is required for all field types except "fixed", for which the 'var' attribute is optional.</li>
|
|
<li>Specified when to advertise support via service discovery.</li>
|
|
<li>Removed references to &PRESENCE; stanzas.</li>
|
|
</ul>
|
|
</section1>
|
|
<section1 topic='Changes in Draft State' anchor='draft-changes'>
|
|
<p>The following substantive protocol changes were made while this specification was in the Draft state:</p>
|
|
<ul>
|
|
<li>The <x/> element MAY be included directly in &MESSAGE; and &PRESENCE; stanzas.</li>
|
|
<li>The <x/> element MAY contain a <title/> child for forms and results.</li>
|
|
<li>The <x/> element MUST possess a 'type' attribute.</li>
|
|
<li>A <field/> element MAY be of type='jid-single'.</li>
|
|
<li>Results MAY be reported back in <item/> tags.</li>
|
|
<li>Results MAY contain a <reported/> element with result set.</li>
|
|
<li>The <reported/> fields MAY possess a 'type' attribute to provide hints about how to interact with the data (type='jid-single' being the most useful).</li>
|
|
</ul>
|
|
</section1>
|
|
</xep>
|