XEP-0004: Data Forms
XEP-0004: Data Forms
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.
Authors
Ryan Eatmon
Joe Hildebrand
Jeremie Miller
Thomas Muldowney
Peter Saint-Andre
SEE LEGAL NOTICES
Status
Final
NOTICE: The protocol defined herein is a
Final Standard
of the XMPP Standards Foundation and can be considered a stable technology for implementation and deployment.
Type
Standards Track
Version
2.13.2 (2024-08-30)
Document Lifecycle
Experimental
Proposed
Stable
Final
1.
Introduction
Several existing Jabber/XMPP protocols involve the exchange of structured data between users and applications for common tasks such as registration (
In-Band Registration (XEP-0077)
]) and searching (
Jabber Search (XEP-0055)
]). 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.,
Multi-User Chat (XEP-0045)
]) 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.,
Service Discovery (XEP-0030)
]) 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.
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.,
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
XForms 1.0
] (on which development had just begun when this protocol was designed). In many ways, 'jabber:x:data' is similar to the Forms Module of
XHTML 1.0
]; 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
Modularization of XHTML
] did not exist at that time).
2.
Requirements
This document addresses the following requirements:
Data Gathering
-- 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).
Data Reporting
-- 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.
Portability
-- 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.
Simplicity
-- 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.
Flexibility
-- the protocol should be flexible and extensible rather than "hard-coded".
Compatibility
-- the protocol should define an extension to existing Jabber/XMPP protocols and not break existing implementations unless absolutely necessary.
3.
Protocol
The base syntax for the 'jabber:x:data' namespace is as follows (a formal description can be found in the
XML Schema
section below):
label='description'>
The
The OPTIONAL
3.1 Form Types
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:
the "wrapper" protocol (i.e., the namespace whose root element is the direct child of the
the place of the form within a transaction (e.g., an IQ "set" or "result") or structured conversation (e.g., a message
the 'type' attribute on the form's root
The first two pieces of contextual information are provided by other protocols, whereas the form types are described in the following table.
Table 1:
Form Types
Type
Description
form
The form-processing entity is asking the form-submitting entity to complete a form.
submit
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
cancel
The form-submitting entity has cancelled submission of data to the form-processing entity.
result
The form-processing entity is returning data (e.g., search results) to the form-submitting entity, or the data is a generic data set.
In order to maintain the context of the data as captured in the form type, the following rules MUST be observed:
For
XMPP Core
], the 'id' attribute MUST be copied in the IQ result. For data forms of type "form" or "result", the
For
3.2 The Field Element
A data form of type "form", "submit", or "result" SHOULD contain at least one
The
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
This element, which MUST be empty, flags the field as required in order for the form to be considered valid.
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
One of the options in a field of type "list-single" or "list-multi". The XML character of the
If the
The 'type' attribute defines the data "type" of the field data. The following rules apply for that attribute:
For data forms of type "form", each
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
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.
3.3 Field Types
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,
XML Schema Part 2
], nor do they define user interface elements.
Table 2:
Field Types
Type
Description
boolean
The field enables an entity to gather or provide an either-or choice between two options. The default value is "false". [
10
fixed
The field is intended for data description (e.g., human-readable text such as "section" headers) rather than data gathering or provision. The
hidden
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".
jid-multi
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
XMPP Core
), and duplicate JIDs MUST be ignored. *
jid-single
The field enables an entity to gather or provide a single Jabber ID. *
list-multi
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.**
list-single
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. **
text-multi
The field enables an entity to gather or provide multiple lines of text. ***
text-private
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).
text-single
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.
* 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
XMPP Core
(see the
Data Validation
section below).
** Note: The 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
*** 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
3.4 Multiple Items in Form Results
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:
One and only one
Zero or more
The
Older revisions of this XEP (before 2.12.0) did not contain an explicit requirement for the ordering between
Similarly, revisions of this XEP before 2.13.1 were ambiguous about whether
The syntax is as follows:
Each of these
3.5 Incomplete Submission Form Handling
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".
3.6 Setting empty or absent values
As specified in the previous section, the values of the omitted fields SHOULD keep their current value. From this, it follows that 'unsetting' a field value requires a request to contain a
This XEP does not standardize a way to differentiate between an "empty" and "absent" value. Unless other XEPs explicitly define these semantics, implementations can be expected to use a variety of representations, such as
4.
Data Validation
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
Error Condition Mappings (XEP-0086)
11
] for information about mappings and formats).
5.
Examples
For the sake of the following examples, let us suppose that there exists a bot hosting service on the Jabber network, located at
Ad-Hoc Commands (XEP-0050)
12
] 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.
Note: Additional examples can be found in the specifications for various "using protocols", such as
XEP-0045: Multi-User Chat
and
XEP-0055: Jabber Search
5.1 Configuration
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:
Example 1.
User Requests Bot Creation
type='get'
xml:lang='en'
id='create1'>
action='execute'/>
The hosting service then returns a data form to the user:
Example 2.
Service Returns Bot Creation Form
type='result'
xml:lang='en'
id='create1'>
sessionid='create:20040408T0128Z'
status='executing'>
var='botname'/>
var='description'/>
var='public'>
var='password'/>
var='features'>
var='maxsubs'>
var='invitelist'>
The user then submits the configuration form:
Example 3.
User Submits Bot Creation Form
type='set'
xml:lang='en'
id='create2'>
sessionid='create:20040408T0128Z'>
The service then returns the results to the user:
Example 4.
Service Returns Bot Creation Result
type='result'
xml:lang='en'
id='create2'>
sessionid='create:20040408T0128Z'
status='completed'>
5.2 Search
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:
Example 5.
User Requests Search Form
type='get'
xml:lang='en'
id='search1'>
action='execute'/>
Example 6.
Service Returns Search Form
type='result'
xml:lang='en'
id='search1'>
status='executing'>
Example 7.
User Submits Search Form
type='get'
xml:lang='en'
id='search2'>
Example 8.
Service Returns Search Results
type='result'
xml:lang='en'
id='search2'>
status='completed'>
6.
Service Discovery
If an entity supports inclusion of the
Protocol Namespaces
regarding issuance of one or more permanent namespaces) in response to a Service Discovery information request:
Example 9.
Service Discovery information request
to='juliet@capulet.com/balcony'
id='disco1'>
Example 10.
Service Discovery information response
to='romeo@montague.net/orchard'
id='disco1'>
...
...
If an entity supports data forms indirectly through inclusion of data forms in a wrapper namespace (rather than directly within a
7.
Security Considerations
There are no security concerns related to this specification above and beyond those described in the relevant section of
XMPP Core
8.
IANA Considerations
This document requires no interaction with the
Internet Assigned Numbers Authority (IANA)
13
].
9.
XMPP Registrar Considerations
9.1 Protocol Namespaces
The
XMPP Registrar
14
] includes the 'jabber:x:data' namespace in its registry of protocol namespaces.
9.2 Parameter Values
The XMPP Registrar maintains a registry of parameter values related to the 'jabber:x:data' namespace, specifically as defined in
Field Standardization for Data Forms (XEP-0068)
15
]; the registry is located at <
>.
10.
XML Schema
This schema is descriptive, not normative.
targetNamespace='jabber:x:data'
xmlns='jabber:x:data'
elementFormDefault='qualified'>
The protocol documented by this schema is defined in
XEP-0004: http://www.xmpp.org/extensions/xep-0004.html
maxOccurs='unbounded'
type='xs:string'/>
When contained in a "reported" element, the "field" element
SHOULD NOT contain a "value" child.
11.
Changes in Final State
The following substantive protocol changes have been made while this specification has been in the Final state:
Specified that the 'var' attribute is required for all field types except "fixed", for which the 'var' attribute is optional.
Specified when to advertise support via service discovery.
Removed references to
12.
Changes in Draft State
The following substantive protocol changes were made while this specification was in the Draft state:
The
The
The
A
Results MAY be reported back in
Results MAY contain a
The
Appendices
Appendix A: Document Information
Series
XEP
Number
0004
Publisher
XMPP Standards Foundation
Status
Final
Type
Standards Track
Version
2.13.2
2024-08-30
Approving Body
XMPP Council
Dependencies
XMPP Core
Supersedes
None
Superseded By
None
Short Name
x-data
Schema
Source Control
HTML
This document in other formats:
XML
Appendix B: Author Information
Ryan Eatmon
reatmon@jabber.org
JabberID
reatmon@jabber.org
Joe Hildebrand
jhildebr@cisco.com
JabberID
hildjj@jabber.org
Jeremie Miller
jer@jabber.org
JabberID
jer@jabber.org
Thomas Muldowney
temas@jabber.org
JabberID
temas@jabber.org
Peter Saint-Andre
stpeter@stpeter.im
JabberID
stpeter@jabber.org
URI
Appendix C: Legal Notices
This XMPP Extension Protocol is copyright © 1999 – 2024 by the
XMPP Standards Foundation
(XSF).
Permissions
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
Disclaimer of Warranty
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
Limitation of Liability
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
IPR Conformance
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <
> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
Visual Presentation
The HTML representation (you are looking at) is maintained by the XSF. It is based on the
YAML CSS Framework
, which is licensed under the terms of the
CC-BY-SA 2.0
license.
Appendix D: Relation to XMPP
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
Appendix E: Discussion Venue
The primary venue for discussion of XMPP Extension Protocols is the <
standards@xmpp.org
> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <
> for a complete list.
Errata can be sent to <
editor@xmpp.org
>.
Appendix F: Requirements Conformance
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in
BCP 14
RFC2119
RFC8174
] when,
and only when, they appear in all capitals, as shown here.
Appendix G: Notes
. XEP-0077: In-Band Registration <
>.
. XEP-0055: Jabber Search <
>.
. XEP-0045: Multi-User Chat <
>.
. XEP-0030: Service Discovery <
>.
. XForms 1.0 <
>.
. XHTML 1.0 <
>.
. Modularization of XHTML <
>.
. RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core <
>.
. XML Schema Part 2: Datatypes <
>.
10
. In accordance with Section 3.2.2.1 of
XML Schema Part 2: Datatypes
, the allowable lexical representations for the xs:boolean datatype are the strings "0" and "false" for the concept 'false' and the strings "1" and "true" for the concept 'true'; implementations MUST support both styles of lexical representation.
11
. XEP-0086: Error Condition Mappings <
>.
12
. XEP-0050: Ad-Hoc Commands <
>.
13
. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <
>.
14
. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <
>.
15
. XEP-0068: Field Data Standardization for Data Forms <
>.
Appendix H: Revision History
Note: Older versions of this specification might be available at
Version
2.13.2
(2024-08-30)
Add section on empty and absent values.
gk
Version
2.13.1
(2022-07-25)
Clarify elements allowed in multi-item data forms
ssw
Version
2.13.0
(2022-01-21)
Add incomplete submission form handling
melvo
Version
2.12.1
(2021-06-08)
Add missing "one" in a sentence (editorial).
ssw
Version
2.12.0
(2021-02-27)
Clarify that the 'reported' element must appear before any
'item' element.
fs, jsc
Version
2.11.0
(2020-09-29)
Further clarify the presence requirements for the type attribute on fields.
fs, jsc
Version
2.10.0
(2020-05-05)
Clarify that fields which are not required may be omitted on submission.
fs
Version
2.9
(2007-08-13)
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.
psa
Version
2.8
(2007-05-21)
Removed mentions of presence stanzas; added section on discovering support; added section on substantive changes in Final state.
psa
Version
2.7
(2006-01-25)
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.
psa
Version
2.6
(2004-10-13)
Incorporated errata: (1) corrected syntax of
psa
Version
2.5
(2004-05-07)
Clarified terminology regarding form-processing entities and form-submitting entities; corrected several small errors in the schema.
psa
Version
2.4
(2004-05-04)
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.
psa
Version
2.3
(2004-03-31)
Formalization and further editorial revisions.
psa
Version
2.2
(2004-01-22)
Editorial revisions.
psa
Version
2.1
(2003-02-16)
Added schema.
psa
Version
2.0
(2002-12-09)
Per a vote of the Jabber Council, changed status to Final.
psa
Version
1.1
(2002-10-15)
Call for Experience changes (see
Changes in Draft State
section). This version voted to Final on 2002-12-09.
rwe
Version
1.0
(2002-04-24)
Per a vote of the Jabber Council, changed status to Draft.
psa
Version
0.6
(2002-03-15)
Protocol tweaks based on Standards list discussion.
rwe
Version
0.5
(2002-02-06)
Protocol tweaks based on implementation and discussion.
rwe
Version
0.4
(2001-11-16)
Major redesign to attempt to clarify the scope of this document and limit what it is trying to solve.
rwe
Version
0.3
(2001-07-23)
Protocol update
rwe
Version
0.2
(2001-06-29)
Protocol update and DocBook version
rwe
Version
0.1
(2001-01-25)
Initial release
rwe
Appendix I: Bib(La)TeX Entry
@report{eatmon2001x-data,
title = {Data Forms},
author = {Eatmon, Ryan and Hildebrand, Joe and Miller, Jeremie and Muldowney, Thomas and Saint-Andre, Peter},
type = {XEP},
number = {0004},
version = {2.13.2},
institution = {XMPP Standards Foundation},
url = {https://xmpp.org/extensions/xep-0004.html},
date = {2001-01-25/2024-08-30},
END